diff options
233 files changed, 37126 insertions, 34055 deletions
diff --git a/_build/lang.map b/_build/lang.map new file mode 100644 index 00000000..e1f1aa63 --- /dev/null +++ b/_build/lang.map @@ -0,0 +1,5 @@ +c = c.lang +bash = sh.lang +erlang = erlang.lang +make = makefile.lang +makefile = makefile.lang diff --git a/_build/themes/ninenines/layouts/articles/single.html b/_build/themes/ninenines/layouts/articles/single.html index edeb63de..1eeda1e5 100644 --- a/_build/themes/ninenines/layouts/articles/single.html +++ b/_build/themes/ninenines/layouts/articles/single.html @@ -23,7 +23,9 @@ <h3>More articles</h3> <ul id="articles-nav" class="extra_margin"> {{ range (where $.Site.Pages "Type" "articles") }} - <li><a href="{{ .Permalink }}">{{ .Title }}</a></li> + {{ if ne .RelPermalink "/articles/" }} + <li><a href="{{ .Permalink }}">{{ .Title }}</a></li> + {{ end }} {{ end }} </ul> diff --git a/_build/themes/ninenines/layouts/docs/single.html b/_build/themes/ninenines/layouts/docs/single.html index 4bef64ca..9071d611 100644 --- a/_build/themes/ninenines/layouts/docs/single.html +++ b/_build/themes/ninenines/layouts/docs/single.html @@ -12,8 +12,11 @@ {{ if .Weight }} {{ if eq .Params.doctype "guide" }} - {{ $.Scratch.Set "prev" ((where (where (where $.Site.Pages ".Params.project" .Params.project) ".Params.doctype" .Params.doctype) ".Params.version" .Params.version).Prev .) }} - {{ $.Scratch.Set "next" ((where (where (where $.Site.Pages ".Params.project" .Params.project) ".Params.doctype" .Params.doctype) ".Params.version" .Params.version).Next .) }} + {{ $pages := where $.Site.Pages ".Params.project" .Params.project }} + {{ $pages := $pages | intersect (where $.Site.Pages ".Params.doctype" .Params.doctype) }} + {{ $pages := $pages | intersect (where $.Site.Pages ".Params.version" .Params.version) }} + {{ $.Scratch.Set "prev" ($pages.Prev .Page) }} + {{ $.Scratch.Set "next" ($pages.Next .Page) }} <nav style="margin:1em 0"> {{ if ($.Scratch.Get "prev").Weight }} diff --git a/_build/themes/ninenines/layouts/partials/head.html b/_build/themes/ninenines/layouts/partials/head.html index 3714bd72..af4710e3 100644 --- a/_build/themes/ninenines/layouts/partials/head.html +++ b/_build/themes/ninenines/layouts/partials/head.html @@ -16,7 +16,7 @@ <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"> - {{ if .RSSlink }} - <link rel="alternate" href="{{ .RSSlink }}" type="application/rss+xml" title="{{ .Site.Title }}" /> + {{ if .RSSLink }} + <link rel="alternate" href="{{ .RSSLink }}" type="application/rss+xml" title="{{ .Site.Title }}" /> {{ end }} </head> diff --git a/articles/cowboy-2.0.0-pre.4/index.html b/articles/cowboy-2.0.0-pre.4/index.html index 2158aa7a..2a23be43 100644 --- a/articles/cowboy-2.0.0-pre.4/index.html +++ b/articles/cowboy-2.0.0-pre.4/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Cowboy 2.0 pre-release 4</title> @@ -74,116 +74,116 @@ </p> </header> -<div class="paragraph"><p>Cowboy <code>2.0.0-pre.4</code> has been released!</p></div>
-<div class="paragraph"><p>This is the new recommended version of Cowboy.
-While I would not recommend putting it in production
-just yet, I do recommend you start writing new
-applications with this Cowboy version.</p></div>
-<div class="paragraph"><p>The most significant changes in the pre-release are:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-A new architecture: there now is one process per
- connection and one process per request. This was
- done because HTTP/2 allows running requests concurrently.
-</p>
-</li>
-<li>
-<p>
-Stream handlers. Every request, response and data goes
- through stream handlers. They are meant to replace hooks
- and more. They will be documented in a future pre-release.
- Check <code>cowboy_stream</code> and <code>cowboy_stream_h</code> if interested.
-</p>
-</li>
-<li>
-<p>
-Numerous changes to the <code>cowboy_req</code> interface. This
- is very close to final. Check the manual for what changed.
-</p>
-</li>
-<li>
-<p>
-The Req object is no longer passed in Websocket callbacks.
-</p>
-</li>
-<li>
-<p>
-It is now possible to send frames directly from <code>websocket_init/1</code>.
-</p>
-</li>
-<li>
-<p>
-SPDY support was removed, now that we have HTTP/2.
-</p>
-</li>
-<li>
-<p>
-Update Ranch to 1.3. We still depend on Cowlib master
- for the time being.
-</p>
-</li>
-<li>
-<p>
-A much improved manual.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>The manual received a lot of love. It now has one page per
-function with a detailed description, arguments list, return
-value, changelog and examples. It also links to the other
-relevant manual pages: <a href="https://ninenines.eu/docs/en/cowboy/2.0/manual/">https://ninenines.eu/docs/en/cowboy/2.0/manual/</a></p></div>
-<div class="paragraph"><p>I am quite proud of the manual right now. While more
-improvements can be made, what we have now is way better
-than before. Feedback for further improvements is welcome!</p></div>
-<div class="paragraph"><p>This is a significant step toward Cowboy 2.0. Almost all
-the breaking changes are in. A few more pre-releases are
-planned and will be released on a weekly basis (with exceptions).</p></div>
-<div class="paragraph"><p>Cowboy is now tested and supported with Erlang/OTP 18.0 or above
-on Arch Linux, FreeBSD, OSX, Ubuntu and Windows 7. Contact me
-if you can provide permanent access to another platform for the
-purposes of testing.</p></div>
-<div class="paragraph"><p>Cowboy is now available from four locations:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="https://git.ninenines.eu/cowboy.git">https://git.ninenines.eu/cowboy.git</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://github.com/ninenines/cowboy.git">https://github.com/ninenines/cowboy.git</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://bitbucket.org/ninenines/cowboy.git">https://bitbucket.org/ninenines/cowboy.git</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://gitlab.com/ninenines/cowboy.git">https://gitlab.com/ninenines/cowboy.git</a>
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>They are updated at the same time so there is no real difference.</p></div>
-<div class="paragraph"><p>Cowboy 2.0 will be released once all the breaking changes
-are completed and the temporarily removed features are
-added back.</p></div>
-<div class="paragraph"><p>Thanks for your patience. I know it took a long time.</p></div>
-<hr/>
-<div class="paragraph"><p>Half-price on all donations because I need a new hat:</p></div>
-<form action="https://www.paypal.com/cgi-bin/webscr" method="post" style="display:inline">
-<input type="hidden" name="cmd" value="_donations">
-<input type="hidden" name="business" value="[email protected]">
-<input type="hidden" name="lc" value="FR">
-<input type="hidden" name="item_name" value="Loic Hoguin">
-<input type="hidden" name="item_number" value="99s">
-<input type="hidden" name="currency_code" value="EUR">
-<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHosted">
-<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
-<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1">
-</form>
+<div class="paragraph"><p>Cowboy <code>2.0.0-pre.4</code> has been released!</p></div> +<div class="paragraph"><p>This is the new recommended version of Cowboy. +While I would not recommend putting it in production +just yet, I do recommend you start writing new +applications with this Cowboy version.</p></div> +<div class="paragraph"><p>The most significant changes in the pre-release are:</p></div> +<div class="ulist"><ul> +<li> +<p> +A new architecture: there now is one process per + connection and one process per request. This was + done because HTTP/2 allows running requests concurrently. +</p> +</li> +<li> +<p> +Stream handlers. Every request, response and data goes + through stream handlers. They are meant to replace hooks + and more. They will be documented in a future pre-release. + Check <code>cowboy_stream</code> and <code>cowboy_stream_h</code> if interested. +</p> +</li> +<li> +<p> +Numerous changes to the <code>cowboy_req</code> interface. This + is very close to final. Check the manual for what changed. +</p> +</li> +<li> +<p> +The Req object is no longer passed in Websocket callbacks. +</p> +</li> +<li> +<p> +It is now possible to send frames directly from <code>websocket_init/1</code>. +</p> +</li> +<li> +<p> +SPDY support was removed, now that we have HTTP/2. +</p> +</li> +<li> +<p> +Update Ranch to 1.3. We still depend on Cowlib master + for the time being. +</p> +</li> +<li> +<p> +A much improved manual. +</p> +</li> +</ul></div> +<div class="paragraph"><p>The manual received a lot of love. It now has one page per +function with a detailed description, arguments list, return +value, changelog and examples. It also links to the other +relevant manual pages: <a href="https://ninenines.eu/docs/en/cowboy/2.0/manual/">https://ninenines.eu/docs/en/cowboy/2.0/manual/</a></p></div> +<div class="paragraph"><p>I am quite proud of the manual right now. While more +improvements can be made, what we have now is way better +than before. Feedback for further improvements is welcome!</p></div> +<div class="paragraph"><p>This is a significant step toward Cowboy 2.0. Almost all +the breaking changes are in. A few more pre-releases are +planned and will be released on a weekly basis (with exceptions).</p></div> +<div class="paragraph"><p>Cowboy is now tested and supported with Erlang/OTP 18.0 or above +on Arch Linux, FreeBSD, OSX, Ubuntu and Windows 7. Contact me +if you can provide permanent access to another platform for the +purposes of testing.</p></div> +<div class="paragraph"><p>Cowboy is now available from four locations:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="https://git.ninenines.eu/cowboy.git">https://git.ninenines.eu/cowboy.git</a> +</p> +</li> +<li> +<p> +<a href="https://github.com/ninenines/cowboy.git">https://github.com/ninenines/cowboy.git</a> +</p> +</li> +<li> +<p> +<a href="https://bitbucket.org/ninenines/cowboy.git">https://bitbucket.org/ninenines/cowboy.git</a> +</p> +</li> +<li> +<p> +<a href="https://gitlab.com/ninenines/cowboy.git">https://gitlab.com/ninenines/cowboy.git</a> +</p> +</li> +</ul></div> +<div class="paragraph"><p>They are updated at the same time so there is no real difference.</p></div> +<div class="paragraph"><p>Cowboy 2.0 will be released once all the breaking changes +are completed and the temporarily removed features are +added back.</p></div> +<div class="paragraph"><p>Thanks for your patience. I know it took a long time.</p></div> +<hr/> +<div class="paragraph"><p>Half-price on all donations because I need a new hat:</p></div> +<form action="https://www.paypal.com/cgi-bin/webscr" method="post" style="display:inline"> +<input type="hidden" name="cmd" value="_donations"> +<input type="hidden" name="business" value="[email protected]"> +<input type="hidden" name="lc" value="FR"> +<input type="hidden" name="item_name" value="Loic Hoguin"> +<input type="hidden" name="item_number" value="99s"> +<input type="hidden" name="currency_code" value="EUR"> +<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHosted"> +<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!"> +<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1"> +</form> </article> </div> @@ -192,55 +192,107 @@ added back.</p></div> <h3>More articles</h3> <ul id="articles-nav" class="extra_margin"> - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + - <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + + <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + - <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + + <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + - <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + + <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + - <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + + <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + - <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + + <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + - <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + + <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + - <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + + <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + - <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + + <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + - <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + + <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + - <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + + </ul> diff --git a/articles/cowboy-2.0.0-rc.1/index.html b/articles/cowboy-2.0.0-rc.1/index.html index 4c06a670..dd1c6584 100644 --- a/articles/cowboy-2.0.0-rc.1/index.html +++ b/articles/cowboy-2.0.0-rc.1/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Cowboy 2.0 release candidate 1</title> @@ -74,62 +74,62 @@ </p> </header> -<div class="paragraph"><p>Cowboy <code>2.0.0-rc.1</code> has been released!</p></div>
-<div class="paragraph"><p>This is the new recommended version of Cowboy.
-Its API should not change before release. While
-you probably should not use it in production yet,
-many do successfully. Use at your own risk.</p></div>
-<div class="paragraph"><p>The plan is to have a new RC version every couple
-weeks until the summer ends or later if there are
-still blocking issues open. Only issues that can’t
-be fixed without making breaking changes to the
-interface may block the release.</p></div>
-<div class="paragraph"><p>Numerous changes were made since Cowboy 1.0. The
-one most people care about is probably HTTP/2, but
-it’s most likely not the only one worthwhile. The
-full list of changes (excluding types) can be found
-in the user guide chapter
-<a href="https://ninenines.eu/docs/en/cowboy/2.0/guide/migrating_from_1.0/">Migrating from Cowboy 1.0 to 2.0</a>.</p></div>
-<div class="paragraph"><p>As this is not the full release just yet, please pay
-extra attention to details and report anything
-suspicious you find.</p></div>
-<div class="paragraph"><p>There are still some tests failing. Most of those are
-related to standards that are not being followed perfectly
-just yet. Some of those will probably not be fixed before
-Cowboy 2.0 is released. They are edge cases and should not
-prevent interoperability.</p></div>
-<div class="paragraph"><p>The manual received a lot of love. It now has one page per
-function with a detailed description, arguments list, return
-value, changelog and examples. It also links to the other
-relevant manual pages: <a href="https://ninenines.eu/docs/en/cowboy/2.0/manual/">https://ninenines.eu/docs/en/cowboy/2.0/manual/</a></p></div>
-<div class="paragraph"><p>Cowboy is now tested and supported with Erlang/OTP 19.0 or above
-on Arch Linux, FreeBSD, OSX, Ubuntu and Windows 7. Contact me
-if you can provide permanent access to another platform for the
-purposes of testing.</p></div>
-<div class="paragraph"><p>Cowboy is now available from four locations:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="https://git.ninenines.eu/cowboy.git">https://git.ninenines.eu/cowboy.git</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://github.com/ninenines/cowboy.git">https://github.com/ninenines/cowboy.git</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://bitbucket.org/ninenines/cowboy.git">https://bitbucket.org/ninenines/cowboy.git</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://gitlab.com/ninenines/cowboy.git">https://gitlab.com/ninenines/cowboy.git</a>
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>They are updated at the same time so there is no real difference.</p></div>
+<div class="paragraph"><p>Cowboy <code>2.0.0-rc.1</code> has been released!</p></div> +<div class="paragraph"><p>This is the new recommended version of Cowboy. +Its API should not change before release. While +you probably should not use it in production yet, +many do successfully. Use at your own risk.</p></div> +<div class="paragraph"><p>The plan is to have a new RC version every couple +weeks until the summer ends or later if there are +still blocking issues open. Only issues that can’t +be fixed without making breaking changes to the +interface may block the release.</p></div> +<div class="paragraph"><p>Numerous changes were made since Cowboy 1.0. The +one most people care about is probably HTTP/2, but +it’s most likely not the only one worthwhile. The +full list of changes (excluding types) can be found +in the user guide chapter +<a href="https://ninenines.eu/docs/en/cowboy/2.0/guide/migrating_from_1.0/">Migrating from Cowboy 1.0 to 2.0</a>.</p></div> +<div class="paragraph"><p>As this is not the full release just yet, please pay +extra attention to details and report anything +suspicious you find.</p></div> +<div class="paragraph"><p>There are still some tests failing. Most of those are +related to standards that are not being followed perfectly +just yet. Some of those will probably not be fixed before +Cowboy 2.0 is released. They are edge cases and should not +prevent interoperability.</p></div> +<div class="paragraph"><p>The manual received a lot of love. It now has one page per +function with a detailed description, arguments list, return +value, changelog and examples. It also links to the other +relevant manual pages: <a href="https://ninenines.eu/docs/en/cowboy/2.0/manual/">https://ninenines.eu/docs/en/cowboy/2.0/manual/</a></p></div> +<div class="paragraph"><p>Cowboy is now tested and supported with Erlang/OTP 19.0 or above +on Arch Linux, FreeBSD, OSX, Ubuntu and Windows 7. Contact me +if you can provide permanent access to another platform for the +purposes of testing.</p></div> +<div class="paragraph"><p>Cowboy is now available from four locations:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="https://git.ninenines.eu/cowboy.git">https://git.ninenines.eu/cowboy.git</a> +</p> +</li> +<li> +<p> +<a href="https://github.com/ninenines/cowboy.git">https://github.com/ninenines/cowboy.git</a> +</p> +</li> +<li> +<p> +<a href="https://bitbucket.org/ninenines/cowboy.git">https://bitbucket.org/ninenines/cowboy.git</a> +</p> +</li> +<li> +<p> +<a href="https://gitlab.com/ninenines/cowboy.git">https://gitlab.com/ninenines/cowboy.git</a> +</p> +</li> +</ul></div> +<div class="paragraph"><p>They are updated at the same time so there is no real difference.</p></div> </article> </div> @@ -138,55 +138,107 @@ purposes of testing.</p></div> <h3>More articles</h3> <ul id="articles-nav" class="extra_margin"> - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + - <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + + <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + - <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + + <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + - <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + + <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + - <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + + <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + - <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + + <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + - <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + + <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + - <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + + <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + - <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + + <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + - <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + + <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + - <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + + </ul> diff --git a/articles/cowboy-2.0.0-rc.2/index.html b/articles/cowboy-2.0.0-rc.2/index.html index 51401e0f..b268f671 100644 --- a/articles/cowboy-2.0.0-rc.2/index.html +++ b/articles/cowboy-2.0.0-rc.2/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Cowboy 2.0 release candidate 2</title> @@ -74,41 +74,41 @@ </p> </header> -<div class="paragraph"><p>Cowboy <code>2.0.0-rc.2</code> has been released!</p></div>
-<div class="paragraph"><p>This is the new recommended version of Cowboy.
-Its API should not change before release. While
-you probably should not use it in production yet,
-many do successfully. Use at your own risk.</p></div>
-<div class="paragraph"><p>This new version contains fixes for the following
-issues:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-HTTP/2 server push was using the wrong header
- compression context.
-</p>
-</li>
-<li>
-<p>
-HTTP/2 flow control could end up queueing data
- in the wrong order when resuming the sending of
- data.
-</p>
-</li>
-<li>
-<p>
-The <code>shutdown</code> timeout was not implemented
- and request processes could be killed too quickly.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>What else is new in Cowboy 2.0? Check the
-<a href="/articles/cowboy-2.0.0-rc.1">rc.1 announcement</a>.</p></div>
-<div class="paragraph"><p>Please test this new release candidate and provide
-feedback! The best place to provide feedback is via
-tickets. Do not hesitate to open a ticket or bring
-an existing ticket to my attention to get it resolved
-before 2.0.</p></div>
+<div class="paragraph"><p>Cowboy <code>2.0.0-rc.2</code> has been released!</p></div> +<div class="paragraph"><p>This is the new recommended version of Cowboy. +Its API should not change before release. While +you probably should not use it in production yet, +many do successfully. Use at your own risk.</p></div> +<div class="paragraph"><p>This new version contains fixes for the following +issues:</p></div> +<div class="ulist"><ul> +<li> +<p> +HTTP/2 server push was using the wrong header + compression context. +</p> +</li> +<li> +<p> +HTTP/2 flow control could end up queueing data + in the wrong order when resuming the sending of + data. +</p> +</li> +<li> +<p> +The <code>shutdown</code> timeout was not implemented + and request processes could be killed too quickly. +</p> +</li> +</ul></div> +<div class="paragraph"><p>What else is new in Cowboy 2.0? Check the +<a href="/articles/cowboy-2.0.0-rc.1">rc.1 announcement</a>.</p></div> +<div class="paragraph"><p>Please test this new release candidate and provide +feedback! The best place to provide feedback is via +tickets. Do not hesitate to open a ticket or bring +an existing ticket to my attention to get it resolved +before 2.0.</p></div> </article> </div> @@ -117,55 +117,107 @@ before 2.0.</p></div> <h3>More articles</h3> <ul id="articles-nav" class="extra_margin"> - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + - <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + + <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + - <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + + <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + - <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + + <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + - <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + + <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + - <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + + <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + - <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + + <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + - <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + + <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + - <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + + <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + - <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + + <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + - <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + + </ul> diff --git a/articles/cowboy2-qs/index.html b/articles/cowboy2-qs/index.html index 5d26a2ee..f8064d1e 100644 --- a/articles/cowboy2-qs/index.html +++ b/articles/cowboy2-qs/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Cowboy 2.0 and query strings</title> @@ -74,155 +74,155 @@ </p> </header> -<div class="paragraph"><p>Now that Cowboy 1.0 is out, I can spend some of my time thinking
-about Cowboy 2.0 that will be released soon after Erlang/OTP 18.0.
-This entry discusses the proposed changes to query string handling
-in Cowboy.</p></div>
-<div class="paragraph"><p>Cowboy 2.0 will respond to user wishes by simplifying the interface
-of the <code>cowboy_req</code> module. Users want two things: less
-juggling with the Req variable, and more maps. Maps is the only
-dynamic key/value data structure in Erlang that we can match directly
-to extract values, allowing users to greatly simplify their code as
-they don’t need to call functions to do everything anymore.</p></div>
-<div class="paragraph"><p>Query strings are a good candidate for maps. It’s a list of
-key/values, so it’s pretty obvious we can win a lot by using maps.
-However query strings have one difference with maps: they can have
-duplicate keys.</p></div>
-<div class="paragraph"><p>How are we expected to handle duplicate keys? There’s no standard
-behavior. It’s up to applications. And looking at what is done in
-the wild, there’s no de facto standard either. While some ignore
-duplicate keys (keeping the first or the last they find), others
-require duplicate keys to end with <code>[]</code> to automatically
-put the values in a list, or even worse, languages like PHP even
-allow you to do things like <code>key[something][other]</code> and
-create a deep structure for it. Finally some allow any key to have
-duplicates and just gives you lists of key/values.</p></div>
-<div class="paragraph"><p>Cowboy so far had functions to retrieve query string values one
-value at a time, and if there were duplicates it would return the
-first it finds. It also has a function returning the entire list
-with all duplicates, allowing you to filter it to get all of them,
-and another function that returns the raw query string.</p></div>
-<div class="paragraph"><p>What are duplicates used for? Not that many things actually.</p></div>
-<div class="paragraph"><p>One use of duplicate keys is with HTML forms. It is common practice
-to give all related checkboxes the same name so you get a list of
-what’s been checked. When nothing is checked, nothing is sent at all,
-the key is not in the list.</p></div>
-<div class="paragraph"><p>Another use of duplicate keys is when generating forms. A good
-example of that would be a form that allows uploading any number
-of files. When you add a file, client-side code adds another field
-to the form. Repeat up to a certain limit.</p></div>
-<div class="paragraph"><p>And that’s about it. Of note is that HTML radio elements share
-the same name too, but only one key/value is sent, so they are not
-relevant here.</p></div>
-<div class="paragraph"><p>Normally this would be the part where I tell you how we solve
-this elegantly. But I had doubts. Why? Because there’s no good
-solutions to solving only this particular problem.</p></div>
-<div class="paragraph"><p>I then stopped thinking about duplicate keys for a minute and
-started to think about the larger problem.</p></div>
-<div class="paragraph"><p>Query strings are input data. They take a particular form,
-and may be sent as part of the URI or as part of the request
-body. We have other kinds of input data. We have headers and
-cookies and the request body in various forms. We also have
-path segments in URIs.</p></div>
-<div class="paragraph"><p>What do you do with input data? Well you use it to do
-something. But there is one thing that you almost always do
-(and if you don’t, you really should): you validate it and
-you map it into Erlang terms.</p></div>
-<div class="paragraph"><p>Cowboy left the user take care of validation and conversion
-into Erlang terms so far. Rather, it left the user take care
-of it everywhere except one place. Guess where? That’s right,
-bindings.</p></div>
-<div class="paragraph"><p>If you define routes with bindings then you have the option
-to provide constraints. Constraints can be used to do two things:
-validate the data and convert it in a more appropriate term. For
-example if you use the <code>int</code> constraint, Cowboy will
-make sure the binding is an integer, and will replace the value
-with the integer representation so that you can use it directly.
-In this particular case it not only routes the URI, but also
-validates and converts the bindings directly.</p></div>
-<div class="paragraph"><p>This is very relevant in the case of our duplicate keys,
-because if we have a list with duplicates of a key, chances
-are we want to convert that into a list of Erlang terms, and
-also make sure that all the elements in this list are expected.</p></div>
-<div class="paragraph"><p>The answer to this particular problem is simple. We need a
-function that will parse the query string and apply constraints.
-But this is not all, there is one other problem to be solved.</p></div>
-<div class="paragraph"><p>The other problem is that for the user some keys are mandatory
-and some are optional. Optional keys include the ones that
-correspond to HTML checkboxes: if the key for one or more
-checkbox is missing from the query string, we still want to
-have an empty list in our map so we can easily match. Matching
-maps is great, but not so much when values might be missing,
-so we have to normalize this data a little.</p></div>
-<div class="paragraph"><p>This problem is solved by allowing a default value. If the
-key is missing and a default exists, set it. If no default
-exists, then the key was mandatory and we want to crash.</p></div>
-<div class="paragraph"><p>I therefore make a proposal for changing the query string
-interface to three functions.</p></div>
-<div class="paragraph"><p>The first function already exists, it is <code>cowboy_req:qs(Req)</code>
-and it returns only the query string binary. No more Req returned.</p></div>
-<div class="paragraph"><p>The second function is a renaming of <code>cowboy_req:qs_vals(Req)</code>
-to something more explicit: <code>cowboy_req:parse_qs(Req)</code>.
-The new name implies that a parsing operation is done. It was implicit
-and cached before. It will be explicit and not cached anymore now.
-Again, no more Req returned.</p></div>
-<div class="paragraph"><p>The third function is the one I mentioned above. I think
-the interface <code>cowboy_req:match_qs(Req, Fields)</code> is
-most appropriate. It returns a normalized map that is the same
-regardless of optional fields being provided with the request,
-allowing for easy matching. It crashes if something went wrong.
-Still no Req returned.</p></div>
-<div class="paragraph"><p>I feel that this three function interface provides everything
-one would need to comfortably write applications. You can get
-low level and get the query string directly; you can get a list
-of key/value binaries without any additional processing and do it
-on your own; or you can get a processed map that contains Erlang
-terms ready to be used.</p></div>
-<div class="paragraph"><p>I strongly believe that by democratizing the constraints to
-more than just bindings, but also to query string, cookies and
-other key/values in Cowboy, we can allow the developer to quickly
-and easily go from HTTP request to Erlang function calls. The
-constraints are reusable functions that can serve as guards
-against unwanted data, providing convenience in the process.</p></div>
-<div class="paragraph"><p>Your handlers will not look like an endless series of calls
-to get and convert the input data, they will instead be just
-one call at the beginning followed by the actual application
-logic, thanks to constraints and maps.</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">handle</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- #{<span style="color: #FF6600">name</span><span style="color: #990000">:=</span><span style="color: #009900">Name</span>, <span style="color: #FF6600">email</span><span style="color: #990000">:=</span><span style="color: #009900">Email</span>, <span style="color: #FF6600">choices</span><span style="color: #990000">:=</span><span style="color: #009900">ChoicesList</span>, <span style="color: #FF6600">remember_me</span><span style="color: #990000">:=</span><span style="color: #009900">RememberMe</span>} <span style="color: #990000">=</span>
- <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_qs</span></span>(<span style="color: #009900">Req</span>, [
- <span style="font-weight: bold"><span style="color: #000080">name</span></span>, {<span style="color: #FF6600">email</span>, <span style="color: #FF6600">email</span>},
- {<span style="color: #FF6600">choices</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span> <span style="font-weight: bold"><span style="color: #000000">check_choices</span></span><span style="color: #990000">/</span><span style="color: #993399">1</span>, []},
- {<span style="color: #FF6600">remember_me</span>, <span style="color: #FF6600">boolean</span>, <span style="color: #000080">false</span>}]),
- <span style="font-weight: bold"><span style="color: #000000">save_choices</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Email</span>, <span style="color: #009900">ChoicesList</span>),
- <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #009900">RememberMe</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">create_account</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Email</span>); <span style="color: #000080">true</span> <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>,
- {<span style="color: #FF6600">ok</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">check_choices</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"blue"</span><span style="color: #990000">>></span>) <span style="color: #990000">-></span> {<span style="color: #000080">true</span>, <span style="color: #FF6600">blue</span>};
-<span style="font-weight: bold"><span style="color: #000000">check_choices</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"red"</span><span style="color: #990000">>></span>) <span style="color: #990000">-></span> {<span style="color: #000080">true</span>, <span style="color: #FF6600">red</span>};
-<span style="font-weight: bold"><span style="color: #000000">check_choices</span></span>(<span style="color: #990000">_</span>) <span style="color: #990000">-></span> <span style="color: #000080">false</span>;</tt></pre></div></div>
-<div class="paragraph"><p>(Don’t look too closely at the structure yet.)</p></div>
-<div class="paragraph"><p>As you can see in the above snippet, it becomes really easy
-to go from query string to values. You can also use the map
-directly as it is guaranteed to only contain the keys you
-specified, any extra key is not returned.</p></div>
-<div class="paragraph"><p>This would I believe be a huge step up as we can now
-focus on writing applications instead of translating HTTP
-calls. Cowboy can now take care of it.</p></div>
-<div class="paragraph"><p>And to conclude, this also solves our duplicate keys
-dilemma, as they now automatically become a list of binaries,
-and this list is then checked against constraints that
-will fail if they were not expecting a list. And in the
-example above, it even converts the values to atoms for
-easier manipulation.</p></div>
-<div class="paragraph"><p>As usual, feedback is more than welcome, and I apologize
-for the rocky structure of this post as it contains all the
-thoughts that went into this rather than just the conclusion.</p></div>
+<div class="paragraph"><p>Now that Cowboy 1.0 is out, I can spend some of my time thinking +about Cowboy 2.0 that will be released soon after Erlang/OTP 18.0. +This entry discusses the proposed changes to query string handling +in Cowboy.</p></div> +<div class="paragraph"><p>Cowboy 2.0 will respond to user wishes by simplifying the interface +of the <code>cowboy_req</code> module. Users want two things: less +juggling with the Req variable, and more maps. Maps is the only +dynamic key/value data structure in Erlang that we can match directly +to extract values, allowing users to greatly simplify their code as +they don’t need to call functions to do everything anymore.</p></div> +<div class="paragraph"><p>Query strings are a good candidate for maps. It’s a list of +key/values, so it’s pretty obvious we can win a lot by using maps. +However query strings have one difference with maps: they can have +duplicate keys.</p></div> +<div class="paragraph"><p>How are we expected to handle duplicate keys? There’s no standard +behavior. It’s up to applications. And looking at what is done in +the wild, there’s no de facto standard either. While some ignore +duplicate keys (keeping the first or the last they find), others +require duplicate keys to end with <code>[]</code> to automatically +put the values in a list, or even worse, languages like PHP even +allow you to do things like <code>key[something][other]</code> and +create a deep structure for it. Finally some allow any key to have +duplicates and just gives you lists of key/values.</p></div> +<div class="paragraph"><p>Cowboy so far had functions to retrieve query string values one +value at a time, and if there were duplicates it would return the +first it finds. It also has a function returning the entire list +with all duplicates, allowing you to filter it to get all of them, +and another function that returns the raw query string.</p></div> +<div class="paragraph"><p>What are duplicates used for? Not that many things actually.</p></div> +<div class="paragraph"><p>One use of duplicate keys is with HTML forms. It is common practice +to give all related checkboxes the same name so you get a list of +what’s been checked. When nothing is checked, nothing is sent at all, +the key is not in the list.</p></div> +<div class="paragraph"><p>Another use of duplicate keys is when generating forms. A good +example of that would be a form that allows uploading any number +of files. When you add a file, client-side code adds another field +to the form. Repeat up to a certain limit.</p></div> +<div class="paragraph"><p>And that’s about it. Of note is that HTML radio elements share +the same name too, but only one key/value is sent, so they are not +relevant here.</p></div> +<div class="paragraph"><p>Normally this would be the part where I tell you how we solve +this elegantly. But I had doubts. Why? Because there’s no good +solutions to solving only this particular problem.</p></div> +<div class="paragraph"><p>I then stopped thinking about duplicate keys for a minute and +started to think about the larger problem.</p></div> +<div class="paragraph"><p>Query strings are input data. They take a particular form, +and may be sent as part of the URI or as part of the request +body. We have other kinds of input data. We have headers and +cookies and the request body in various forms. We also have +path segments in URIs.</p></div> +<div class="paragraph"><p>What do you do with input data? Well you use it to do +something. But there is one thing that you almost always do +(and if you don’t, you really should): you validate it and +you map it into Erlang terms.</p></div> +<div class="paragraph"><p>Cowboy left the user take care of validation and conversion +into Erlang terms so far. Rather, it left the user take care +of it everywhere except one place. Guess where? That’s right, +bindings.</p></div> +<div class="paragraph"><p>If you define routes with bindings then you have the option +to provide constraints. Constraints can be used to do two things: +validate the data and convert it in a more appropriate term. For +example if you use the <code>int</code> constraint, Cowboy will +make sure the binding is an integer, and will replace the value +with the integer representation so that you can use it directly. +In this particular case it not only routes the URI, but also +validates and converts the bindings directly.</p></div> +<div class="paragraph"><p>This is very relevant in the case of our duplicate keys, +because if we have a list with duplicates of a key, chances +are we want to convert that into a list of Erlang terms, and +also make sure that all the elements in this list are expected.</p></div> +<div class="paragraph"><p>The answer to this particular problem is simple. We need a +function that will parse the query string and apply constraints. +But this is not all, there is one other problem to be solved.</p></div> +<div class="paragraph"><p>The other problem is that for the user some keys are mandatory +and some are optional. Optional keys include the ones that +correspond to HTML checkboxes: if the key for one or more +checkbox is missing from the query string, we still want to +have an empty list in our map so we can easily match. Matching +maps is great, but not so much when values might be missing, +so we have to normalize this data a little.</p></div> +<div class="paragraph"><p>This problem is solved by allowing a default value. If the +key is missing and a default exists, set it. If no default +exists, then the key was mandatory and we want to crash.</p></div> +<div class="paragraph"><p>I therefore make a proposal for changing the query string +interface to three functions.</p></div> +<div class="paragraph"><p>The first function already exists, it is <code>cowboy_req:qs(Req)</code> +and it returns only the query string binary. No more Req returned.</p></div> +<div class="paragraph"><p>The second function is a renaming of <code>cowboy_req:qs_vals(Req)</code> +to something more explicit: <code>cowboy_req:parse_qs(Req)</code>. +The new name implies that a parsing operation is done. It was implicit +and cached before. It will be explicit and not cached anymore now. +Again, no more Req returned.</p></div> +<div class="paragraph"><p>The third function is the one I mentioned above. I think +the interface <code>cowboy_req:match_qs(Req, Fields)</code> is +most appropriate. It returns a normalized map that is the same +regardless of optional fields being provided with the request, +allowing for easy matching. It crashes if something went wrong. +Still no Req returned.</p></div> +<div class="paragraph"><p>I feel that this three function interface provides everything +one would need to comfortably write applications. You can get +low level and get the query string directly; you can get a list +of key/value binaries without any additional processing and do it +on your own; or you can get a processed map that contains Erlang +terms ready to be used.</p></div> +<div class="paragraph"><p>I strongly believe that by democratizing the constraints to +more than just bindings, but also to query string, cookies and +other key/values in Cowboy, we can allow the developer to quickly +and easily go from HTTP request to Erlang function calls. The +constraints are reusable functions that can serve as guards +against unwanted data, providing convenience in the process.</p></div> +<div class="paragraph"><p>Your handlers will not look like an endless series of calls +to get and convert the input data, they will instead be just +one call at the beginning followed by the actual application +logic, thanks to constraints and maps.</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">handle</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + #{<span style="color: #FF6600">name</span><span style="color: #990000">:=</span><span style="color: #009900">Name</span>, <span style="color: #FF6600">email</span><span style="color: #990000">:=</span><span style="color: #009900">Email</span>, <span style="color: #FF6600">choices</span><span style="color: #990000">:=</span><span style="color: #009900">ChoicesList</span>, <span style="color: #FF6600">remember_me</span><span style="color: #990000">:=</span><span style="color: #009900">RememberMe</span>} <span style="color: #990000">=</span> + <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_qs</span></span>(<span style="color: #009900">Req</span>, [ + <span style="font-weight: bold"><span style="color: #000080">name</span></span>, {<span style="color: #FF6600">email</span>, <span style="color: #FF6600">email</span>}, + {<span style="color: #FF6600">choices</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span> <span style="font-weight: bold"><span style="color: #000000">check_choices</span></span><span style="color: #990000">/</span><span style="color: #993399">1</span>, []}, + {<span style="color: #FF6600">remember_me</span>, <span style="color: #FF6600">boolean</span>, <span style="color: #000080">false</span>}]), + <span style="font-weight: bold"><span style="color: #000000">save_choices</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Email</span>, <span style="color: #009900">ChoicesList</span>), + <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #009900">RememberMe</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">create_account</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Email</span>); <span style="color: #000080">true</span> <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>, + {<span style="color: #FF6600">ok</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">check_choices</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"blue"</span><span style="color: #990000">>></span>) <span style="color: #990000">-></span> {<span style="color: #000080">true</span>, <span style="color: #FF6600">blue</span>}; +<span style="font-weight: bold"><span style="color: #000000">check_choices</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"red"</span><span style="color: #990000">>></span>) <span style="color: #990000">-></span> {<span style="color: #000080">true</span>, <span style="color: #FF6600">red</span>}; +<span style="font-weight: bold"><span style="color: #000000">check_choices</span></span>(<span style="color: #990000">_</span>) <span style="color: #990000">-></span> <span style="color: #000080">false</span>;</tt></pre></div></div> +<div class="paragraph"><p>(Don’t look too closely at the structure yet.)</p></div> +<div class="paragraph"><p>As you can see in the above snippet, it becomes really easy +to go from query string to values. You can also use the map +directly as it is guaranteed to only contain the keys you +specified, any extra key is not returned.</p></div> +<div class="paragraph"><p>This would I believe be a huge step up as we can now +focus on writing applications instead of translating HTTP +calls. Cowboy can now take care of it.</p></div> +<div class="paragraph"><p>And to conclude, this also solves our duplicate keys +dilemma, as they now automatically become a list of binaries, +and this list is then checked against constraints that +will fail if they were not expecting a list. And in the +example above, it even converts the values to atoms for +easier manipulation.</p></div> +<div class="paragraph"><p>As usual, feedback is more than welcome, and I apologize +for the rocky structure of this post as it contains all the +thoughts that went into this rather than just the conclusion.</p></div> </article> </div> @@ -231,55 +231,107 @@ thoughts that went into this rather than just the conclusion.</p></div> <h3>More articles</h3> <ul id="articles-nav" class="extra_margin"> - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + + <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + - <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + + <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + - <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + + <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + - <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + + <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + - <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + + <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + - <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + + <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + - <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + + <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + - <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + + <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + - <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + + <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + - <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + + <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + - <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + </ul> diff --git a/articles/dont-let-it-crash/index.html b/articles/dont-let-it-crash/index.html index 239e479a..e86cb263 100644 --- a/articles/dont-let-it-crash/index.html +++ b/articles/dont-let-it-crash/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Don't let it crash</title> @@ -74,118 +74,118 @@ </p> </header> -<div class="paragraph"><p>We have a specific mindset when writing Erlang
-programs. We focus on the normal execution of the
-program and don’t handle most of the errors that may
-occur. We sometimes call this normal execution the
-<em>happy path</em>.</p></div>
-<div class="paragraph"><p>The general pattern behind writing only for the
-<em>happy path</em>, letting the VM catch errors (writing
-them to a log for future consumption) and then
-having a supervisor restart the processes that
-failed from a clean state, has a name. We call it
-<em>let it crash</em>; and it drives many of our design
-decisions.</p></div>
-<div class="paragraph"><p>It’s a really great way to program and the results
-are fantastic compared to most other programming
-languages. And yet, <em>let it crash</em> barely convinced
-anyone that they should use Erlang. Why would that
-be?</p></div>
-<div class="paragraph"><p>You may already know that Cowboy is capable of
-handling at least 2 million Websocket connections
-on a single server. This is in large part thanks
-to the capabilities of the VM. Still, 2 million
-is good, much better than most other servers can
-do.</p></div>
-<div class="paragraph"><p>Cowboy is not just a Websocket server; it’s also
-an HTTP and HTTP/2 server, and it handles many
-related features like long polling or the parsing
-of most request headers.</p></div>
-<div class="paragraph"><p>Can you guess how large the Cowboy codebase is,
-without looking at the source?</p></div>
-<div class="paragraph"><p>Do make sure you have a clear answer in your mind
-before you go check.</p></div>
-<div class="paragraph"><p>Good, you are back. Now what were the results? If
-I am correct, you overestimated the size of Cowboy.
-Cowboy is in fact about five thousand lines of code.
-You probably thought it was at least ten thousand.
-About eighty percent of readers will have
-overestimated the size of Cowboy. And you did only
-because I mentioned it can handle millions of
-Websocket connections.</p></div>
-<div class="paragraph"><p>Numerous studies show this effect. Just mentioning
-the large number already prepared your mind to think
-in that direction. Repeating the number made you
-focus even more on it. Then the question asked for
-a number, which ended up larger than the reality.</p></div>
-<div class="paragraph"><p>The same effect can be applied to negotiation for
-example. You generally want to start by giving your
-offer (and not let the other party initiate) and
-you want to give a really large number first. You
-can also prepare your customer by mentioning an even
-larger number in the previous discussion.</p></div>
-<div class="paragraph"><p>And it’s not just numbers either. An experiment
-showed that just by looking at an image of clouds,
-customers of a pillow store were buying pillows
-more comfortable (and more expensive) than those
-who didn’t see that image.</p></div>
-<div class="paragraph"><p>This is the power of associations. It is covered in
-much larger detail in the books
-<a href="https://www.amazon.com/Influence-Psychology-Persuasion-Robert-Cialdini/dp/006124189X">Influence</a>
-and
-<a href="https://www.amazon.com/Pre-Suasion-Revolutionary-Way-Influence-Persuade/dp/1501109790">Pre-suasion</a>.
-I highly recommend reading those and applying what
-you learn to your daily life. I’m definitely not
-a professional psychologist so take this post with
-a grain of salt.</p></div>
-<div class="paragraph"><p>When selling Erlang, whether we are selling it to
-a customer or trying to convince a developer friend
-to start using it, we often talk about how Erlang
-<em>lets you sleep at night</em>, that it is auto healing
-and always gets fantastic uptimes.</p></div>
-<div class="paragraph"><p>And then we talk about <em>let it crash</em>.</p></div>
-<div class="paragraph"><p>And we describe what it means.</p></div>
-<div class="paragraph"><p>We might as well just say that Erlang crashes a lot
-and then take the door. It would have the same effect.
-It doesn’t even stop at programs crashing. You know
-what else crashes? Cars, planes, trains. Often with
-disastrous consequences. Is that really the message
-we want to convey?</p></div>
-<div class="paragraph"><p>They even <a href="https://img.youtube.com/vi/oEUBW2lCkIk/0.jpg">printed it on a t-shirt</a>!
-Keep calm and let it crash. It’s the kind of t-shirt
-you probably shouldn’t wear in an airport, and for good
-reasons. A few people did, then realized what they were
-wearing and were not too smug about it.</p></div>
-<div class="paragraph"><p>And yet this is how we sell Erlang.</p></div>
-<div class="paragraph"><p>A better way would be to focus on the positives, of
-course, but also to make sure that those positives
-are phrased in a way that prevents bad associations
-to be formed in people’s minds.</p></div>
-<div class="paragraph"><p>Instead of <em>let it crash</em>, you can say that Erlang
-has <em>auto healing mechanisms</em>. Healing is a good
-thing and accurately describes what happens in the
-system.</p></div>
-<div class="paragraph"><p>Should you need to go into more details, you will
-probably want to avoid <em>recover from crashes</em> and
-instead say <em>recover from exceptions</em>. Exceptions
-are a pretty neutral word and, should you explain
-what you mean by that, you can talk about exceptions
-that occur for reasons unrelated to Erlang, like
-hardware failure or network instability.</p></div>
-<div class="paragraph"><p>The trick is to always use positive words and
-phrases to describe Erlang, and to use external
-factors to explain how Erlang deals with failures.
-Never mention the failures internal to Erlang
-systems unless you are asked specifically, in
-which case you can say that the auto healing
-applies to all exceptions.</p></div>
-<div class="paragraph"><p>The <em>let it crash</em> philosophy is great when
-learning Erlang or when writing fault-tolerant
-systems. But it’s not going to convince anyone
-to use it unless they were already looking for
-it.</p></div>
-<div class="paragraph"><p>Do you like this post? Tell me on Twitter. I might
-make more.</p></div>
+<div class="paragraph"><p>We have a specific mindset when writing Erlang +programs. We focus on the normal execution of the +program and don’t handle most of the errors that may +occur. We sometimes call this normal execution the +<em>happy path</em>.</p></div> +<div class="paragraph"><p>The general pattern behind writing only for the +<em>happy path</em>, letting the VM catch errors (writing +them to a log for future consumption) and then +having a supervisor restart the processes that +failed from a clean state, has a name. We call it +<em>let it crash</em>; and it drives many of our design +decisions.</p></div> +<div class="paragraph"><p>It’s a really great way to program and the results +are fantastic compared to most other programming +languages. And yet, <em>let it crash</em> barely convinced +anyone that they should use Erlang. Why would that +be?</p></div> +<div class="paragraph"><p>You may already know that Cowboy is capable of +handling at least 2 million Websocket connections +on a single server. This is in large part thanks +to the capabilities of the VM. Still, 2 million +is good, much better than most other servers can +do.</p></div> +<div class="paragraph"><p>Cowboy is not just a Websocket server; it’s also +an HTTP and HTTP/2 server, and it handles many +related features like long polling or the parsing +of most request headers.</p></div> +<div class="paragraph"><p>Can you guess how large the Cowboy codebase is, +without looking at the source?</p></div> +<div class="paragraph"><p>Do make sure you have a clear answer in your mind +before you go check.</p></div> +<div class="paragraph"><p>Good, you are back. Now what were the results? If +I am correct, you overestimated the size of Cowboy. +Cowboy is in fact about five thousand lines of code. +You probably thought it was at least ten thousand. +About eighty percent of readers will have +overestimated the size of Cowboy. And you did only +because I mentioned it can handle millions of +Websocket connections.</p></div> +<div class="paragraph"><p>Numerous studies show this effect. Just mentioning +the large number already prepared your mind to think +in that direction. Repeating the number made you +focus even more on it. Then the question asked for +a number, which ended up larger than the reality.</p></div> +<div class="paragraph"><p>The same effect can be applied to negotiation for +example. You generally want to start by giving your +offer (and not let the other party initiate) and +you want to give a really large number first. You +can also prepare your customer by mentioning an even +larger number in the previous discussion.</p></div> +<div class="paragraph"><p>And it’s not just numbers either. An experiment +showed that just by looking at an image of clouds, +customers of a pillow store were buying pillows +more comfortable (and more expensive) than those +who didn’t see that image.</p></div> +<div class="paragraph"><p>This is the power of associations. It is covered in +much larger detail in the books +<a href="https://www.amazon.com/Influence-Psychology-Persuasion-Robert-Cialdini/dp/006124189X">Influence</a> +and +<a href="https://www.amazon.com/Pre-Suasion-Revolutionary-Way-Influence-Persuade/dp/1501109790">Pre-suasion</a>. +I highly recommend reading those and applying what +you learn to your daily life. I’m definitely not +a professional psychologist so take this post with +a grain of salt.</p></div> +<div class="paragraph"><p>When selling Erlang, whether we are selling it to +a customer or trying to convince a developer friend +to start using it, we often talk about how Erlang +<em>lets you sleep at night</em>, that it is auto healing +and always gets fantastic uptimes.</p></div> +<div class="paragraph"><p>And then we talk about <em>let it crash</em>.</p></div> +<div class="paragraph"><p>And we describe what it means.</p></div> +<div class="paragraph"><p>We might as well just say that Erlang crashes a lot +and then take the door. It would have the same effect. +It doesn’t even stop at programs crashing. You know +what else crashes? Cars, planes, trains. Often with +disastrous consequences. Is that really the message +we want to convey?</p></div> +<div class="paragraph"><p>They even <a href="https://img.youtube.com/vi/oEUBW2lCkIk/0.jpg">printed it on a t-shirt</a>! +Keep calm and let it crash. It’s the kind of t-shirt +you probably shouldn’t wear in an airport, and for good +reasons. A few people did, then realized what they were +wearing and were not too smug about it.</p></div> +<div class="paragraph"><p>And yet this is how we sell Erlang.</p></div> +<div class="paragraph"><p>A better way would be to focus on the positives, of +course, but also to make sure that those positives +are phrased in a way that prevents bad associations +to be formed in people’s minds.</p></div> +<div class="paragraph"><p>Instead of <em>let it crash</em>, you can say that Erlang +has <em>auto healing mechanisms</em>. Healing is a good +thing and accurately describes what happens in the +system.</p></div> +<div class="paragraph"><p>Should you need to go into more details, you will +probably want to avoid <em>recover from crashes</em> and +instead say <em>recover from exceptions</em>. Exceptions +are a pretty neutral word and, should you explain +what you mean by that, you can talk about exceptions +that occur for reasons unrelated to Erlang, like +hardware failure or network instability.</p></div> +<div class="paragraph"><p>The trick is to always use positive words and +phrases to describe Erlang, and to use external +factors to explain how Erlang deals with failures. +Never mention the failures internal to Erlang +systems unless you are asked specifically, in +which case you can say that the auto healing +applies to all exceptions.</p></div> +<div class="paragraph"><p>The <em>let it crash</em> philosophy is great when +learning Erlang or when writing fault-tolerant +systems. But it’s not going to convince anyone +to use it unless they were already looking for +it.</p></div> +<div class="paragraph"><p>Do you like this post? Tell me on Twitter. I might +make more.</p></div> </article> </div> @@ -194,55 +194,107 @@ make more.</p></div> <h3>More articles</h3> <ul id="articles-nav" class="extra_margin"> - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + - <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + + <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + - <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + + <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + - <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + + <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + - <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + + <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + - <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + + <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + - <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + + <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + - <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + + <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + - <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + + <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + - <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + + <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + - <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + + </ul> diff --git a/articles/erlang-scalability/index.html b/articles/erlang-scalability/index.html index 213881da..a9e0be42 100644 --- a/articles/erlang-scalability/index.html +++ b/articles/erlang-scalability/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Erlang Scalability</title> @@ -74,140 +74,140 @@ </p> </header> -<div class="paragraph"><p>I would like to share some experience and theories on
-Erlang scalability.</p></div>
-<div class="paragraph"><p>This will be in the form of a series of hints, which
-may or may not be accompanied with explanations as to why
-things are this way, or how they improve or reduce the scalability
-of a system. I will try to do my best to avoid giving falsehoods,
-even if that means a few things won’t be explained.</p></div>
-<div class="sect1">
-<h2 id="_nifs">NIFs</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>NIFs are considered harmful. I don’t know any single NIF-based
-library that I would recommend. That doesn’t mean they should
-all be avoided, just that if you’re going to want your system to
-scale, you probably shouldn’t use a NIF.</p></div>
-<div class="paragraph"><p>A common case for using NIFs is JSON processing. The problem
-is that JSON is a highly inefficient data structure (similar
-in inefficiency to XML, although perhaps not as bad). If you can
-avoid using JSON, you probably should. MessagePack can replace
-it in many situations.</p></div>
-<div class="paragraph"><p>Long-running NIFs will take over a scheduler and prevent Erlang
-from efficiently handling many processes.</p></div>
-<div class="paragraph"><p>Short-running NIFs will still confuse the scheduler if they
-take more than a few microseconds to run.</p></div>
-<div class="paragraph"><p>Threaded NIFs, or the use of the <code>enif_consume_timeslice</code>
-might help allievate this problem, but they’re not a silver bullet.</p></div>
-<div class="paragraph"><p>And as you already know, a crashing NIF will take down your VM,
-destroying any claims you may have at being scalable.</p></div>
-<div class="paragraph"><p>Never use a NIF because "C is fast". This is only true in
-single-threaded programs.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_bifs">BIFs</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>BIFs can also be harmful. While they are generally better than
-NIFs, they are not perfect and some of them might have harmful
-effects on the scheduler.</p></div>
-<div class="paragraph"><p>A great example of this is the <code>erlang:decode_packet/3</code>
-BIF, when used for HTTP request or response decoding. Avoiding
-its use in <em>Cowboy</em> allowed us to see a big increase in
-the number of requests production systems were able to handle,
-up to two times the original amount. Incidentally this is something
-that is impossible to detect using synthetic benchmarks.</p></div>
-<div class="paragraph"><p>BIFs that return immediately are perfectly fine though.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_binary_strings">Binary strings</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Binary strings use less memory, which means you spend less time
-allocating memory compared to list-based strings. They are also
-more natural for strings manipulation because they are optimized
-for appending (as opposed to prepending for lists).</p></div>
-<div class="paragraph"><p>If you can process a binary string using a single match context,
-then the code will run incredibly fast. The effects will be much
-increased if the code was compiled using HiPE, even if your Erlang
-system isn’t compiled natively.</p></div>
-<div class="paragraph"><p>Avoid using <code>binary:split</code> or <code>binary:replace</code>
-if you can avoid it. They have a certain overhead due to supporting
-many options that you probably don’t need for most operations.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_buffering_and_streaming">Buffering and streaming</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Use binaries. They are great for appending, and it’s a direct copy
-from what you receive from a stream (usually a socket or a file).</p></div>
-<div class="paragraph"><p>Be careful to not indefinitely receive data, as you might end up
-having a single binary taking up huge amounts of memory.</p></div>
-<div class="paragraph"><p>If you stream from a socket and know how much data you expect,
-then fetch that data in a single <code>recv</code> call.</p></div>
-<div class="paragraph"><p>Similarly, if you can use a single <code>send</code> call, then
-you should do so, to avoid going back and forth unnecessarily between
-your Erlang process and the Erlang port for your socket.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_list_and_binary_comprehensions">List and binary comprehensions</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Prefer list comprehensions over <code>lists:map/2</code>. The
-compiler will be able to optimize your code greatly, for example
-not creating the result if you don’t need it. As time goes on,
-more optimizations will be added to the compiler and you will
-automatically benefit from them.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_gen_server_is_no_silver_bullet">gen_server is no silver bullet</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>It’s a bad idea to use <code>gen_server</code> for everything.
-For two reasons.</p></div>
-<div class="paragraph"><p>There is an overhead everytime the <code>gen_server</code> receives
-a call, a cast or a simple message. It can be a problem if your
-<code>gen_server</code> is in a critical code path where speed
-is all that matters. Do not hesitate to create other kinds of
-processes where it makes sense. And depending on the kind of process,
-you might want to consider making them special processes, which
-would essentially behave the same as a <code>gen_server</code>.</p></div>
-<div class="paragraph"><p>A common mistake is to have a unique <code>gen_server</code> to
-handle queries from many processes. This generally becomes the
-biggest bottleneck you’ll want to fix. You should try to avoid
-relying on a single process, using a pool if you can.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_supervisor_and_monitoring">Supervisor and monitoring</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A <code>supervisor</code> is also a <code>gen_server</code>,
-so the previous points also apply to them.</p></div>
-<div class="paragraph"><p>Sometimes you’re in a situation where you have supervised
-processes but also want to monitor them in one or more other
-processes, effectively duplicating the work. The supervisor
-already knows when processes die, why not use this to our
-advantage?</p></div>
-<div class="paragraph"><p>You can create a custom supervisor process that will perform
-both the supervision and handle exit and other events, allowing
-to avoid the combination of supervising and monitoring which
-can prove harmful when many processes die at once, or when you
-have many short lived processes.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_ets_for_lolspeed_tm">ets for LOLSPEED(tm)</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>If you have data queried or modified by many processes, then
-<code>ets</code> public or protected tables will give you the
-performance boost you require. Do not forget to set the
-<code>read_concurrency</code> or <code>write_concurrency</code>
-options though.</p></div>
-<div class="paragraph"><p>You might also be thrilled to know that Erlang R16B will feature
-a big performance improvement for accessing <code>ets</code> tables
-concurrently.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>I would like to share some experience and theories on +Erlang scalability.</p></div> +<div class="paragraph"><p>This will be in the form of a series of hints, which +may or may not be accompanied with explanations as to why +things are this way, or how they improve or reduce the scalability +of a system. I will try to do my best to avoid giving falsehoods, +even if that means a few things won’t be explained.</p></div> +<div class="sect1"> +<h2 id="_nifs">NIFs</h2> +<div class="sectionbody"> +<div class="paragraph"><p>NIFs are considered harmful. I don’t know any single NIF-based +library that I would recommend. That doesn’t mean they should +all be avoided, just that if you’re going to want your system to +scale, you probably shouldn’t use a NIF.</p></div> +<div class="paragraph"><p>A common case for using NIFs is JSON processing. The problem +is that JSON is a highly inefficient data structure (similar +in inefficiency to XML, although perhaps not as bad). If you can +avoid using JSON, you probably should. MessagePack can replace +it in many situations.</p></div> +<div class="paragraph"><p>Long-running NIFs will take over a scheduler and prevent Erlang +from efficiently handling many processes.</p></div> +<div class="paragraph"><p>Short-running NIFs will still confuse the scheduler if they +take more than a few microseconds to run.</p></div> +<div class="paragraph"><p>Threaded NIFs, or the use of the <code>enif_consume_timeslice</code> +might help allievate this problem, but they’re not a silver bullet.</p></div> +<div class="paragraph"><p>And as you already know, a crashing NIF will take down your VM, +destroying any claims you may have at being scalable.</p></div> +<div class="paragraph"><p>Never use a NIF because "C is fast". This is only true in +single-threaded programs.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_bifs">BIFs</h2> +<div class="sectionbody"> +<div class="paragraph"><p>BIFs can also be harmful. While they are generally better than +NIFs, they are not perfect and some of them might have harmful +effects on the scheduler.</p></div> +<div class="paragraph"><p>A great example of this is the <code>erlang:decode_packet/3</code> +BIF, when used for HTTP request or response decoding. Avoiding +its use in <em>Cowboy</em> allowed us to see a big increase in +the number of requests production systems were able to handle, +up to two times the original amount. Incidentally this is something +that is impossible to detect using synthetic benchmarks.</p></div> +<div class="paragraph"><p>BIFs that return immediately are perfectly fine though.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_binary_strings">Binary strings</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Binary strings use less memory, which means you spend less time +allocating memory compared to list-based strings. They are also +more natural for strings manipulation because they are optimized +for appending (as opposed to prepending for lists).</p></div> +<div class="paragraph"><p>If you can process a binary string using a single match context, +then the code will run incredibly fast. The effects will be much +increased if the code was compiled using HiPE, even if your Erlang +system isn’t compiled natively.</p></div> +<div class="paragraph"><p>Avoid using <code>binary:split</code> or <code>binary:replace</code> +if you can avoid it. They have a certain overhead due to supporting +many options that you probably don’t need for most operations.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_buffering_and_streaming">Buffering and streaming</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Use binaries. They are great for appending, and it’s a direct copy +from what you receive from a stream (usually a socket or a file).</p></div> +<div class="paragraph"><p>Be careful to not indefinitely receive data, as you might end up +having a single binary taking up huge amounts of memory.</p></div> +<div class="paragraph"><p>If you stream from a socket and know how much data you expect, +then fetch that data in a single <code>recv</code> call.</p></div> +<div class="paragraph"><p>Similarly, if you can use a single <code>send</code> call, then +you should do so, to avoid going back and forth unnecessarily between +your Erlang process and the Erlang port for your socket.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_list_and_binary_comprehensions">List and binary comprehensions</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Prefer list comprehensions over <code>lists:map/2</code>. The +compiler will be able to optimize your code greatly, for example +not creating the result if you don’t need it. As time goes on, +more optimizations will be added to the compiler and you will +automatically benefit from them.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_gen_server_is_no_silver_bullet">gen_server is no silver bullet</h2> +<div class="sectionbody"> +<div class="paragraph"><p>It’s a bad idea to use <code>gen_server</code> for everything. +For two reasons.</p></div> +<div class="paragraph"><p>There is an overhead everytime the <code>gen_server</code> receives +a call, a cast or a simple message. It can be a problem if your +<code>gen_server</code> is in a critical code path where speed +is all that matters. Do not hesitate to create other kinds of +processes where it makes sense. And depending on the kind of process, +you might want to consider making them special processes, which +would essentially behave the same as a <code>gen_server</code>.</p></div> +<div class="paragraph"><p>A common mistake is to have a unique <code>gen_server</code> to +handle queries from many processes. This generally becomes the +biggest bottleneck you’ll want to fix. You should try to avoid +relying on a single process, using a pool if you can.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_supervisor_and_monitoring">Supervisor and monitoring</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A <code>supervisor</code> is also a <code>gen_server</code>, +so the previous points also apply to them.</p></div> +<div class="paragraph"><p>Sometimes you’re in a situation where you have supervised +processes but also want to monitor them in one or more other +processes, effectively duplicating the work. The supervisor +already knows when processes die, why not use this to our +advantage?</p></div> +<div class="paragraph"><p>You can create a custom supervisor process that will perform +both the supervision and handle exit and other events, allowing +to avoid the combination of supervising and monitoring which +can prove harmful when many processes die at once, or when you +have many short lived processes.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_ets_for_lolspeed_tm">ets for LOLSPEED(tm)</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you have data queried or modified by many processes, then +<code>ets</code> public or protected tables will give you the +performance boost you require. Do not forget to set the +<code>read_concurrency</code> or <code>write_concurrency</code> +options though.</p></div> +<div class="paragraph"><p>You might also be thrilled to know that Erlang R16B will feature +a big performance improvement for accessing <code>ets</code> tables +concurrently.</p></div> +</div> +</div> </article> </div> @@ -216,55 +216,107 @@ concurrently.</p></div> <h3>More articles</h3> <ul id="articles-nav" class="extra_margin"> - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + + <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + - <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + + <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + - <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + + <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + - <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + + <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + - <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + + <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + - <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + + <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + - <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + + <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + - <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + + <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + - <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + + <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + - <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + + <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + - <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + </ul> diff --git a/articles/erlang-validate-utf8/index.html b/articles/erlang-validate-utf8/index.html index a96aba26..3eceb840 100644 --- a/articles/erlang-validate-utf8/index.html +++ b/articles/erlang-validate-utf8/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Validating UTF-8 binaries with Erlang</title> @@ -74,191 +74,191 @@ </p> </header> -<div class="paragraph"><p>Yesterday I pushed Websocket permessage-deflate to
-Cowboy master. I also pushed
-<a href="https://github.com/ninenines/cowlib/commit/7e4983b70ddf8cedb967e36fba6a600731bdad5d">a
-change in the way the code validates UTF-8 data</a>
-(required for text and close frames as per the spec).</p></div>
-<div class="paragraph"><p>When looking into why the permessage-deflate tests
-in autobahntestsuite were taking such a long time, I
-found that autobahn is using an adaptation of the
-algorithm named <a href="http://bjoern.hoehrmann.de/utf-8/decoder/dfa/">Flexible
-and Economical UTF-8 Decoder</a>. This is the C99
-implementation:</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-style: italic"><span style="color: #9A1900">// Copyright (c) 2008-2009 Bjoern Hoehrmann <[email protected]></span></span>
-<span style="font-style: italic"><span style="color: #9A1900">// See http://bjoern.hoehrmann.de/utf-8/decoder/dfa/ for details.</span></span>
-
-<span style="font-weight: bold"><span style="color: #000080">#define</span></span> UTF8_ACCEPT <span style="color: #993399">0</span>
-<span style="font-weight: bold"><span style="color: #000080">#define</span></span> UTF8_REJECT <span style="color: #993399">1</span>
-
-<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> <span style="color: #008080">uint8_t</span> utf8d<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">{</span>
- <span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// 00..1f</span></span>
- <span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// 20..3f</span></span>
- <span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// 40..5f</span></span>
- <span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// 60..7f</span></span>
- <span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// 80..9f</span></span>
- <span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// a0..bf</span></span>
- <span style="color: #993399">8</span><span style="color: #990000">,</span><span style="color: #993399">8</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// c0..df</span></span>
- <span style="color: #993399">0xa</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x4</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// e0..ef</span></span>
- <span style="color: #993399">0xb</span><span style="color: #990000">,</span><span style="color: #993399">0x6</span><span style="color: #990000">,</span><span style="color: #993399">0x6</span><span style="color: #990000">,</span><span style="color: #993399">0x6</span><span style="color: #990000">,</span><span style="color: #993399">0x5</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// f0..ff</span></span>
- <span style="color: #993399">0x0</span><span style="color: #990000">,</span><span style="color: #993399">0x1</span><span style="color: #990000">,</span><span style="color: #993399">0x2</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x5</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x7</span><span style="color: #990000">,</span><span style="color: #993399">0x1</span><span style="color: #990000">,</span><span style="color: #993399">0x1</span><span style="color: #990000">,</span><span style="color: #993399">0x1</span><span style="color: #990000">,</span><span style="color: #993399">0x4</span><span style="color: #990000">,</span><span style="color: #993399">0x6</span><span style="color: #990000">,</span><span style="color: #993399">0x1</span><span style="color: #990000">,</span><span style="color: #993399">0x1</span><span style="color: #990000">,</span><span style="color: #993399">0x1</span><span style="color: #990000">,</span><span style="color: #993399">0x1</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// s0..s0</span></span>
- <span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// s1..s2</span></span>
- <span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// s3..s4</span></span>
- <span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">3</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">3</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// s5..s6</span></span>
- <span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">3</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">3</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">3</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">3</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// s7..s8</span></span>
-<span style="color: #FF0000">}</span><span style="color: #990000">;</span>
-
-uint32_t inline
-<span style="font-weight: bold"><span style="color: #000000">decode</span></span><span style="color: #990000">(</span>uint32_t<span style="color: #990000">*</span> state<span style="color: #990000">,</span> uint32_t<span style="color: #990000">*</span> codep<span style="color: #990000">,</span> <span style="color: #008080">uint32_t</span> byte<span style="color: #990000">)</span> <span style="color: #FF0000">{</span>
- <span style="color: #008080">uint32_t</span> type <span style="color: #990000">=</span> utf8d<span style="color: #990000">[</span>byte<span style="color: #990000">];</span>
-
- <span style="color: #990000">*</span>codep <span style="color: #990000">=</span> <span style="color: #990000">(*</span>state <span style="color: #990000">!=</span> UTF8_ACCEPT<span style="color: #990000">)</span> <span style="color: #990000">?</span>
- <span style="color: #990000">(</span>byte <span style="color: #990000">&</span> <span style="color: #993399">0x3fu</span><span style="color: #990000">)</span> <span style="color: #990000">|</span> <span style="color: #990000">(*</span>codep <span style="color: #990000"><<</span> <span style="color: #993399">6</span><span style="color: #990000">)</span> <span style="color: #990000">:</span>
- <span style="color: #990000">(</span><span style="color: #993399">0xff</span> <span style="color: #990000">>></span> type<span style="color: #990000">)</span> <span style="color: #990000">&</span> <span style="color: #990000">(</span>byte<span style="color: #990000">);</span>
-
- <span style="color: #990000">*</span>state <span style="color: #990000">=</span> utf8d<span style="color: #990000">[</span><span style="color: #993399">256</span> <span style="color: #990000">+</span> <span style="color: #990000">*</span>state<span style="color: #990000">*</span><span style="color: #993399">16</span> <span style="color: #990000">+</span> type<span style="color: #990000">];</span>
- <span style="font-weight: bold"><span style="color: #0000FF">return</span></span> <span style="color: #990000">*</span>state<span style="color: #990000">;</span>
-<span style="color: #FF0000">}</span></tt></pre></div></div>
-<div class="paragraph"><p>And this is the Erlang implementation I came up with:</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-style: italic"><span style="color: #9A1900">%% This function returns 0 on success, 1 on error, and 2..8 on incomplete data.</span></span>
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<>></span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #009900">State</span>;
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">128</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">2</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">128</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">144</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">3</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">128</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">144</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">5</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">128</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">144</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">7</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">128</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">144</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">8</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">128</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">144</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">2</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">160</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">3</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">160</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">5</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">160</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">6</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">160</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">7</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">160</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">2</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">160</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">192</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">3</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">160</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">192</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">4</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">160</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">192</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">6</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">160</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">192</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">7</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">160</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">192</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">194</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">224</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">224</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">4</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">225</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">237</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">237</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">5</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">=:=</span> <span style="color: #993399">238</span>; <span style="color: #009900">C</span> <span style="color: #990000">=:=</span> <span style="color: #993399">239</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">240</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">6</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">=:=</span> <span style="color: #993399">241</span>; <span style="color: #009900">C</span> <span style="color: #990000">=:=</span> <span style="color: #993399">242</span>; <span style="color: #009900">C</span> <span style="color: #990000">=:=</span> <span style="color: #993399">243</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">7</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">244</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">8</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">_</span>, <span style="color: #990000">_</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>Does it look similar to you? So how did we get there?</p></div>
-<div class="paragraph"><p>I started with a naive implementation of the original. First, we
-don’t need the codepoint calculated and extracted for our validation
-function. We just want to know the data is valid, so we only need to
-calculate the next state. Then, the only thing we needed to be careful
-about was that tuples are 1-based, and that we need to stop processing
-the binary when we get the state 1 or when the binary is empty.</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">validate_utf8</span></span>(<span style="color: #990000"><<>></span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #009900">State</span>;
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">_</span>, <span style="color: #993399">1</span>) <span style="color: #990000">-></span> <span style="color: #993399">1</span>;
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="font-weight: bold"><span style="color: #000080">element</span></span>(<span style="color: #993399">257</span> <span style="color: #990000">+</span> <span style="color: #009900">State</span> <span style="color: #990000">*</span> <span style="color: #993399">16</span> <span style="color: #990000">+</span> <span style="font-weight: bold"><span style="color: #000080">element</span></span>(<span style="color: #993399">1</span> <span style="color: #990000">+</span> <span style="color: #009900">C</span>, <span style="font-weight: bold"><span style="color: #000080">?UTF8D</span></span>), <span style="font-weight: bold"><span style="color: #000080">?UTF8D</span></span>))<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The macro <code>?UTF8D</code> is the tuple equivalent of the C array
-in the original code.</p></div>
-<div class="paragraph"><p>Compared to our previous algorithm, this performed about the same.
-In some situations a little faster, in some a little slower. In other words,
-not good enough. But because this new algorithm allows us to avoid a binary
-concatenation this warranted looking further.</p></div>
-<div class="paragraph"><p>It was time to step into crazy land.</p></div>
-<div class="paragraph"><p>Erlang is very good at pattern matching, even more so than doing some
-arithmetic coupled by fetching elements from a tuple. So I decided I was
-going to write all possible clauses for all combinations of <code>C</code>
-and <code>State</code>. And by write I mean generate.</p></div>
-<div class="paragraph"><p>So I opened my Erlang shell, defined the variable <code>D</code> to be
-the tuple <code>?UTF8D</code> with its 400 elements, and then ran the
-following expression (after a bit of trial and error):</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: #993399">16</span><span style="color: #990000">></span> <span style="font-weight: bold"><span style="color: #000000">file:write_file</span></span>(<span style="color: #FF0000">"out.txt"</span>,
- [<span style="font-weight: bold"><span style="color: #000000">io_lib:format</span></span>(<span style="color: #FF0000">"validate_utf8(<< ~p, Rest/bits >>, ~p) -> ~p;~n"</span>,
- [<span style="color: #009900">C</span>, <span style="color: #009900">S</span>, <span style="font-weight: bold"><span style="color: #000080">element</span></span>(<span style="color: #993399">257</span> <span style="color: #990000">+</span> <span style="color: #009900">S</span> <span style="color: #990000">*</span> <span style="color: #993399">16</span> <span style="color: #990000">+</span> <span style="font-weight: bold"><span style="color: #000080">element</span></span>(<span style="color: #993399">1</span> <span style="color: #990000">+</span> <span style="color: #009900">C</span>, <span style="color: #009900">D</span>), <span style="color: #009900">D</span>)])
- || <span style="color: #009900">C</span> <span style="color: #990000"><-</span> <span style="font-weight: bold"><span style="color: #000000">lists:seq</span></span>(<span style="color: #993399">0</span>,<span style="color: #993399">255</span>), <span style="color: #009900">S</span> <span style="color: #990000"><-</span> <span style="font-weight: bold"><span style="color: #000000">lists:seq</span></span>(<span style="color: #993399">0</span>,<span style="color: #993399">8</span>)])<span style="color: #990000">.</span>
-<span style="color: #FF6600">ok</span></tt></pre></div></div>
-<div class="paragraph"><p>The result is a 2304 lines long file, containing 2304 clauses.
-People who pay attention to what I say on Twitter will remember
-I said something around 3000 clauses, but that was just me not
-using the right number of states in my estimate.</p></div>
-<div class="paragraph"><p>There was a little more work to be done on this generated
-code that I did using regular expressions. We need to recurse
-when the resulting state is not 1. We also need to stop when
-the binary is empty, making it the 2305th clause.</p></div>
-<div class="paragraph"><p>Still, 2305 is a lot. But hey, the code did work, and faster
-than the previous implementation too! But hey, perhaps I could
-find a way to reduce its size.</p></div>
-<div class="paragraph"><p>Removing all the clauses that return 1 and putting a catch-all
-clause at the end instead reduced the number to about 500, and
-showed that many clauses were similar:</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">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">0</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">1</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">2</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">3</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">4</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">5</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">6</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">7</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);</tt></pre></div></div>
-<div class="paragraph"><p>But 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="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">157</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">2</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">157</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">3</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">157</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">5</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">157</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">6</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">157</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">7</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">158</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">2</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">158</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">3</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">158</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">5</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">158</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">6</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">158</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">7</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>);</tt></pre></div></div>
-<div class="paragraph"><p>Patterns, my favorites!</p></div>
-<div class="paragraph"><p>A little more time was spent to edit the 500 or so clauses into
-smaller equivalents, testing that performance was not impacted, and
-comitting the result.</p></div>
-<div class="paragraph"><p>The patterns above can be found here in the resulting 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">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">128</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="color: #990000">...</span>
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">2</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">160</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">3</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">160</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">5</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">160</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">6</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">160</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">7</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">160</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>);
-<span style="color: #990000">...</span></tt></pre></div></div>
-<div class="paragraph"><p>I hope you enjoyed this post.</p></div>
+<div class="paragraph"><p>Yesterday I pushed Websocket permessage-deflate to +Cowboy master. I also pushed +<a href="https://github.com/ninenines/cowlib/commit/7e4983b70ddf8cedb967e36fba6a600731bdad5d">a +change in the way the code validates UTF-8 data</a> +(required for text and close frames as per the spec).</p></div> +<div class="paragraph"><p>When looking into why the permessage-deflate tests +in autobahntestsuite were taking such a long time, I +found that autobahn is using an adaptation of the +algorithm named <a href="http://bjoern.hoehrmann.de/utf-8/decoder/dfa/">Flexible +and Economical UTF-8 Decoder</a>. This is the C99 +implementation:</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-style: italic"><span style="color: #9A1900">// Copyright (c) 2008-2009 Bjoern Hoehrmann <[email protected]></span></span> +<span style="font-style: italic"><span style="color: #9A1900">// See http://bjoern.hoehrmann.de/utf-8/decoder/dfa/ for details.</span></span> + +<span style="font-weight: bold"><span style="color: #000080">#define</span></span> UTF8_ACCEPT <span style="color: #993399">0</span> +<span style="font-weight: bold"><span style="color: #000080">#define</span></span> UTF8_REJECT <span style="color: #993399">1</span> + +<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> <span style="color: #008080">uint8_t</span> utf8d<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">{</span> + <span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// 00..1f</span></span> + <span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// 20..3f</span></span> + <span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// 40..5f</span></span> + <span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// 60..7f</span></span> + <span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// 80..9f</span></span> + <span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// a0..bf</span></span> + <span style="color: #993399">8</span><span style="color: #990000">,</span><span style="color: #993399">8</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// c0..df</span></span> + <span style="color: #993399">0xa</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x4</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// e0..ef</span></span> + <span style="color: #993399">0xb</span><span style="color: #990000">,</span><span style="color: #993399">0x6</span><span style="color: #990000">,</span><span style="color: #993399">0x6</span><span style="color: #990000">,</span><span style="color: #993399">0x6</span><span style="color: #990000">,</span><span style="color: #993399">0x5</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// f0..ff</span></span> + <span style="color: #993399">0x0</span><span style="color: #990000">,</span><span style="color: #993399">0x1</span><span style="color: #990000">,</span><span style="color: #993399">0x2</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x5</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x7</span><span style="color: #990000">,</span><span style="color: #993399">0x1</span><span style="color: #990000">,</span><span style="color: #993399">0x1</span><span style="color: #990000">,</span><span style="color: #993399">0x1</span><span style="color: #990000">,</span><span style="color: #993399">0x4</span><span style="color: #990000">,</span><span style="color: #993399">0x6</span><span style="color: #990000">,</span><span style="color: #993399">0x1</span><span style="color: #990000">,</span><span style="color: #993399">0x1</span><span style="color: #990000">,</span><span style="color: #993399">0x1</span><span style="color: #990000">,</span><span style="color: #993399">0x1</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// s0..s0</span></span> + <span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// s1..s2</span></span> + <span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// s3..s4</span></span> + <span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">3</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">3</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// s5..s6</span></span> + <span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">3</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">3</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">3</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">3</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// s7..s8</span></span> +<span style="color: #FF0000">}</span><span style="color: #990000">;</span> + +uint32_t inline +<span style="font-weight: bold"><span style="color: #000000">decode</span></span><span style="color: #990000">(</span>uint32_t<span style="color: #990000">*</span> state<span style="color: #990000">,</span> uint32_t<span style="color: #990000">*</span> codep<span style="color: #990000">,</span> <span style="color: #008080">uint32_t</span> byte<span style="color: #990000">)</span> <span style="color: #FF0000">{</span> + <span style="color: #008080">uint32_t</span> type <span style="color: #990000">=</span> utf8d<span style="color: #990000">[</span>byte<span style="color: #990000">];</span> + + <span style="color: #990000">*</span>codep <span style="color: #990000">=</span> <span style="color: #990000">(*</span>state <span style="color: #990000">!=</span> UTF8_ACCEPT<span style="color: #990000">)</span> <span style="color: #990000">?</span> + <span style="color: #990000">(</span>byte <span style="color: #990000">&</span> <span style="color: #993399">0x3fu</span><span style="color: #990000">)</span> <span style="color: #990000">|</span> <span style="color: #990000">(*</span>codep <span style="color: #990000"><<</span> <span style="color: #993399">6</span><span style="color: #990000">)</span> <span style="color: #990000">:</span> + <span style="color: #990000">(</span><span style="color: #993399">0xff</span> <span style="color: #990000">>></span> type<span style="color: #990000">)</span> <span style="color: #990000">&</span> <span style="color: #990000">(</span>byte<span style="color: #990000">);</span> + + <span style="color: #990000">*</span>state <span style="color: #990000">=</span> utf8d<span style="color: #990000">[</span><span style="color: #993399">256</span> <span style="color: #990000">+</span> <span style="color: #990000">*</span>state<span style="color: #990000">*</span><span style="color: #993399">16</span> <span style="color: #990000">+</span> type<span style="color: #990000">];</span> + <span style="font-weight: bold"><span style="color: #0000FF">return</span></span> <span style="color: #990000">*</span>state<span style="color: #990000">;</span> +<span style="color: #FF0000">}</span></tt></pre></div></div> +<div class="paragraph"><p>And this is the Erlang implementation I came up with:</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-style: italic"><span style="color: #9A1900">%% This function returns 0 on success, 1 on error, and 2..8 on incomplete data.</span></span> +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<>></span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #009900">State</span>; +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">128</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">2</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">128</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">144</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">3</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">128</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">144</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">5</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">128</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">144</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">7</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">128</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">144</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">8</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">128</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">144</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">2</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">160</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">3</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">160</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">5</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">160</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">6</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">160</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">7</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">160</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">2</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">160</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">192</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">3</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">160</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">192</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">4</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">160</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">192</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">6</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">160</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">192</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">7</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">160</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">192</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">194</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">224</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">224</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">4</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">225</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">237</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">237</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">5</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">=:=</span> <span style="color: #993399">238</span>; <span style="color: #009900">C</span> <span style="color: #990000">=:=</span> <span style="color: #993399">239</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">240</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">6</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">=:=</span> <span style="color: #993399">241</span>; <span style="color: #009900">C</span> <span style="color: #990000">=:=</span> <span style="color: #993399">242</span>; <span style="color: #009900">C</span> <span style="color: #990000">=:=</span> <span style="color: #993399">243</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">7</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">244</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">8</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">_</span>, <span style="color: #990000">_</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>Does it look similar to you? So how did we get there?</p></div> +<div class="paragraph"><p>I started with a naive implementation of the original. First, we +don’t need the codepoint calculated and extracted for our validation +function. We just want to know the data is valid, so we only need to +calculate the next state. Then, the only thing we needed to be careful +about was that tuples are 1-based, and that we need to stop processing +the binary when we get the state 1 or when the binary is empty.</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">validate_utf8</span></span>(<span style="color: #990000"><<>></span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #009900">State</span>; +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">_</span>, <span style="color: #993399">1</span>) <span style="color: #990000">-></span> <span style="color: #993399">1</span>; +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="font-weight: bold"><span style="color: #000080">element</span></span>(<span style="color: #993399">257</span> <span style="color: #990000">+</span> <span style="color: #009900">State</span> <span style="color: #990000">*</span> <span style="color: #993399">16</span> <span style="color: #990000">+</span> <span style="font-weight: bold"><span style="color: #000080">element</span></span>(<span style="color: #993399">1</span> <span style="color: #990000">+</span> <span style="color: #009900">C</span>, <span style="font-weight: bold"><span style="color: #000080">?UTF8D</span></span>), <span style="font-weight: bold"><span style="color: #000080">?UTF8D</span></span>))<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The macro <code>?UTF8D</code> is the tuple equivalent of the C array +in the original code.</p></div> +<div class="paragraph"><p>Compared to our previous algorithm, this performed about the same. +In some situations a little faster, in some a little slower. In other words, +not good enough. But because this new algorithm allows us to avoid a binary +concatenation this warranted looking further.</p></div> +<div class="paragraph"><p>It was time to step into crazy land.</p></div> +<div class="paragraph"><p>Erlang is very good at pattern matching, even more so than doing some +arithmetic coupled by fetching elements from a tuple. So I decided I was +going to write all possible clauses for all combinations of <code>C</code> +and <code>State</code>. And by write I mean generate.</p></div> +<div class="paragraph"><p>So I opened my Erlang shell, defined the variable <code>D</code> to be +the tuple <code>?UTF8D</code> with its 400 elements, and then ran the +following expression (after a bit of trial and error):</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: #993399">16</span><span style="color: #990000">></span> <span style="font-weight: bold"><span style="color: #000000">file:write_file</span></span>(<span style="color: #FF0000">"out.txt"</span>, + [<span style="font-weight: bold"><span style="color: #000000">io_lib:format</span></span>(<span style="color: #FF0000">"validate_utf8(<< ~p, Rest/bits >>, ~p) -> ~p;~n"</span>, + [<span style="color: #009900">C</span>, <span style="color: #009900">S</span>, <span style="font-weight: bold"><span style="color: #000080">element</span></span>(<span style="color: #993399">257</span> <span style="color: #990000">+</span> <span style="color: #009900">S</span> <span style="color: #990000">*</span> <span style="color: #993399">16</span> <span style="color: #990000">+</span> <span style="font-weight: bold"><span style="color: #000080">element</span></span>(<span style="color: #993399">1</span> <span style="color: #990000">+</span> <span style="color: #009900">C</span>, <span style="color: #009900">D</span>), <span style="color: #009900">D</span>)]) + || <span style="color: #009900">C</span> <span style="color: #990000"><-</span> <span style="font-weight: bold"><span style="color: #000000">lists:seq</span></span>(<span style="color: #993399">0</span>,<span style="color: #993399">255</span>), <span style="color: #009900">S</span> <span style="color: #990000"><-</span> <span style="font-weight: bold"><span style="color: #000000">lists:seq</span></span>(<span style="color: #993399">0</span>,<span style="color: #993399">8</span>)])<span style="color: #990000">.</span> +<span style="color: #FF6600">ok</span></tt></pre></div></div> +<div class="paragraph"><p>The result is a 2304 lines long file, containing 2304 clauses. +People who pay attention to what I say on Twitter will remember +I said something around 3000 clauses, but that was just me not +using the right number of states in my estimate.</p></div> +<div class="paragraph"><p>There was a little more work to be done on this generated +code that I did using regular expressions. We need to recurse +when the resulting state is not 1. We also need to stop when +the binary is empty, making it the 2305th clause.</p></div> +<div class="paragraph"><p>Still, 2305 is a lot. But hey, the code did work, and faster +than the previous implementation too! But hey, perhaps I could +find a way to reduce its size.</p></div> +<div class="paragraph"><p>Removing all the clauses that return 1 and putting a catch-all +clause at the end instead reduced the number to about 500, and +showed that many clauses were similar:</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">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">0</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">1</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">2</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">3</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">4</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">5</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">6</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">7</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);</tt></pre></div></div> +<div class="paragraph"><p>But 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="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">157</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">2</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">157</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">3</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">157</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">5</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">157</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">6</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">157</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">7</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">158</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">2</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">158</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">3</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">158</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">5</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">158</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">6</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #993399">158</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">7</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>);</tt></pre></div></div> +<div class="paragraph"><p>Patterns, my favorites!</p></div> +<div class="paragraph"><p>A little more time was spent to edit the 500 or so clauses into +smaller equivalents, testing that performance was not impacted, and +comitting the result.</p></div> +<div class="paragraph"><p>The patterns above can be found here in the resulting 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">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">0</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">128</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>); +<span style="color: #990000">...</span> +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">2</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">160</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">3</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">160</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">5</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">160</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">6</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">160</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>); +<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000"><<</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span>, <span style="color: #993399">7</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">>=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000"><</span> <span style="color: #993399">160</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>); +<span style="color: #990000">...</span></tt></pre></div></div> +<div class="paragraph"><p>I hope you enjoyed this post.</p></div> </article> </div> @@ -267,55 +267,107 @@ http://www.gnu.org/software/src-highlite --> <h3>More articles</h3> <ul id="articles-nav" class="extra_margin"> - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + + <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + - <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + + <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + - <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + + <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + - <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + + <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + - <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + + <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + - <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + + <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + - <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + + <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + - <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + + <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + - <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + + <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + - <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + + <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + - <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + </ul> diff --git a/articles/erlang.mk-and-relx/index.html b/articles/erlang.mk-and-relx/index.html index 359a30e6..28bdc7a5 100644 --- a/articles/erlang.mk-and-relx/index.html +++ b/articles/erlang.mk-and-relx/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Build Erlang releases with Erlang.mk and Relx</title> @@ -74,94 +74,118 @@ </p> </header> -<div class="paragraph"><p>Building OTP releases has always been a difficult task. Tools like
-Reltool or Rebar have made this simpler, but
-it’s no panacea. This article will show you an alternative and
-hopefully much simpler solution.</p></div>
-<div class="paragraph"><p>There is two steps to building a release. First you need to build
-the various OTP applications you want to include in the release. Once
-done, you need to create the release itself, by including the Erlang
-runtime system alongside the applications, a boot script to start the
-node and all its applications, and some configuration files.</p></div>
-<div class="paragraph"><p><a href="https://github.com/extend/erlang.mk">Erlang.mk</a> solves
-the first step. It is an include file for GNU Make. Just
-including it in a Makefile is enough to allow building your project,
-fetching and building dependencies, building documentation, performing
-static analysis and more.</p></div>
-<div class="paragraph"><p><a href="https://github.com/erlware/relx">Relx</a> solves the second
-step. It is a release creation tool, wrapped into a single executable
-file. It doesn’t require a configuration file. And if you do need one,
-it will be a pretty small one.</p></div>
-<div class="paragraph"><p>Let’s take a look at the smallest Erlang.mk powered
-Makefile. There is only one thing required: defining the project
-name.</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Simply doing this allows you to build your application by typing
-<code>make</code>, running tests using <code>make tests</code>, and
-more. It will even compile your <em>.dtl</em> files found in the
-<em>templates/</em> directory if you are using ErlyDTL!</p></div>
-<div class="paragraph"><p>Let’s now take a look at a simplified version of the Makefile for
-this website. I only removed a few targets that were off-topic.</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>You can see here how to define dependencies. First you list all
-the dependency names, then you have one line per dependency, giving
-the repository URL and the commit number, tag or branch you want.</p></div>
-<div class="paragraph"><p>Then you can see two targets defined, with <code>release</code>
-becoming the default target, because it was defined first. You can
-override the default target <code>all</code>, which builds the
-application and its dependencies, this way.</p></div>
-<div class="paragraph"><p>And as you can see, the <code>release</code> target uses
-Relx to build a release into the <em>rel/ninenines/</em>
-directory. Let’s take a look at the configuration file for this 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: #FF6600">release</span>, {<span style="color: #FF6600">ninenines</span>, <span style="color: #FF0000">"1"</span>}, [<span style="color: #FF6600">ninenines</span>]}<span style="color: #990000">.</span>
-
-{<span style="color: #FF6600">extended_start_script</span>, <span style="color: #000080">true</span>}<span style="color: #990000">.</span>
-{<span style="color: #FF6600">sys_config</span>, <span style="color: #FF0000">"rel/sys.config"</span>}<span style="color: #990000">.</span>
-
-{<span style="color: #FF6600">overlay</span>, [
- {<span style="color: #FF6600">mkdir</span>, <span style="color: #FF0000">"log"</span>},
- {<span style="color: #FF6600">copy</span>, <span style="color: #FF0000">"rel/vm.args"</span>,
- <span style="color: #FF0000">"releases/\{\{release_name\}\}-\{\{release_version\}\}/vm.args"</span>}
-]}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The first line defines a release named <code>ninenines</code>, which
-has a version number <code>"1"</code> and includes one application, also
-named <code>ninenines</code>, although it doesn’t have to.</p></div>
-<div class="paragraph"><p>We then use the <code>extended_start_script</code> option to tell
-Relx that we would like to have a start script that allows
-us to not only start the release, but do so with the node in the
-background, or also to allow us to connect to a running node, and so on.
-This start script has the same features as the one tools like
-Rebar generates.</p></div>
-<div class="paragraph"><p>The rest of the file just makes sure our configuration files are
-where we expect them. Relx will automatically take care
-of your <em>sys.config</em> file as long as you tell it where to
-find it. The <em>vm.args</em> file used by the extended start script
-needs to be handled more explicitly by using an overlay however.</p></div>
-<div class="paragraph"><p>How does Relx find what applications to include?
-By looking at the application dependencies in the <em>.app</em>
-file of each OTP application. Make sure you put all dependencies in
-there, <em>including</em> library applications, and Relx
-will find everything for you.</p></div>
-<div class="paragraph"><p>For example, this release includes the following applications.
-Only what’s strictly required.</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>compiler-4.9.1 crypto-2.3 kernel-2.16.1 ranch-0.8.3 syntax_tools-1.6.11
-cowboy-0.8.5 erlydtl-0.7.0 ninenines-0.2.0 stdlib-1.19.1</code></pre>
-</div></div>
-<div class="paragraph"><p>The <em>sys.config</em> file is standard and
-<a href="http://www.erlang.org/doc/man/config.html">well documented</a>.
-The <em>vm.args</em> file is just an optionally multiline file
-containing all the flags to pass to the Erlang VM, for example
-<code>-name [email protected] -heart</code>.</p></div>
-<div class="paragraph"><p>Building OTP releases has always been a difficult task. Until now.</p></div>
+<div class="paragraph"><p>Building OTP releases has always been a difficult task. Tools like +Reltool or Rebar have made this simpler, but +it’s no panacea. This article will show you an alternative and +hopefully much simpler solution.</p></div> +<div class="paragraph"><p>There is two steps to building a release. First you need to build +the various OTP applications you want to include in the release. Once +done, you need to create the release itself, by including the Erlang +runtime system alongside the applications, a boot script to start the +node and all its applications, and some configuration files.</p></div> +<div class="paragraph"><p><a href="https://github.com/extend/erlang.mk">Erlang.mk</a> solves +the first step. It is an include file for GNU Make. Just +including it in a Makefile is enough to allow building your project, +fetching and building dependencies, building documentation, performing +static analysis and more.</p></div> +<div class="paragraph"><p><a href="https://github.com/erlware/relx">Relx</a> solves the second +step. It is a release creation tool, wrapped into a single executable +file. It doesn’t require a configuration file. And if you do need one, +it will be a pretty small one.</p></div> +<div class="paragraph"><p>Let’s take a look at the smallest Erlang.mk powered +Makefile. There is only one thing required: defining the project +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">PROJECT =</span> my_project + +include erlang.mk</tt></pre></div></div> +<div class="paragraph"><p>Simply doing this allows you to build your application by typing +<code>make</code>, running tests using <code>make tests</code>, and +more. It will even compile your <em>.dtl</em> files found in the +<em>templates/</em> directory if you are using ErlyDTL!</p></div> +<div class="paragraph"><p>Let’s now take a look at a simplified version of the Makefile for +this website. I only removed a few targets that were off-topic.</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> ninenines + +<span style="color: #009900">DEPS =</span> cowboy erlydtl +<span style="color: #009900">dep_cowboy_commit =</span> 0.8.5 +<span style="color: #009900">dep_erlydtl_commit =</span> 4d0dc8fb + +<span style="font-weight: bold"><span style="color: #000080">.PHONY:</span></span> release clean-release + +<span style="color: #990000">release:</span> clean-release all projects + relx -o rel<span style="color: #990000">/</span><span style="color: #009900">$(PROJECT)</span> + +<span style="color: #990000">clean-release:</span> clean-projects + rm -rf rel<span style="color: #990000">/</span><span style="color: #009900">$(PROJECT)</span> + +include erlang.mk</tt></pre></div></div> +<div class="paragraph"><p>You can see here how to define dependencies. First you list all +the dependency names, then you have one line per dependency, giving +the repository URL and the commit number, tag or branch you want.</p></div> +<div class="paragraph"><p>Then you can see two targets defined, with <code>release</code> +becoming the default target, because it was defined first. You can +override the default target <code>all</code>, which builds the +application and its dependencies, this way.</p></div> +<div class="paragraph"><p>And as you can see, the <code>release</code> target uses +Relx to build a release into the <em>rel/ninenines/</em> +directory. Let’s take a look at the configuration file for this 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: #FF6600">release</span>, {<span style="color: #FF6600">ninenines</span>, <span style="color: #FF0000">"1"</span>}, [<span style="color: #FF6600">ninenines</span>]}<span style="color: #990000">.</span> + +{<span style="color: #FF6600">extended_start_script</span>, <span style="color: #000080">true</span>}<span style="color: #990000">.</span> +{<span style="color: #FF6600">sys_config</span>, <span style="color: #FF0000">"rel/sys.config"</span>}<span style="color: #990000">.</span> + +{<span style="color: #FF6600">overlay</span>, [ + {<span style="color: #FF6600">mkdir</span>, <span style="color: #FF0000">"log"</span>}, + {<span style="color: #FF6600">copy</span>, <span style="color: #FF0000">"rel/vm.args"</span>, + <span style="color: #FF0000">"releases/\{\{release_name\}\}-\{\{release_version\}\}/vm.args"</span>} +]}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The first line defines a release named <code>ninenines</code>, which +has a version number <code>"1"</code> and includes one application, also +named <code>ninenines</code>, although it doesn’t have to.</p></div> +<div class="paragraph"><p>We then use the <code>extended_start_script</code> option to tell +Relx that we would like to have a start script that allows +us to not only start the release, but do so with the node in the +background, or also to allow us to connect to a running node, and so on. +This start script has the same features as the one tools like +Rebar generates.</p></div> +<div class="paragraph"><p>The rest of the file just makes sure our configuration files are +where we expect them. Relx will automatically take care +of your <em>sys.config</em> file as long as you tell it where to +find it. The <em>vm.args</em> file used by the extended start script +needs to be handled more explicitly by using an overlay however.</p></div> +<div class="paragraph"><p>How does Relx find what applications to include? +By looking at the application dependencies in the <em>.app</em> +file of each OTP application. Make sure you put all dependencies in +there, <em>including</em> library applications, and Relx +will find everything for you.</p></div> +<div class="paragraph"><p>For example, this release includes the following applications. +Only what’s strictly required.</p></div> +<div class="listingblock"> +<div class="content"> +<pre><code>compiler-4.9.1 crypto-2.3 kernel-2.16.1 ranch-0.8.3 syntax_tools-1.6.11 +cowboy-0.8.5 erlydtl-0.7.0 ninenines-0.2.0 stdlib-1.19.1</code></pre> +</div></div> +<div class="paragraph"><p>The <em>sys.config</em> file is standard and +<a href="http://www.erlang.org/doc/man/config.html">well documented</a>. +The <em>vm.args</em> file is just an optionally multiline file +containing all the flags to pass to the Erlang VM, for example +<code>-name [email protected] -heart</code>.</p></div> +<div class="paragraph"><p>Building OTP releases has always been a difficult task. Until now.</p></div> </article> </div> @@ -170,55 +194,107 @@ containing all the flags to pass to the Erlang VM, for example <h3>More articles</h3> <ul id="articles-nav" class="extra_margin"> - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + + <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + - <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + + <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + - <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + + <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + - <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + + <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + - <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + + <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + - <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + + <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + - <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + + <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + - <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + + <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + - <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + + <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + - <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + + <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + - <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + </ul> diff --git a/articles/erlanger-playbook-september-2015-update/index.html b/articles/erlanger-playbook-september-2015-update/index.html index 355e1d4f..64b2d558 100644 --- a/articles/erlanger-playbook-september-2015-update/index.html +++ b/articles/erlanger-playbook-september-2015-update/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: The Erlanger Playbook September 2015 Update</title> @@ -74,19 +74,19 @@ </p> </header> -<div class="paragraph"><p>An update to The Erlanger Playbook is now available!</p></div>
-<div class="paragraph"><p>The Erlanger Playbook is a book about software development using
-Erlang. It currently covers all areas from the conception, design,
-the writing of code, documentation and tests.</p></div>
-<div class="paragraph"><p>The book is still a work in progress. Future topics will include
-refactoring, debugging and tracing, benchmarking, releases, community
-management (for open source projects).</p></div>
-<div class="paragraph"><p>This update fixes a number of things and adds two chapters: IOlists
-and Erlang building blocks.</p></div>
-<div class="paragraph"><p>Learn more about <a href="/articles/erlanger-playbook">The Erlanger Playbook</a>!</p></div>
-<div class="paragraph"><p>This is a self-published ebook. The base price is 50€. All proceeds
-will be used to allow me to work on open source full time.</p></div>
-<div class="paragraph"><p>Thank you for helping me helping you help us all!</p></div>
+<div class="paragraph"><p>An update to The Erlanger Playbook is now available!</p></div> +<div class="paragraph"><p>The Erlanger Playbook is a book about software development using +Erlang. It currently covers all areas from the conception, design, +the writing of code, documentation and tests.</p></div> +<div class="paragraph"><p>The book is still a work in progress. Future topics will include +refactoring, debugging and tracing, benchmarking, releases, community +management (for open source projects).</p></div> +<div class="paragraph"><p>This update fixes a number of things and adds two chapters: IOlists +and Erlang building blocks.</p></div> +<div class="paragraph"><p>Learn more about <a href="/articles/erlanger-playbook">The Erlanger Playbook</a>!</p></div> +<div class="paragraph"><p>This is a self-published ebook. The base price is 50€. All proceeds +will be used to allow me to work on open source full time.</p></div> +<div class="paragraph"><p>Thank you for helping me helping you help us all!</p></div> </article> </div> @@ -95,55 +95,107 @@ will be used to allow me to work on open source full time.</p></div> <h3>More articles</h3> <ul id="articles-nav" class="extra_margin"> - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + - <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + + <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + - <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + + <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + - <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + + <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + - <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + + <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + - <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + + <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + - <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + + <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + - <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + + <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + - <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + + <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + - <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + + <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + - <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + + </ul> diff --git a/articles/erlanger-playbook/index.html b/articles/erlanger-playbook/index.html index cc6bd1fa..7d50cff8 100644 --- a/articles/erlanger-playbook/index.html +++ b/articles/erlanger-playbook/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: The Erlanger Playbook</title> @@ -74,87 +74,87 @@ </p> </header> -<div class="paragraph"><p>I am proud to announce the pre-release of The Erlanger Playbook.</p></div>
-<div class="paragraph"><p>The Erlanger Playbook is a book about software development using
-Erlang. It currently covers all areas from the conception, design,
-the writing of code, documentation and tests.</p></div>
-<div class="paragraph"><p>The book is still a work in progress. Future topics will include
-refactoring, debugging and tracing, benchmarking, releases, community
-management (for open source projects).</p></div>
-<div class="paragraph"><p>The following sections are currently available:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-About this book; Changelog; Future additions
-</p>
-</li>
-<li>
-<p>
-<em>Erlang:</em> Building blocks; Patterns
-</p>
-</li>
-<li>
-<p>
-<em>Workflow:</em> Think; Write; Stay productive
-</p>
-</li>
-<li>
-<p>
-<em>Documentation:</em> On documentation; Tutorials; User guide; Manual; README files
-</p>
-</li>
-<li>
-<p>
-<em>Design:</em> RESTful APIs; Lessons learned
-</p>
-</li>
-<li>
-<p>
-<em>Code:</em> Starting a project; Version control; Project structure; Code style; Best practices; Special processes; IOLists; The process dictionary
-</p>
-</li>
-<li>
-<p>
-<em>Tests:</em> On testing; Success typing analysis; Manual testing; Unit testing; Functional testing
-</p>
-</li>
-<li>
-<p>
-<em>Selling Erlang:</em> On persuasion; Don’t let it crash
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Read a preview: <a href="/res/erlanger-preview.pdf">Special processes</a></p></div>
-<div class="paragraph"><p>The book is currently 180 pages long. The final version
-of the book is planned to be between 200 and 250 pages.
-A print version of the book will be considered once the final
-version gets released. The printed book is <strong>not</strong> included
-in the price.</p></div>
-<div class="paragraph"><p>This is a self-published book. The base price is 50€. All proceeds
-will be used to allow me to work on open source full time.</p></div>
-<form action="https://www.paypal.com/cgi-bin/webscr" method="post" target="_top">
-<input type="hidden" name="cmd" value="_s-xclick">
-<input type="hidden" name="hosted_button_id" value="9M44HJCGX3GVN">
-<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_buynowCC_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
-<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1">
-</form>
-<div class="paragraph"><p>You are more than welcome to pay extra by using this second button.
-It allows you to set the price you want. Make sure to set it to at least
-50€ to receive the book.</p></div>
-<form action="https://www.paypal.com/cgi-bin/webscr" method="post" target="_top">
-<input type="hidden" name="cmd" value="_s-xclick">
-<input type="hidden" name="hosted_button_id" value="BBW9TR9LBK8C2">
-<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_buynowCC_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
-<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1">
-</form>
-<div class="paragraph"><p>Make sure to provide a valid email address.</p></div>
-<div class="paragraph"><p>There will be a <strong>delay</strong> between payment and sending of the book.
-This process is currently manual.</p></div>
-<div class="paragraph"><p>As the book is a pre-release, feedback is more than welcome. You can
-send your comments to erlanger@ this website.</p></div>
-<div class="paragraph"><p>The plan is to add content regularly until I run out of things to say.
-You will receive updates to the book for free as soon as they are available.</p></div>
-<div class="paragraph"><p>Huge thanks for your interest in buying this book!</p></div>
+<div class="paragraph"><p>I am proud to announce the pre-release of The Erlanger Playbook.</p></div> +<div class="paragraph"><p>The Erlanger Playbook is a book about software development using +Erlang. It currently covers all areas from the conception, design, +the writing of code, documentation and tests.</p></div> +<div class="paragraph"><p>The book is still a work in progress. Future topics will include +refactoring, debugging and tracing, benchmarking, releases, community +management (for open source projects).</p></div> +<div class="paragraph"><p>The following sections are currently available:</p></div> +<div class="ulist"><ul> +<li> +<p> +About this book; Changelog; Future additions +</p> +</li> +<li> +<p> +<em>Erlang:</em> Building blocks; Patterns +</p> +</li> +<li> +<p> +<em>Workflow:</em> Think; Write; Stay productive +</p> +</li> +<li> +<p> +<em>Documentation:</em> On documentation; Tutorials; User guide; Manual; README files +</p> +</li> +<li> +<p> +<em>Design:</em> RESTful APIs; Lessons learned +</p> +</li> +<li> +<p> +<em>Code:</em> Starting a project; Version control; Project structure; Code style; Best practices; Special processes; IOLists; The process dictionary +</p> +</li> +<li> +<p> +<em>Tests:</em> On testing; Success typing analysis; Manual testing; Unit testing; Functional testing +</p> +</li> +<li> +<p> +<em>Selling Erlang:</em> On persuasion; Don’t let it crash +</p> +</li> +</ul></div> +<div class="paragraph"><p>Read a preview: <a href="/res/erlanger-preview.pdf">Special processes</a></p></div> +<div class="paragraph"><p>The book is currently 180 pages long. The final version +of the book is planned to be between 200 and 250 pages. +A print version of the book will be considered once the final +version gets released. The printed book is <strong>not</strong> included +in the price.</p></div> +<div class="paragraph"><p>This is a self-published book. The base price is 50€. All proceeds +will be used to allow me to work on open source full time.</p></div> +<form action="https://www.paypal.com/cgi-bin/webscr" method="post" target="_top"> +<input type="hidden" name="cmd" value="_s-xclick"> +<input type="hidden" name="hosted_button_id" value="9M44HJCGX3GVN"> +<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_buynowCC_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!"> +<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1"> +</form> +<div class="paragraph"><p>You are more than welcome to pay extra by using this second button. +It allows you to set the price you want. Make sure to set it to at least +50€ to receive the book.</p></div> +<form action="https://www.paypal.com/cgi-bin/webscr" method="post" target="_top"> +<input type="hidden" name="cmd" value="_s-xclick"> +<input type="hidden" name="hosted_button_id" value="BBW9TR9LBK8C2"> +<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_buynowCC_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!"> +<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1"> +</form> +<div class="paragraph"><p>Make sure to provide a valid email address.</p></div> +<div class="paragraph"><p>There will be a <strong>delay</strong> between payment and sending of the book. +This process is currently manual.</p></div> +<div class="paragraph"><p>As the book is a pre-release, feedback is more than welcome. You can +send your comments to erlanger@ this website.</p></div> +<div class="paragraph"><p>The plan is to add content regularly until I run out of things to say. +You will receive updates to the book for free as soon as they are available.</p></div> +<div class="paragraph"><p>Huge thanks for your interest in buying this book!</p></div> </article> </div> @@ -163,55 +163,107 @@ You will receive updates to the book for free as soon as they are available.</p> <h3>More articles</h3> <ul id="articles-nav" class="extra_margin"> - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + - <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + + <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + - <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + + <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + - <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + + <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + - <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + + <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + - <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + + <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + - <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + + <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + - <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + + <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + - <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + + <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + - <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + + <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + - <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + + </ul> diff --git a/articles/farwest-funded/index.html b/articles/farwest-funded/index.html index a3280216..c36a91d8 100644 --- a/articles/farwest-funded/index.html +++ b/articles/farwest-funded/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Farwest got funded!</title> @@ -74,27 +74,27 @@ </p> </header> -<div class="paragraph"><p>This was a triumph! I’m making a note here: HUGE SUCCESS!!</p></div>
-<iframe frameborder="0" scrolling="no" height="400px" width"236px" seamless="seamless" src="https://api.bountysource.com/user/fundraisers/83/embed"></iframe>
-<div class="paragraph"><p>It’s hard to overstate my satisfaction. Thanks to everyone who
-made this possible.</p></div>
-<div class="paragraph"><p>If you have backed this fundraiser, and haven’t provided your
-personal details yet, please do so quickly so that your rewards
-can be sent!</p></div>
-<div class="paragraph"><p>I am hoping that we will be able to make good use of all that
-money. The details of the expenses will be published regularly
-on the <a href="https://github.com/extend/farwest/wiki/2013-Fundraiser">2013 Fundraiser wiki page</a>,
-giving you full disclosure as to how your money is used.</p></div>
-<div class="paragraph"><p>It will take a little time to get things started, we are in
-summer after all! We will however act quickly to make the
-prototype easy enough to use so that the paid UI work can
-begin. This is also when user contributions will be welcome.</p></div>
-<div class="paragraph"><p>You can see the <a href="https://github.com/extend/farwest/wiki/Roadmap">Roadmap</a>
-to get more information on the current plans. This document will
-get updated as time goes on so check again later to see if you
-can help!</p></div>
-<div class="paragraph"><p>Look at me: still talking when there’s open source to do!</p></div>
-<div class="paragraph"><p>Thanks again for all your support. I really appreciate it.</p></div>
+<div class="paragraph"><p>This was a triumph! I’m making a note here: HUGE SUCCESS!!</p></div> +<iframe frameborder="0" scrolling="no" height="400px" width"236px" seamless="seamless" src="https://api.bountysource.com/user/fundraisers/83/embed"></iframe> +<div class="paragraph"><p>It’s hard to overstate my satisfaction. Thanks to everyone who +made this possible.</p></div> +<div class="paragraph"><p>If you have backed this fundraiser, and haven’t provided your +personal details yet, please do so quickly so that your rewards +can be sent!</p></div> +<div class="paragraph"><p>I am hoping that we will be able to make good use of all that +money. The details of the expenses will be published regularly +on the <a href="https://github.com/extend/farwest/wiki/2013-Fundraiser">2013 Fundraiser wiki page</a>, +giving you full disclosure as to how your money is used.</p></div> +<div class="paragraph"><p>It will take a little time to get things started, we are in +summer after all! We will however act quickly to make the +prototype easy enough to use so that the paid UI work can +begin. This is also when user contributions will be welcome.</p></div> +<div class="paragraph"><p>You can see the <a href="https://github.com/extend/farwest/wiki/Roadmap">Roadmap</a> +to get more information on the current plans. This document will +get updated as time goes on so check again later to see if you +can help!</p></div> +<div class="paragraph"><p>Look at me: still talking when there’s open source to do!</p></div> +<div class="paragraph"><p>Thanks again for all your support. I really appreciate it.</p></div> </article> </div> @@ -103,55 +103,107 @@ can help!</p></div> <h3>More articles</h3> <ul id="articles-nav" class="extra_margin"> - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + - <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + + <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + - <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + + <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + - <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + + <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + - <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + + <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + - <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + + <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + - <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + + <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + - <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + + <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + - <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + + <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + - <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + + <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + - <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + + </ul> diff --git a/articles/index.html b/articles/index.html index dc52f5d1..ebc2bff4 100644 --- a/articles/index.html +++ b/articles/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Articles</title> @@ -80,9 +80,9 @@ </header> <p>Cowboy 2.0.0-rc.2 has been released! -
This is the new recommended version of Cowboy.
Its API should not change before release. While
you probably should not use it in production yet,
many do successfully. Use at your own risk. -
This new version contains fixes for the following
issues: -
HTTP/2 server push was using the wrong header
compression context.
HTTP/2 flow control could end up queueing data
in the wrong order when resuming the sending of
data.</p> + This is the new recommended version of Cowboy. Its API should not change before release. While you probably should not use it in production yet, many do successfully. Use at your own risk. + This new version contains fixes for the following issues: + HTTP/2 server push was using the wrong header compression context. HTTP/2 flow control could end up queueing data in the wrong order when resuming the sending of data.</p> <p style="text-align:right"> <a class="read_more" href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Read More</a> @@ -99,8 +99,8 @@ </header> <p>Cowboy 2.0.0-rc.1 has been released! -
This is the new recommended version of Cowboy.
Its API should not change before release. While
you probably should not use it in production yet,
many do successfully. Use at your own risk. -
The plan is to have a new RC version every couple
weeks until the summer ends or later if there are
still blocking issues open. Only issues that can’t
be fixed without making breaking changes to the
interface may block the release.</p> + This is the new recommended version of Cowboy. Its API should not change before release. While you probably should not use it in production yet, many do successfully. Use at your own risk. + The plan is to have a new RC version every couple weeks until the summer ends or later if there are still blocking issues open. Only issues that can’t be fixed without making breaking changes to the interface may block the release.</p> <p style="text-align:right"> <a class="read_more" href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Read More</a> @@ -116,8 +116,8 @@ </p> </header> - <p>Have you ever tried telling someone why they should use
Erlang? You boast the smaller code size, the auto healing
mechanisms, the distribution and they seem really excited.
They wonder why they never heard about Erlang before. And
then you show them what the code looks like. All excitement
goes away. The smiles disappear. Their face starts
becoming really serious. -
You lost them. You know you lost them. They comment on the
syntax, or perhaps you do, already admitting defeat.</p> + <p>Have you ever tried telling someone why they should use Erlang? You boast the smaller code size, the auto healing mechanisms, the distribution and they seem really excited. They wonder why they never heard about Erlang before. And then you show them what the code looks like. All excitement goes away. The smiles disappear. Their face starts becoming really serious. + You lost them. You know you lost them. They comment on the syntax, or perhaps you do, already admitting defeat.</p> <p style="text-align:right"> <a class="read_more" href="https://ninenines.eu/articles/the-elephant-in-the-room/">Read More</a> @@ -133,8 +133,8 @@ </p> </header> - <p>We have a specific mindset when writing Erlang
programs. We focus on the normal execution of the
program and don’t handle most of the errors that may
occur. We sometimes call this normal execution the
happy path. -
The general pattern behind writing only for the
happy path, letting the VM catch errors (writing
them to a log for future consumption) and then
having a supervisor restart the processes that
failed from a clean state, has a name.</p> + <p>We have a specific mindset when writing Erlang programs. We focus on the normal execution of the program and don’t handle most of the errors that may occur. We sometimes call this normal execution the happy path. + The general pattern behind writing only for the happy path, letting the VM catch errors (writing them to a log for future consumption) and then having a supervisor restart the processes that failed from a clean state, has a name.</p> <p style="text-align:right"> <a class="read_more" href="https://ninenines.eu/articles/dont-let-it-crash/">Read More</a> @@ -151,9 +151,9 @@ </header> <p>Cowboy 2.0.0-pre.4 has been released! -
This is the new recommended version of Cowboy.
While I would not recommend putting it in production
just yet, I do recommend you start writing new
applications with this Cowboy version. -
The most significant changes in the pre-release are: -
A new architecture: there now is one process per
connection and one process per request. This was
done because HTTP/2 allows running requests concurrently.</p> + This is the new recommended version of Cowboy. While I would not recommend putting it in production just yet, I do recommend you start writing new applications with this Cowboy version. + The most significant changes in the pre-release are: + A new architecture: there now is one process per connection and one process per request. This was done because HTTP/2 allows running requests concurrently.</p> <p style="text-align:right"> <a class="read_more" href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Read More</a> @@ -170,8 +170,8 @@ </header> <p>Ranch 1.3.0 has been released! -
This release fixes a number of long standing issues and adds
a small number of features: -
The ssl application has been added to the list of dependencies.
If you don’t need it, you can remove it automatically when fetching
Ranch or when building the release. If you do need it, you will no
longer have issues shutting down a node because of Ranch.</p> + This release fixes a number of long standing issues and adds a small number of features: + The ssl application has been added to the list of dependencies. If you don’t need it, you can remove it automatically when fetching Ranch or when building the release. If you do need it, you will no longer have issues shutting down a node because of Ranch.</p> <p style="text-align:right"> <a class="read_more" href="https://ninenines.eu/articles/ranch-1.3/">Read More</a> @@ -187,10 +187,10 @@ </p> </header> - <p>The old mailing list archives have been
added to the site, mainly for referencing purposes. -
The mailing list has been shut down and all personal information
has been deleted. -
If you need help with a project, consider either opening a ticket
on that project’s issues tracker or going through the community
channels (erlang-questions, #ninenines or #erlang on Freenode). -
Prefer tickets; often when people have issues it highlights an
underlying problem in the project or its documentation.</p> + <p>The old mailing list archives have been added to the site, mainly for referencing purposes. + The mailing list has been shut down and all personal information has been deleted. + If you need help with a project, consider either opening a ticket on that project’s issues tracker or going through the community channels (erlang-questions, #ninenines or #erlang on Freenode). + Prefer tickets; often when people have issues it highlights an underlying problem in the project or its documentation.</p> <p style="text-align:right"> <a class="read_more" href="https://ninenines.eu/articles/ml-archives/">Read More</a> @@ -207,8 +207,8 @@ </header> <p>Last week-end I updated the Nine Nines website. -
I switched to Hugo. The site is
now built from Asciidoc
documents. You probably saw me switch to Asciidoc
for documentation this past year. This is the
natural conclusion to that story. The great thing
is that with a little bit of Makefile magic I can
just copy the documentation files into Hugo and
poof, they appear on the website. -
I am very happy with that new setup.</p> + I switched to Hugo. The site is now built from Asciidoc documents. You probably saw me switch to Asciidoc for documentation this past year. This is the natural conclusion to that story. The great thing is that with a little bit of Makefile magic I can just copy the documentation files into Hugo and poof, they appear on the website. + I am very happy with that new setup.</p> <p style="text-align:right"> <a class="read_more" href="https://ninenines.eu/articles/website-update/">Read More</a> @@ -225,9 +225,9 @@ </header> <p>An update to The Erlanger Playbook is now available! -
The Erlanger Playbook is a book about software development using
Erlang. It currently covers all areas from the conception, design,
the writing of code, documentation and tests. -
The book is still a work in progress. Future topics will include
refactoring, debugging and tracing, benchmarking, releases, community
management (for open source projects). -
This update fixes a number of things and adds two chapters: IOlists
and Erlang building blocks.</p> + The Erlanger Playbook is a book about software development using Erlang. It currently covers all areas from the conception, design, the writing of code, documentation and tests. + The book is still a work in progress. Future topics will include refactoring, debugging and tracing, benchmarking, releases, community management (for open source projects). + This update fixes a number of things and adds two chapters: IOlists and Erlang building blocks.</p> <p style="text-align:right"> <a class="read_more" href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">Read More</a> @@ -244,9 +244,9 @@ </header> <p>I am proud to announce the pre-release of The Erlanger Playbook. -
The Erlanger Playbook is a book about software development using
Erlang. It currently covers all areas from the conception, design,
the writing of code, documentation and tests. -
The book is still a work in progress. Future topics will include
refactoring, debugging and tracing, benchmarking, releases, community
management (for open source projects). -
The following sections are currently available:</p> + The Erlanger Playbook is a book about software development using Erlang. It currently covers all areas from the conception, design, the writing of code, documentation and tests. + The book is still a work in progress. Future topics will include refactoring, debugging and tracing, benchmarking, releases, community management (for open source projects). + The following sections are currently available:</p> <p style="text-align:right"> <a class="read_more" href="https://ninenines.eu/articles/erlanger-playbook/">Read More</a> @@ -262,9 +262,9 @@ </p> </header> - <p>Yesterday I pushed Websocket permessage-deflate to
Cowboy master. I also pushed
a
change in the way the code validates UTF-8 data
(required for text and close frames as per the spec). -
When looking into why the permessage-deflate tests
in autobahntestsuite were taking such a long time, I
found that autobahn is using an adaptation of the
algorithm named Flexible
and Economical UTF-8 Decoder. This is the C99
implementation: -
// Copyright (c) 2008-2009 Bjoern Hoehrmann <bjoern@hoehrmann.</p> + <p>Yesterday I pushed Websocket permessage-deflate to Cowboy master. I also pushed a change in the way the code validates UTF-8 data (required for text and close frames as per the spec). + When looking into why the permessage-deflate tests in autobahntestsuite were taking such a long time, I found that autobahn is using an adaptation of the algorithm named Flexible and Economical UTF-8 Decoder. This is the C99 implementation: + // Copyright (c) 2008-2009 Bjoern Hoehrmann <bjoern@hoehrmann.</p> <p style="text-align:right"> <a class="read_more" href="https://ninenines.eu/articles/erlang-validate-utf8/">Read More</a> @@ -280,7 +280,7 @@ </p> </header> - <p>Last week I read a great article
on
contributing to open source by Alvaro Videla. He makes
many great points and I am in agreement with most of it.
This made me want to properly explain my point of view with
regard to open source and contributions. Unlike most open
source evangelism articles I will not talk about ideals or
any of that crap, but rather my personal feelings and
experience.</p> + <p>Last week I read a great article on contributing to open source by Alvaro Videla. He makes many great points and I am in agreement with most of it. This made me want to properly explain my point of view with regard to open source and contributions. Unlike most open source evangelism articles I will not talk about ideals or any of that crap, but rather my personal feelings and experience.</p> <p style="text-align:right"> <a class="read_more" href="https://ninenines.eu/articles/on-open-source/">Read More</a> @@ -296,7 +296,7 @@ </p> </header> - <p>As I am away from home with little to do (some call this
a vacation) I wanted to reflect a little on the story so far,
or how I arrived to Erlang and got to where I am now. The
raw personal experience. It’ll be an article that’s more
about social aspect, communities and marketing a project than
technical considerations. As a period piece, it will also
allow me to reflect on the evolution of Erlang in recent
years.</p> + <p>As I am away from home with little to do (some call this a vacation) I wanted to reflect a little on the story so far, or how I arrived to Erlang and got to where I am now. The raw personal experience. It’ll be an article that’s more about social aspect, communities and marketing a project than technical considerations. As a period piece, it will also allow me to reflect on the evolution of Erlang in recent years.</p> <p style="text-align:right"> <a class="read_more" href="https://ninenines.eu/articles/the-story-so-far/">Read More</a> @@ -312,8 +312,8 @@ </p> </header> - <p>Now that Cowboy 1.0 is out, I can spend some of my time thinking
about Cowboy 2.0 that will be released soon after Erlang/OTP 18.0.
This entry discusses the proposed changes to query string handling
in Cowboy. -
Cowboy 2.0 will respond to user wishes by simplifying the interface
of the cowboy_req module. Users want two things: less
juggling with the Req variable, and more maps. Maps is the only
dynamic key/value data structure in Erlang that we can match directly
to extract values, allowing users to greatly simplify their code as
they don’t need to call functions to do everything anymore.</p> + <p>Now that Cowboy 1.0 is out, I can spend some of my time thinking about Cowboy 2.0 that will be released soon after Erlang/OTP 18.0. This entry discusses the proposed changes to query string handling in Cowboy. + Cowboy 2.0 will respond to user wishes by simplifying the interface of the cowboy_req module. Users want two things: less juggling with the Req variable, and more maps. Maps is the only dynamic key/value data structure in Erlang that we can match directly to extract values, allowing users to greatly simplify their code as they don’t need to call functions to do everything anymore.</p> <p style="text-align:right"> <a class="read_more" href="https://ninenines.eu/articles/cowboy2-qs/">Read More</a> @@ -329,9 +329,9 @@ </p> </header> - <p>I will now be regularly writing posts about project status, plans
and hopes for the future. -
Before that though, there’s one important news to share. -
Until a year ago all development was financed through consulting
and development services. This worked alright but too much time was
spent doing things that didn’t benefit the open source projects.
And that didn’t make me happy at all. Because I like being happy
I stopped that for the most part and spent the year figuring things
out, experimenting and discussing with people about it.</p> + <p>I will now be regularly writing posts about project status, plans and hopes for the future. + Before that though, there’s one important news to share. + Until a year ago all development was financed through consulting and development services. This worked alright but too much time was spent doing things that didn’t benefit the open source projects. And that didn’t make me happy at all. Because I like being happy I stopped that for the most part and spent the year figuring things out, experimenting and discussing with people about it.</p> <p style="text-align:right"> <a class="read_more" href="https://ninenines.eu/articles/january-2014-status/">Read More</a> @@ -348,9 +348,9 @@ </header> <p>This was a triumph! I’m making a note here: HUGE SUCCESS!! -
It’s hard to overstate my satisfaction. Thanks to everyone who
made this possible. -
If you have backed this fundraiser, and haven’t provided your
personal details yet, please do so quickly so that your rewards
can be sent! -
I am hoping that we will be able to make good use of all that
money. The details of the expenses will be published regularly
on the 2013 Fundraiser wiki page,
giving you full disclosure as to how your money is used.</p> + It’s hard to overstate my satisfaction. Thanks to everyone who made this possible. + If you have backed this fundraiser, and haven’t provided your personal details yet, please do so quickly so that your rewards can be sent! + I am hoping that we will be able to make good use of all that money. The details of the expenses will be published regularly on the 2013 Fundraiser wiki page, giving you full disclosure as to how your money is used.</p> <p style="text-align:right"> <a class="read_more" href="https://ninenines.eu/articles/farwest-funded/">Read More</a> @@ -366,8 +366,8 @@ </p> </header> - <p>Building OTP releases has always been a difficult task. Tools like
Reltool or Rebar have made this simpler, but
it’s no panacea. This article will show you an alternative and
hopefully much simpler solution. -
There is two steps to building a release. First you need to build
the various OTP applications you want to include in the release. Once
done, you need to create the release itself, by including the Erlang
runtime system alongside the applications, a boot script to start the
node and all its applications, and some configuration files.</p> + <p>Building OTP releases has always been a difficult task. Tools like Reltool or Rebar have made this simpler, but it’s no panacea. This article will show you an alternative and hopefully much simpler solution. + There is two steps to building a release. First you need to build the various OTP applications you want to include in the release. Once done, you need to create the release itself, by including the Erlang runtime system alongside the applications, a boot script to start the node and all its applications, and some configuration files.</p> <p style="text-align:right"> <a class="read_more" href="https://ninenines.eu/articles/erlang.mk-and-relx/">Read More</a> @@ -383,9 +383,9 @@ </p> </header> - <p>Today we will start the work on the intermediate module
that will be used to run the code for the expressions found
in our file’s body, replacing our interpreter. -
This is what we want to have when all the work is done: -
xerl -> tokens -> AST -> intermediate -> cerl
Today we will perform this work only on the atomic integer
expression however, so we will not build any module at the end.</p> + <p>Today we will start the work on the intermediate module that will be used to run the code for the expressions found in our file’s body, replacing our interpreter. + This is what we want to have when all the work is done: + xerl -> tokens -> AST -> intermediate -> cerl Today we will perform this work only on the atomic integer expression however, so we will not build any module at the end.</p> <p style="text-align:right"> <a class="read_more" href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Read More</a> @@ -401,10 +401,10 @@ </p> </header> - <p>As promised we are adding an expression separator this time.
This will be short and easy. -
In the tokenizer we only need to add a line recognizing the
comma as a valid token. -
, : {token, {',', TokenLine}}.
Then we need to change the following lines in the parser: -
exprs -> expr : ['$1'].
exprs -> expr exprs : ['$1' | '$2'].
And add a comma between the expressions on the second line:</p> + <p>As promised we are adding an expression separator this time. This will be short and easy. + In the tokenizer we only need to add a line recognizing the comma as a valid token. + , : {token, {',', TokenLine}}. Then we need to change the following lines in the parser: + exprs -> expr : ['$1']. exprs -> expr exprs : ['$1' | '$2']. And add a comma between the expressions on the second line:</p> <p style="text-align:right"> <a class="read_more" href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Read More</a> @@ -420,8 +420,8 @@ </p> </header> - <p>I would like to share some experience and theories on
Erlang scalability. -
This will be in the form of a series of hints, which
may or may not be accompanied with explanations as to why
things are this way, or how they improve or reduce the scalability
of a system. I will try to do my best to avoid giving falsehoods,
even if that means a few things won’t be explained.</p> + <p>I would like to share some experience and theories on Erlang scalability. + This will be in the form of a series of hints, which may or may not be accompanied with explanations as to why things are this way, or how they improve or reduce the scalability of a system. I will try to do my best to avoid giving falsehoods, even if that means a few things won’t be explained.</p> <p style="text-align:right"> <a class="read_more" href="https://ninenines.eu/articles/erlang-scalability/">Read More</a> diff --git a/articles/index.xml b/articles/index.xml index 57beccf0..249e5d71 100644 --- a/articles/index.xml +++ b/articles/index.xml @@ -1,13 +1,15 @@ <?xml version="1.0" encoding="utf-8" standalone="yes" ?> <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"> <channel> - <title>Articles-rsses on Nine Nines</title> - <link>https://ninenines.eu/articles/index.xml</link> - <description>Recent content in Articles-rsses on Nine Nines</description> + <title>Articles on Nine Nines</title> + <link>https://ninenines.eu/articles/</link> + <description>Recent content in Articles on Nine Nines</description> <generator>Hugo -- gohugo.io</generator> <language>en-us</language> <lastBuildDate>Wed, 23 Aug 2017 18:00:00 +0100</lastBuildDate> - <atom:link href="https://ninenines.eu/articles/index.xml" rel="self" type="application/rss+xml" /> + + <atom:link href="https://ninenines.eu/articles/index.xml" rel="self" type="application/rss+xml" /> + <item> <title>Cowboy 2.0 release candidate 2</title> @@ -15,42 +17,10 @@ <pubDate>Wed, 23 Aug 2017 18:00:00 +0100</pubDate> <guid>https://ninenines.eu/articles/cowboy-2.0.0-rc.2/</guid> - <description><div class="paragraph"><p>Cowboy <code>2.0.0-rc.2</code> has been released!</p></div>
-<div class="paragraph"><p>This is the new recommended version of Cowboy.
-Its API should not change before release. While
-you probably should not use it in production yet,
-many do successfully. Use at your own risk.</p></div>
-<div class="paragraph"><p>This new version contains fixes for the following
-issues:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-HTTP/2 server push was using the wrong header
- compression context.
-</p>
-</li>
-<li>
-<p>
-HTTP/2 flow control could end up queueing data
- in the wrong order when resuming the sending of
- data.
-</p>
-</li>
-<li>
-<p>
-The <code>shutdown</code> timeout was not implemented
- and request processes could be killed too quickly.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>What else is new in Cowboy 2.0? Check the
-<a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1">rc.1 announcement</a>.</p></div>
-<div class="paragraph"><p>Please test this new release candidate and provide
-feedback! The best place to provide feedback is via
-tickets. Do not hesitate to open a ticket or bring
-an existing ticket to my attention to get it resolved
-before 2.0.</p></div>
-</description> + <description>Cowboy 2.0.0-rc.2 has been released! + This is the new recommended version of Cowboy. Its API should not change before release. While you probably should not use it in production yet, many do successfully. Use at your own risk. + This new version contains fixes for the following issues: + HTTP/2 server push was using the wrong header compression context. HTTP/2 flow control could end up queueing data in the wrong order when resuming the sending of data.</description> </item> <item> @@ -59,63 +29,9 @@ before 2.0.</p></div> <pubDate>Mon, 24 Jul 2017 18:00:00 +0100</pubDate> <guid>https://ninenines.eu/articles/cowboy-2.0.0-rc.1/</guid> - <description><div class="paragraph"><p>Cowboy <code>2.0.0-rc.1</code> has been released!</p></div>
-<div class="paragraph"><p>This is the new recommended version of Cowboy.
-Its API should not change before release. While
-you probably should not use it in production yet,
-many do successfully. Use at your own risk.</p></div>
-<div class="paragraph"><p>The plan is to have a new RC version every couple
-weeks until the summer ends or later if there are
-still blocking issues open. Only issues that can&#8217;t
-be fixed without making breaking changes to the
-interface may block the release.</p></div>
-<div class="paragraph"><p>Numerous changes were made since Cowboy 1.0. The
-one most people care about is probably HTTP/2, but
-it&#8217;s most likely not the only one worthwhile. The
-full list of changes (excluding types) can be found
-in the user guide chapter
-<a href="https://ninenines.eu/docs/en/cowboy/2.0/guide/migrating_from_1.0/">Migrating from Cowboy 1.0 to 2.0</a>.</p></div>
-<div class="paragraph"><p>As this is not the full release just yet, please pay
-extra attention to details and report anything
-suspicious you find.</p></div>
-<div class="paragraph"><p>There are still some tests failing. Most of those are
-related to standards that are not being followed perfectly
-just yet. Some of those will probably not be fixed before
-Cowboy 2.0 is released. They are edge cases and should not
-prevent interoperability.</p></div>
-<div class="paragraph"><p>The manual received a lot of love. It now has one page per
-function with a detailed description, arguments list, return
-value, changelog and examples. It also links to the other
-relevant manual pages: <a href="https://ninenines.eu/docs/en/cowboy/2.0/manual/">https://ninenines.eu/docs/en/cowboy/2.0/manual/</a></p></div>
-<div class="paragraph"><p>Cowboy is now tested and supported with Erlang/OTP 19.0 or above
-on Arch Linux, FreeBSD, OSX, Ubuntu and Windows 7. Contact me
-if you can provide permanent access to another platform for the
-purposes of testing.</p></div>
-<div class="paragraph"><p>Cowboy is now available from four locations:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="https://git.ninenines.eu/cowboy.git">https://git.ninenines.eu/cowboy.git</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://github.com/ninenines/cowboy.git">https://github.com/ninenines/cowboy.git</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://bitbucket.org/ninenines/cowboy.git">https://bitbucket.org/ninenines/cowboy.git</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://gitlab.com/ninenines/cowboy.git">https://gitlab.com/ninenines/cowboy.git</a>
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>They are updated at the same time so there is no real difference.</p></div>
-</description> + <description>Cowboy 2.0.0-rc.1 has been released! + This is the new recommended version of Cowboy. Its API should not change before release. While you probably should not use it in production yet, many do successfully. Use at your own risk. + The plan is to have a new RC version every couple weeks until the summer ends or later if there are still blocking issues open. Only issues that can&#8217;t be fixed without making breaking changes to the interface may block the release.</description> </item> <item> @@ -124,140 +40,8 @@ purposes of testing.</p></div> <pubDate>Sun, 26 Mar 2017 00:00:00 +0100</pubDate> <guid>https://ninenines.eu/articles/the-elephant-in-the-room/</guid> - <description><div class="paragraph"><p>Have you ever tried telling someone why they should use
-Erlang? You boast the smaller code size, the auto healing
-mechanisms, the distribution and they seem really excited.
-They wonder why they never heard about Erlang before. And
-then you show them what the code looks like. All excitement
-goes away. The smiles disappear. Their face starts
-becoming really serious.</p></div>
-<div class="paragraph"><p>You lost them. You know you lost them. They comment on the
-syntax, or perhaps you do, already admitting defeat. It&#8217;s
-unlike anything they have ever used before. And they will
-most likely end up not using it.</p></div>
-<div class="paragraph"><p>What about people who already know what the syntax looks
-like? As soon as you mention Erlang, the topic of the syntax
-comes in. It&#8217;s like nothing else matters.</p></div>
-<div class="paragraph"><p>Perhaps the topic of syntax didn&#8217;t come up. But they&#8217;re
-still not going to try Erlang because of it.</p></div>
-<div class="paragraph"><p>You&#8217;re probably not having these kinds of interactions at
-Erlang conferences. This doesn&#8217;t happen with people who are
-already somewhat interested in, or need, the features that
-Erlang provides. With them the syntax is at worst a minor
-inconvenience.</p></div>
-<div class="paragraph"><p>This happens because most developers are familiar with
-syntaxes that look nothing like Erlang. To be clear, I
-include language features and other concepts like objects
-as part of "syntax" here. Familiarity is a very important
-factor to drive adoption.</p></div>
-<div class="paragraph"><p>You can see an example of that in the Elixir world, where
-the majority of people come from Ruby or already knew and
-liked Ruby. The 2016 survey tells us that 59% of Elixir
-developers were using Ruby primarily before. That&#8217;s in
-large part because of the syntax. They will deny it of
-course and find other reasons. And yet, we don&#8217;t see such
-a strong adoption of Erlang from Ruby developers, before
-or after Elixir appeared.</p></div>
-<div class="paragraph"><p>Side note: have you ever wondered why the Elixir community
-is, I quote, much friendlier than the Ruby community?
-Despite having much of the same people?</p></div>
-<div class="paragraph"><p>Before we continue, let me be clear. I love the Erlang
-syntax. It is simple and explicit. It is powerful, especially
-when dealing with binary data. It has very few quirks.
-It has little to no ambiguity. It&#8217;s great. Except for
-persuading people to use it.</p></div>
-<div class="paragraph"><p>Over the years I have been writing Erlang, I have seen
-very few people point out that the syntax slows down
-adoption. We have no problem with it, so why would others?
-At the same time, people coming to Erlang come to solve
-a real problem they&#8217;re having, so the syntax is fairly
-secondary. Even if they hate it at first, they know they
-can solve their problems despite the syntax.</p></div>
-<div class="paragraph"><p>You don&#8217;t build a popular product or language by solving
-people&#8217;s problems though. In general you end up solving
-some problems and creating new problems. No, you build
-a popular product by <strong>convincing people to use it</strong>. And
-you make them stay with your product by making them
-<strong>commit</strong> to using it.</p></div>
-<div class="paragraph"><p>Take MongoDB for example. It didn&#8217;t become popular by
-working, or even by being practical. It wasn&#8217;t performing
-its primary function and was losing people&#8217;s data. That
-didn&#8217;t stop it from becoming popular. Smart people would
-knowingly use a database that was losing data. Think about
-that for a minute.</p></div>
-<div class="paragraph"><p>MongoDB of course had a huge marketing machine, and they
-focused on that. They helped organize many meetups all
-over the world, complete with various swag items given
-for free, including a small handbook about MongoDB. All
-people had to do was show up.</p></div>
-<div class="paragraph"><p>They didn&#8217;t go tell people to look at all the weaknesses
-their product had. They focused on the strengths. On
-what would convince people to try it. They would go
-to meetups, discuss with others, commit to try it (or
-try it at meetups directly), and by doing so sell MongoDB
-to themselves.</p></div>
-<div class="paragraph"><p>How do we get people to meetups though? That&#8217;d be the
-first step: you need to <strong>catch their attention</strong>.
-I believe MongoDB did this using benchmark results.
-Ironic isn&#8217;t it? MongoDB gets fast benchmark results
-because they lose data, and this gets everyone to buy
-into the product.</p></div>
-<div class="paragraph"><p>The key points to remember about this are:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-catch people&#8217;s attention
-</p>
-</li>
-<li>
-<p>
-show your product&#8217;s strengths
-</p>
-</li>
-<li>
-<p>
-make people take a commitment
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Once they commit to something, you win. Everyone will not
-end up ultimately using your product of course, but it&#8217;s
-at the very least become a consideration. It&#8217;s on their
-mind. Their resolve will be stronger when they ultimately
-try it and inevitably run into issues.</p></div>
-<div class="paragraph"><p>Erlang&#8217;s syntax is a weakness. Almost nobody looks at the
-Erlang syntax and falls in love with it at first sight.
-No, it takes time to learn it and understand how good it
-is. You need to sell Erlang to people without showing
-the Erlang syntax. If you do show it, then you need to
-hide the parts that feel alien. Function calls are OK.
-Recursion, not so much. Maps are OK. Records, not.</p></div>
-<div class="paragraph"><p>Avoiding code is not always possible when you try
-to sell it, especially to developers. You can however
-prepare them to accept the alien syntax by admitting
-that the syntax is not perfect before you show it.
-You can do this while praising it at the same time.
-For example, "the syntax is a little out there, but
-it matches the concepts perfectly, it will all make
-sense when you start learning".</p></div>
-<div class="paragraph"><p>This might not be the best introduction. Someone will
-need to A/B test it to find the one that gives the
-best results. But that should give you ideas.</p></div>
-<div class="paragraph"><p>When something terrible happens, mentioning that this
-isn&#8217;t the end of the world <strong>before</strong> you tell others what
-happened will soften their reaction. When someone
-breaks your favorite item and cries over it calling
-themselves stupid, it&#8217;s harder to get mad at them,
-compared to the same event with no emotional reaction.</p></div>
-<div class="paragraph"><p>Our behavior is largely dependent on what&#8217;s at the
-top of our mind, so it&#8217;s up to you to take advantage
-of this to make your case in the best conditions.</p></div>
-<div class="paragraph"><p>Next time you try to make someone use Erlang, remember
-that you should aim for getting a spoken commitment
-out of them, if possible before you show the syntax.
-If that&#8217;s not possible, then prepare them to accept
-the flaws or the weirdness before they see them.</p></div>
-</description> + <description>Have you ever tried telling someone why they should use Erlang? You boast the smaller code size, the auto healing mechanisms, the distribution and they seem really excited. They wonder why they never heard about Erlang before. And then you show them what the code looks like. All excitement goes away. The smiles disappear. Their face starts becoming really serious. + You lost them. You know you lost them. They comment on the syntax, or perhaps you do, already admitting defeat.</description> </item> <item> @@ -266,119 +50,8 @@ the flaws or the weirdness before they see them.</p></div> <pubDate>Sun, 22 Jan 2017 00:00:00 +0100</pubDate> <guid>https://ninenines.eu/articles/dont-let-it-crash/</guid> - <description><div class="paragraph"><p>We have a specific mindset when writing Erlang
-programs. We focus on the normal execution of the
-program and don&#8217;t handle most of the errors that may
-occur. We sometimes call this normal execution the
-<em>happy path</em>.</p></div>
-<div class="paragraph"><p>The general pattern behind writing only for the
-<em>happy path</em>, letting the VM catch errors (writing
-them to a log for future consumption) and then
-having a supervisor restart the processes that
-failed from a clean state, has a name. We call it
-<em>let it crash</em>; and it drives many of our design
-decisions.</p></div>
-<div class="paragraph"><p>It&#8217;s a really great way to program and the results
-are fantastic compared to most other programming
-languages. And yet, <em>let it crash</em> barely convinced
-anyone that they should use Erlang. Why would that
-be?</p></div>
-<div class="paragraph"><p>You may already know that Cowboy is capable of
-handling at least 2 million Websocket connections
-on a single server. This is in large part thanks
-to the capabilities of the VM. Still, 2 million
-is good, much better than most other servers can
-do.</p></div>
-<div class="paragraph"><p>Cowboy is not just a Websocket server; it&#8217;s also
-an HTTP and HTTP/2 server, and it handles many
-related features like long polling or the parsing
-of most request headers.</p></div>
-<div class="paragraph"><p>Can you guess how large the Cowboy codebase is,
-without looking at the source?</p></div>
-<div class="paragraph"><p>Do make sure you have a clear answer in your mind
-before you go check.</p></div>
-<div class="paragraph"><p>Good, you are back. Now what were the results? If
-I am correct, you overestimated the size of Cowboy.
-Cowboy is in fact about five thousand lines of code.
-You probably thought it was at least ten thousand.
-About eighty percent of readers will have
-overestimated the size of Cowboy. And you did only
-because I mentioned it can handle millions of
-Websocket connections.</p></div>
-<div class="paragraph"><p>Numerous studies show this effect. Just mentioning
-the large number already prepared your mind to think
-in that direction. Repeating the number made you
-focus even more on it. Then the question asked for
-a number, which ended up larger than the reality.</p></div>
-<div class="paragraph"><p>The same effect can be applied to negotiation for
-example. You generally want to start by giving your
-offer (and not let the other party initiate) and
-you want to give a really large number first. You
-can also prepare your customer by mentioning an even
-larger number in the previous discussion.</p></div>
-<div class="paragraph"><p>And it&#8217;s not just numbers either. An experiment
-showed that just by looking at an image of clouds,
-customers of a pillow store were buying pillows
-more comfortable (and more expensive) than those
-who didn&#8217;t see that image.</p></div>
-<div class="paragraph"><p>This is the power of associations. It is covered in
-much larger detail in the books
-<a href="https://www.amazon.com/Influence-Psychology-Persuasion-Robert-Cialdini/dp/006124189X">Influence</a>
-and
-<a href="https://www.amazon.com/Pre-Suasion-Revolutionary-Way-Influence-Persuade/dp/1501109790">Pre-suasion</a>.
-I highly recommend reading those and applying what
-you learn to your daily life. I&#8217;m definitely not
-a professional psychologist so take this post with
-a grain of salt.</p></div>
-<div class="paragraph"><p>When selling Erlang, whether we are selling it to
-a customer or trying to convince a developer friend
-to start using it, we often talk about how Erlang
-<em>lets you sleep at night</em>, that it is auto healing
-and always gets fantastic uptimes.</p></div>
-<div class="paragraph"><p>And then we talk about <em>let it crash</em>.</p></div>
-<div class="paragraph"><p>And we describe what it means.</p></div>
-<div class="paragraph"><p>We might as well just say that Erlang crashes a lot
-and then take the door. It would have the same effect.
-It doesn&#8217;t even stop at programs crashing. You know
-what else crashes? Cars, planes, trains. Often with
-disastrous consequences. Is that really the message
-we want to convey?</p></div>
-<div class="paragraph"><p>They even <a href="https://img.youtube.com/vi/oEUBW2lCkIk/0.jpg">printed it on a t-shirt</a>!
-Keep calm and let it crash. It&#8217;s the kind of t-shirt
-you probably shouldn&#8217;t wear in an airport, and for good
-reasons. A few people did, then realized what they were
-wearing and were not too smug about it.</p></div>
-<div class="paragraph"><p>And yet this is how we sell Erlang.</p></div>
-<div class="paragraph"><p>A better way would be to focus on the positives, of
-course, but also to make sure that those positives
-are phrased in a way that prevents bad associations
-to be formed in people&#8217;s minds.</p></div>
-<div class="paragraph"><p>Instead of <em>let it crash</em>, you can say that Erlang
-has <em>auto healing mechanisms</em>. Healing is a good
-thing and accurately describes what happens in the
-system.</p></div>
-<div class="paragraph"><p>Should you need to go into more details, you will
-probably want to avoid <em>recover from crashes</em> and
-instead say <em>recover from exceptions</em>. Exceptions
-are a pretty neutral word and, should you explain
-what you mean by that, you can talk about exceptions
-that occur for reasons unrelated to Erlang, like
-hardware failure or network instability.</p></div>
-<div class="paragraph"><p>The trick is to always use positive words and
-phrases to describe Erlang, and to use external
-factors to explain how Erlang deals with failures.
-Never mention the failures internal to Erlang
-systems unless you are asked specifically, in
-which case you can say that the auto healing
-applies to all exceptions.</p></div>
-<div class="paragraph"><p>The <em>let it crash</em> philosophy is great when
-learning Erlang or when writing fault-tolerant
-systems. But it&#8217;s not going to convince anyone
-to use it unless they were already looking for
-it.</p></div>
-<div class="paragraph"><p>Do you like this post? Tell me on Twitter. I might
-make more.</p></div>
-</description> + <description>We have a specific mindset when writing Erlang programs. We focus on the normal execution of the program and don&#8217;t handle most of the errors that may occur. We sometimes call this normal execution the happy path. + The general pattern behind writing only for the happy path, letting the VM catch errors (writing them to a log for future consumption) and then having a supervisor restart the processes that failed from a clean state, has a name.</description> </item> <item> @@ -387,117 +60,10 @@ make more.</p></div> <pubDate>Tue, 03 Jan 2017 00:00:00 +0100</pubDate> <guid>https://ninenines.eu/articles/cowboy-2.0.0-pre.4/</guid> - <description><div class="paragraph"><p>Cowboy <code>2.0.0-pre.4</code> has been released!</p></div>
-<div class="paragraph"><p>This is the new recommended version of Cowboy.
-While I would not recommend putting it in production
-just yet, I do recommend you start writing new
-applications with this Cowboy version.</p></div>
-<div class="paragraph"><p>The most significant changes in the pre-release are:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-A new architecture: there now is one process per
- connection and one process per request. This was
- done because HTTP/2 allows running requests concurrently.
-</p>
-</li>
-<li>
-<p>
-Stream handlers. Every request, response and data goes
- through stream handlers. They are meant to replace hooks
- and more. They will be documented in a future pre-release.
- Check <code>cowboy_stream</code> and <code>cowboy_stream_h</code> if interested.
-</p>
-</li>
-<li>
-<p>
-Numerous changes to the <code>cowboy_req</code> interface. This
- is very close to final. Check the manual for what changed.
-</p>
-</li>
-<li>
-<p>
-The Req object is no longer passed in Websocket callbacks.
-</p>
-</li>
-<li>
-<p>
-It is now possible to send frames directly from <code>websocket_init/1</code>.
-</p>
-</li>
-<li>
-<p>
-SPDY support was removed, now that we have HTTP/2.
-</p>
-</li>
-<li>
-<p>
-Update Ranch to 1.3. We still depend on Cowlib master
- for the time being.
-</p>
-</li>
-<li>
-<p>
-A much improved manual.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>The manual received a lot of love. It now has one page per
-function with a detailed description, arguments list, return
-value, changelog and examples. It also links to the other
-relevant manual pages: <a href="https://ninenines.eu/docs/en/cowboy/2.0/manual/">https://ninenines.eu/docs/en/cowboy/2.0/manual/</a></p></div>
-<div class="paragraph"><p>I am quite proud of the manual right now. While more
-improvements can be made, what we have now is way better
-than before. Feedback for further improvements is welcome!</p></div>
-<div class="paragraph"><p>This is a significant step toward Cowboy 2.0. Almost all
-the breaking changes are in. A few more pre-releases are
-planned and will be released on a weekly basis (with exceptions).</p></div>
-<div class="paragraph"><p>Cowboy is now tested and supported with Erlang/OTP 18.0 or above
-on Arch Linux, FreeBSD, OSX, Ubuntu and Windows 7. Contact me
-if you can provide permanent access to another platform for the
-purposes of testing.</p></div>
-<div class="paragraph"><p>Cowboy is now available from four locations:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="https://git.ninenines.eu/cowboy.git">https://git.ninenines.eu/cowboy.git</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://github.com/ninenines/cowboy.git">https://github.com/ninenines/cowboy.git</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://bitbucket.org/ninenines/cowboy.git">https://bitbucket.org/ninenines/cowboy.git</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://gitlab.com/ninenines/cowboy.git">https://gitlab.com/ninenines/cowboy.git</a>
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>They are updated at the same time so there is no real difference.</p></div>
-<div class="paragraph"><p>Cowboy 2.0 will be released once all the breaking changes
-are completed and the temporarily removed features are
-added back.</p></div>
-<div class="paragraph"><p>Thanks for your patience. I know it took a long time.</p></div>
-<hr/>
-<div class="paragraph"><p>Half-price on all donations because I need a new hat:</p></div>
-<form action="https://www.paypal.com/cgi-bin/webscr" method="post" style="display:inline">
-<input type="hidden" name="cmd" value="_donations">
-<input type="hidden" name="business" value="[email protected]">
-<input type="hidden" name="lc" value="FR">
-<input type="hidden" name="item_name" value="Loic Hoguin">
-<input type="hidden" name="item_number" value="99s">
-<input type="hidden" name="currency_code" value="EUR">
-<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHosted">
-<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
-<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1">
-</form>
-</description> + <description>Cowboy 2.0.0-pre.4 has been released! + This is the new recommended version of Cowboy. While I would not recommend putting it in production just yet, I do recommend you start writing new applications with this Cowboy version. + The most significant changes in the pre-release are: + A new architecture: there now is one process per connection and one process per request. This was done because HTTP/2 allows running requests concurrently.</description> </item> <item> @@ -506,89 +72,9 @@ added back.</p></div> <pubDate>Mon, 28 Nov 2016 00:00:00 +0100</pubDate> <guid>https://ninenines.eu/articles/ranch-1.3/</guid> - <description><div class="paragraph"><p>Ranch <code>1.3.0</code> has been released!</p></div>
-<div class="paragraph"><p>This release fixes a number of long standing issues and adds
-a small number of features:</p></div>
-<div class="paragraph"><p>The <code>ssl</code> application has been added to the list of dependencies.
-If you don&#8217;t need it, you can remove it automatically when fetching
-Ranch or when building the release. If you do need it, you will no
-longer have issues shutting down a node because of Ranch.</p></div>
-<div class="paragraph"><p>The <code>ranch:info/0</code> and <code>ranch:procs/2</code> can be used to retrieve
-information about Ranch&#8217;s state. Use it for diagnostic and
-discovery purposes.</p></div>
-<div class="paragraph"><p>SSL listeners can now be configured without a certificate, for setups
-that make use of the SNI extension.</p></div>
-<div class="paragraph"><p>Transport options are now a blacklist, meaning all unknown options
-will be accepted. However Dialyzer will warn if said option is not
-defined in Ranch&#8217;s type specifications. Please send a patch when that
-happens!</p></div>
-<div class="paragraph"><p>Various bugs have been fixed, including the bug where the
-number of active connections could become negative. Common
-errors at listener startup should be easier to read (for
-example when the port is already in use).</p></div>
-<div class="paragraph"><p>See the <a href="https://git.ninenines.eu/ranch.git/plain/CHANGELOG.asciidoc">CHANGELOG</a>
-for more details.</p></div>
-<div class="paragraph"><p>Ranch is now tested and supported with Erlang/OTP R16B or above
-on Arch Linux, FreeBSD, OSX, Ubuntu and Windows 7. Contact me
-if you can provide permanent access to another platform for the
-purposes of testing.</p></div>
-<div class="paragraph"><p>Ranch is now available from four locations:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="https://git.ninenines.eu/ranch.git">https://git.ninenines.eu/ranch.git</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://github.com/ninenines/ranch.git">https://github.com/ninenines/ranch.git</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://bitbucket.org/ninenines/ranch.git">https://bitbucket.org/ninenines/ranch.git</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://gitlab.com/ninenines/ranch.git">https://gitlab.com/ninenines/ranch.git</a>
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>They are updated at the same time so there is no real difference.</p></div>
-<div class="paragraph"><p>The most recent Ranch commit is now always signed. You can import the
-<a href="https://pgp.mit.edu/pks/lookup?op=vindex&amp;fingerprint=on&amp;exact=on&amp;search=0xF19F189CECC7439699CEDD7A6EF7A77066CCCC8A">signing key for Loïc Hoguin</a> with:</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>$ gpg --keyserver hkp<span style="color: #990000">:</span>//keys<span style="color: #990000">.</span>gnupg<span style="color: #990000">.</span>net --recv-key 66CCCC8A</tt></pre></div></div>
-<div class="paragraph"><p>The primary key fingerprint is <code>F19F 189C ECC7 4396 99CE DD7A 6EF7 A770 66CC CC8A</code>.</p></div>
-<div class="paragraph"><p>When verifying signatures in git, the following should appear:</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>gpg<span style="color: #990000">:</span> Signature made Sat <span style="color: #993399">26</span> Nov <span style="color: #993399">2016</span> <span style="color: #993399">12</span><span style="color: #990000">:</span><span style="color: #993399">58</span><span style="color: #990000">:</span><span style="color: #993399">35</span> PM CET
-gpg<span style="color: #990000">:</span> using RSA key 71366FF21851DF03
-gpg<span style="color: #990000">:</span> Good signature from <span style="color: #FF0000">"Loïc Hoguin &lt;[email protected]&gt;"</span> <span style="color: #990000">[</span>unknown<span style="color: #990000">]</span>
-gpg<span style="color: #990000">:</span> WARNING<span style="color: #990000">:</span> This key is not certified with a trusted signature<span style="color: #990000">!</span>
-gpg<span style="color: #990000">:</span> There is no indication that the signature belongs to the owner<span style="color: #990000">.</span>
-Primary key fingerprint<span style="color: #990000">:</span> F19F 189C ECC7 <span style="color: #993399">4396</span> 99CE DD7A 6EF7 A770 66CC CC8A
- Subkey fingerprint<span style="color: #990000">:</span> FEDA <span style="color: #993399">6E41</span> B390 F745 A385 5CDC <span style="color: #993399">7136</span> 6FF2 <span style="color: #993399">1851</span> DF03</tt></pre></div></div>
-<div class="paragraph"><p>You can safely ignore the warning if you don&#8217;t know what it
-means, as long as everything else is correct.</p></div>
-<div class="paragraph"><p>Mirrors and signature verification will soon be implemented
-directly in Erlang.mk. In the meantime, you will need to
-set them up manually.</p></div>
-<div class="paragraph"><p>Most of this work was done to fix issues in RabbitMQ. Paid
-customers get priority; contact me if you have some issues
-that need fixing sooner rather than later.</p></div>
-<div class="paragraph"><p>Expect future releases to be announced in this space.</p></div>
-<div class="paragraph"><p>Thanks for reading!</p></div>
-</description> + <description>Ranch 1.3.0 has been released! + This release fixes a number of long standing issues and adds a small number of features: + The ssl application has been added to the list of dependencies. If you don&#8217;t need it, you can remove it automatically when fetching Ranch or when building the release. If you do need it, you will no longer have issues shutting down a node because of Ranch.</description> </item> <item> @@ -597,17 +83,10 @@ that need fixing sooner rather than later.</p></div> <pubDate>Mon, 29 Aug 2016 00:00:00 +0100</pubDate> <guid>https://ninenines.eu/articles/ml-archives/</guid> - <description><div class="paragraph"><p>The <a href="https://ninenines.eu/archives/extend">old mailing list archives</a> have been
-added to the site, mainly for referencing purposes.</p></div>
-<div class="paragraph"><p>The mailing list has been shut down and all personal information
-has been deleted.</p></div>
-<div class="paragraph"><p>If you need help with a project, consider either opening a ticket
-on that project&#8217;s issues tracker or going through the community
-channels (erlang-questions, #ninenines or #erlang on Freenode).</p></div>
-<div class="paragraph"><p>Prefer tickets; often when people have issues it highlights an
-underlying problem in the project or its documentation.</p></div>
-<div class="paragraph"><p>Thanks.</p></div>
-</description> + <description>The old mailing list archives have been added to the site, mainly for referencing purposes. + The mailing list has been shut down and all personal information has been deleted. + If you need help with a project, consider either opening a ticket on that project&#8217;s issues tracker or going through the community channels (erlang-questions, #ninenines or #erlang on Freenode). + Prefer tickets; often when people have issues it highlights an underlying problem in the project or its documentation.</description> </item> <item> @@ -616,64 +95,9 @@ underlying problem in the project or its documentation.</p></div> <pubDate>Sat, 02 Apr 2016 00:00:00 +0100</pubDate> <guid>https://ninenines.eu/articles/website-update/</guid> - <description><div class="paragraph"><p>Last week-end I updated the Nine Nines website.</p></div>
-<div class="paragraph"><p>I switched to <a href="http://gohugo.io/">Hugo</a>. The site is
-now built from <a href="http://asciidoc.org/">Asciidoc</a>
-documents. You probably saw me switch to Asciidoc
-for documentation this past year. This is the
-natural conclusion to that story. The great thing
-is that with a little bit of Makefile magic I can
-just copy the documentation files into Hugo and
-poof, they appear on the website.</p></div>
-<div class="paragraph"><p>I am very happy with that new setup. I can now
-post my thoughts again. Woo! Expect regular posts
-from now on. I will try to replace my long series
-of tweets with posts.</p></div>
-<div class="paragraph"><p>The sections have been rearranged. There used to
-be a separate training section; now
-<a href="https://ninenines.eu/services">all my services</a> are described in
-one page. I have also clarified my areas of
-expertise. There used to be confusion in the past,
-so now it should be clearer that I am not a
-distributed systems expert.</p></div>
-<div class="paragraph"><p>On that note, if you are looking for my
-services right now, I&#8217;m not available. I&#8217;ll have
-to work 7 days a week for a while. Try again in a
-couple months. More on that in a future post.</p></div>
-<div class="paragraph"><p>The <a href="https://ninenines.eu/docs">documentation</a> becomes a first class
-citizen. Bullet and Cowlib don&#8217;t have proper
-documentation&#8230; yet. I have started working on the
-Cowlib documentation, and Bullet shouldn&#8217;t take too
-long. All these projects will be documented when
-Cowboy gets to 2.0, and will all be supported
-equally. Note that the Cowboy 1.0 documentation
-still has the old website templates and links.
-Don&#8217;t worry about it.</p></div>
-<div class="paragraph"><p>The mailing lists link has been removed. I did
-announce a few months back that mailing lists were
-going to go. They&#8217;re still up right now, but not
-for long. I am planning to put the archives
-read-only, link to them from a future post and
-be done with it. If you have a question, open a
-ticket on Github. Then I can just decide to leave
-the ticket open if I want to do improvements based
-on your feedback.</p></div>
-<div class="paragraph"><p>I have replaced most of the "we" by "I". I am
-a one-man company right now. Have been for a while.
-Doesn&#8217;t make sense to keep a facade. I want to be
-close to users, not put a barrier between us.</p></div>
-<div class="paragraph"><p>The RSS changed. The old link doesn&#8217;t work anymore.
-The new link is at <a href="https://ninenines.eu/index.xml">/index.xml</a>,
-or <a href="https://ninenines.eu/articles/index.xml">/articles/index.xml</a>
-if you only care about my posts. I guess that&#8217;s the
-one most people want.</p></div>
-<div class="paragraph"><p>I still have some tweaks to do, but it will take a
-while. My long term plan is to remove Bootstrap, use
-vanilla CSS and as little JS as possible. The reason
-for that is that it&#8217;s cheaper than upgrading libraries
-every few years. Life is too short to spend it
-upgrading JS libraries.</p></div>
-</description> + <description>Last week-end I updated the Nine Nines website. + I switched to Hugo. The site is now built from Asciidoc documents. You probably saw me switch to Asciidoc for documentation this past year. This is the natural conclusion to that story. The great thing is that with a little bit of Makefile magic I can just copy the documentation files into Hugo and poof, they appear on the website. + I am very happy with that new setup.</description> </item> <item> @@ -682,20 +106,10 @@ upgrading JS libraries.</p></div> <pubDate>Wed, 02 Sep 2015 00:00:00 +0100</pubDate> <guid>https://ninenines.eu/articles/erlanger-playbook-september-2015-update/</guid> - <description><div class="paragraph"><p>An update to The Erlanger Playbook is now available!</p></div>
-<div class="paragraph"><p>The Erlanger Playbook is a book about software development using
-Erlang. It currently covers all areas from the conception, design,
-the writing of code, documentation and tests.</p></div>
-<div class="paragraph"><p>The book is still a work in progress. Future topics will include
-refactoring, debugging and tracing, benchmarking, releases, community
-management (for open source projects).</p></div>
-<div class="paragraph"><p>This update fixes a number of things and adds two chapters: IOlists
-and Erlang building blocks.</p></div>
-<div class="paragraph"><p>Learn more about <a href="https://ninenines.eu/articles/erlanger-playbook">The Erlanger Playbook</a>!</p></div>
-<div class="paragraph"><p>This is a self-published ebook. The base price is 50€. All proceeds
-will be used to allow me to work on open source full time.</p></div>
-<div class="paragraph"><p>Thank you for helping me helping you help us all!</p></div>
-</description> + <description>An update to The Erlanger Playbook is now available! + The Erlanger Playbook is a book about software development using Erlang. It currently covers all areas from the conception, design, the writing of code, documentation and tests. + The book is still a work in progress. Future topics will include refactoring, debugging and tracing, benchmarking, releases, community management (for open source projects). + This update fixes a number of things and adds two chapters: IOlists and Erlang building blocks.</description> </item> <item> @@ -704,88 +118,10 @@ will be used to allow me to work on open source full time.</p></div> <pubDate>Thu, 18 Jun 2015 00:00:00 +0100</pubDate> <guid>https://ninenines.eu/articles/erlanger-playbook/</guid> - <description><div class="paragraph"><p>I am proud to announce the pre-release of The Erlanger Playbook.</p></div>
-<div class="paragraph"><p>The Erlanger Playbook is a book about software development using
-Erlang. It currently covers all areas from the conception, design,
-the writing of code, documentation and tests.</p></div>
-<div class="paragraph"><p>The book is still a work in progress. Future topics will include
-refactoring, debugging and tracing, benchmarking, releases, community
-management (for open source projects).</p></div>
-<div class="paragraph"><p>The following sections are currently available:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-About this book; Changelog; Future additions
-</p>
-</li>
-<li>
-<p>
-<em>Erlang:</em> Building blocks; Patterns
-</p>
-</li>
-<li>
-<p>
-<em>Workflow:</em> Think; Write; Stay productive
-</p>
-</li>
-<li>
-<p>
-<em>Documentation:</em> On documentation; Tutorials; User guide; Manual; README files
-</p>
-</li>
-<li>
-<p>
-<em>Design:</em> RESTful APIs; Lessons learned
-</p>
-</li>
-<li>
-<p>
-<em>Code:</em> Starting a project; Version control; Project structure; Code style; Best practices; Special processes; IOLists; The process dictionary
-</p>
-</li>
-<li>
-<p>
-<em>Tests:</em> On testing; Success typing analysis; Manual testing; Unit testing; Functional testing
-</p>
-</li>
-<li>
-<p>
-<em>Selling Erlang:</em> On persuasion; Don&#8217;t let it crash
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Read a preview: <a href="https://ninenines.eu/res/erlanger-preview.pdf">Special processes</a></p></div>
-<div class="paragraph"><p>The book is currently 180 pages long. The final version
-of the book is planned to be between 200 and 250 pages.
-A print version of the book will be considered once the final
-version gets released. The printed book is <strong>not</strong> included
-in the price.</p></div>
-<div class="paragraph"><p>This is a self-published book. The base price is 50€. All proceeds
-will be used to allow me to work on open source full time.</p></div>
-<form action="https://www.paypal.com/cgi-bin/webscr" method="post" target="_top">
-<input type="hidden" name="cmd" value="_s-xclick">
-<input type="hidden" name="hosted_button_id" value="9M44HJCGX3GVN">
-<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_buynowCC_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
-<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1">
-</form>
-<div class="paragraph"><p>You are more than welcome to pay extra by using this second button.
-It allows you to set the price you want. Make sure to set it to at least
-50€ to receive the book.</p></div>
-<form action="https://www.paypal.com/cgi-bin/webscr" method="post" target="_top">
-<input type="hidden" name="cmd" value="_s-xclick">
-<input type="hidden" name="hosted_button_id" value="BBW9TR9LBK8C2">
-<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_buynowCC_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
-<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1">
-</form>
-<div class="paragraph"><p>Make sure to provide a valid email address.</p></div>
-<div class="paragraph"><p>There will be a <strong>delay</strong> between payment and sending of the book.
-This process is currently manual.</p></div>
-<div class="paragraph"><p>As the book is a pre-release, feedback is more than welcome. You can
-send your comments to erlanger@ this website.</p></div>
-<div class="paragraph"><p>The plan is to add content regularly until I run out of things to say.
-You will receive updates to the book for free as soon as they are available.</p></div>
-<div class="paragraph"><p>Huge thanks for your interest in buying this book!</p></div>
-</description> + <description>I am proud to announce the pre-release of The Erlanger Playbook. + The Erlanger Playbook is a book about software development using Erlang. It currently covers all areas from the conception, design, the writing of code, documentation and tests. + The book is still a work in progress. Future topics will include refactoring, debugging and tracing, benchmarking, releases, community management (for open source projects). + The following sections are currently available:</description> </item> <item> @@ -794,192 +130,9 @@ You will receive updates to the book for free as soon as they are available.< <pubDate>Fri, 06 Mar 2015 00:00:00 +0100</pubDate> <guid>https://ninenines.eu/articles/erlang-validate-utf8/</guid> - <description><div class="paragraph"><p>Yesterday I pushed Websocket permessage-deflate to
-Cowboy master. I also pushed
-<a href="https://github.com/ninenines/cowlib/commit/7e4983b70ddf8cedb967e36fba6a600731bdad5d">a
-change in the way the code validates UTF-8 data</a>
-(required for text and close frames as per the spec).</p></div>
-<div class="paragraph"><p>When looking into why the permessage-deflate tests
-in autobahntestsuite were taking such a long time, I
-found that autobahn is using an adaptation of the
-algorithm named <a href="http://bjoern.hoehrmann.de/utf-8/decoder/dfa/">Flexible
-and Economical UTF-8 Decoder</a>. This is the C99
-implementation:</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-style: italic"><span style="color: #9A1900">// Copyright (c) 2008-2009 Bjoern Hoehrmann &lt;[email protected]&gt;</span></span>
-<span style="font-style: italic"><span style="color: #9A1900">// See http://bjoern.hoehrmann.de/utf-8/decoder/dfa/ for details.</span></span>
-
-<span style="font-weight: bold"><span style="color: #000080">#define</span></span> UTF8_ACCEPT <span style="color: #993399">0</span>
-<span style="font-weight: bold"><span style="color: #000080">#define</span></span> UTF8_REJECT <span style="color: #993399">1</span>
-
-<span style="font-weight: bold"><span style="color: #0000FF">static</span></span> <span style="font-weight: bold"><span style="color: #0000FF">const</span></span> <span style="color: #008080">uint8_t</span> utf8d<span style="color: #990000">[]</span> <span style="color: #990000">=</span> <span style="color: #FF0000">{</span>
- <span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// 00..1f</span></span>
- <span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// 20..3f</span></span>
- <span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// 40..5f</span></span>
- <span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// 60..7f</span></span>
- <span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span><span style="color: #993399">9</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// 80..9f</span></span>
- <span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span><span style="color: #993399">7</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// a0..bf</span></span>
- <span style="color: #993399">8</span><span style="color: #990000">,</span><span style="color: #993399">8</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// c0..df</span></span>
- <span style="color: #993399">0xa</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x4</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// e0..ef</span></span>
- <span style="color: #993399">0xb</span><span style="color: #990000">,</span><span style="color: #993399">0x6</span><span style="color: #990000">,</span><span style="color: #993399">0x6</span><span style="color: #990000">,</span><span style="color: #993399">0x6</span><span style="color: #990000">,</span><span style="color: #993399">0x5</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// f0..ff</span></span>
- <span style="color: #993399">0x0</span><span style="color: #990000">,</span><span style="color: #993399">0x1</span><span style="color: #990000">,</span><span style="color: #993399">0x2</span><span style="color: #990000">,</span><span style="color: #993399">0x3</span><span style="color: #990000">,</span><span style="color: #993399">0x5</span><span style="color: #990000">,</span><span style="color: #993399">0x8</span><span style="color: #990000">,</span><span style="color: #993399">0x7</span><span style="color: #990000">,</span><span style="color: #993399">0x1</span><span style="color: #990000">,</span><span style="color: #993399">0x1</span><span style="color: #990000">,</span><span style="color: #993399">0x1</span><span style="color: #990000">,</span><span style="color: #993399">0x4</span><span style="color: #990000">,</span><span style="color: #993399">0x6</span><span style="color: #990000">,</span><span style="color: #993399">0x1</span><span style="color: #990000">,</span><span style="color: #993399">0x1</span><span style="color: #990000">,</span><span style="color: #993399">0x1</span><span style="color: #990000">,</span><span style="color: #993399">0x1</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// s0..s0</span></span>
- <span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// s1..s2</span></span>
- <span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// s3..s4</span></span>
- <span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">3</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">3</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// s5..s6</span></span>
- <span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">3</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">3</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">3</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">3</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">1</span><span style="color: #990000">,</span> <span style="font-style: italic"><span style="color: #9A1900">// s7..s8</span></span>
-<span style="color: #FF0000">}</span><span style="color: #990000">;</span>
-
-uint32_t inline
-<span style="font-weight: bold"><span style="color: #000000">decode</span></span><span style="color: #990000">(</span>uint32_t<span style="color: #990000">*</span> state<span style="color: #990000">,</span> uint32_t<span style="color: #990000">*</span> codep<span style="color: #990000">,</span> <span style="color: #008080">uint32_t</span> byte<span style="color: #990000">)</span> <span style="color: #FF0000">{</span>
- <span style="color: #008080">uint32_t</span> type <span style="color: #990000">=</span> utf8d<span style="color: #990000">[</span>byte<span style="color: #990000">];</span>
-
- <span style="color: #990000">*</span>codep <span style="color: #990000">=</span> <span style="color: #990000">(*</span>state <span style="color: #990000">!=</span> UTF8_ACCEPT<span style="color: #990000">)</span> <span style="color: #990000">?</span>
- <span style="color: #990000">(</span>byte <span style="color: #990000">&amp;</span> <span style="color: #993399">0x3fu</span><span style="color: #990000">)</span> <span style="color: #990000">|</span> <span style="color: #990000">(*</span>codep <span style="color: #990000">&lt;&lt;</span> <span style="color: #993399">6</span><span style="color: #990000">)</span> <span style="color: #990000">:</span>
- <span style="color: #990000">(</span><span style="color: #993399">0xff</span> <span style="color: #990000">&gt;&gt;</span> type<span style="color: #990000">)</span> <span style="color: #990000">&amp;</span> <span style="color: #990000">(</span>byte<span style="color: #990000">);</span>
-
- <span style="color: #990000">*</span>state <span style="color: #990000">=</span> utf8d<span style="color: #990000">[</span><span style="color: #993399">256</span> <span style="color: #990000">+</span> <span style="color: #990000">*</span>state<span style="color: #990000">*</span><span style="color: #993399">16</span> <span style="color: #990000">+</span> type<span style="color: #990000">];</span>
- <span style="font-weight: bold"><span style="color: #0000FF">return</span></span> <span style="color: #990000">*</span>state<span style="color: #990000">;</span>
-<span style="color: #FF0000">}</span></tt></pre></div></div>
-<div class="paragraph"><p>And this is the Erlang implementation I came up with:</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-style: italic"><span style="color: #9A1900">%% This function returns 0 on success, 1 on error, and 2..8 on incomplete data.</span></span>
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;&gt;&gt;</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-&gt;</span> <span style="color: #009900">State</span>;
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">0</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">&lt;</span> <span style="color: #993399">128</span> <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">2</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">&gt;=</span> <span style="color: #993399">128</span>, <span style="color: #009900">C</span> <span style="color: #990000">&lt;</span> <span style="color: #993399">144</span> <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">3</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">&gt;=</span> <span style="color: #993399">128</span>, <span style="color: #009900">C</span> <span style="color: #990000">&lt;</span> <span style="color: #993399">144</span> <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">5</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">&gt;=</span> <span style="color: #993399">128</span>, <span style="color: #009900">C</span> <span style="color: #990000">&lt;</span> <span style="color: #993399">144</span> <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">7</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">&gt;=</span> <span style="color: #993399">128</span>, <span style="color: #009900">C</span> <span style="color: #990000">&lt;</span> <span style="color: #993399">144</span> <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">8</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">&gt;=</span> <span style="color: #993399">128</span>, <span style="color: #009900">C</span> <span style="color: #990000">&lt;</span> <span style="color: #993399">144</span> <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">2</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">&gt;=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000">&lt;</span> <span style="color: #993399">160</span> <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">3</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">&gt;=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000">&lt;</span> <span style="color: #993399">160</span> <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">5</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">&gt;=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000">&lt;</span> <span style="color: #993399">160</span> <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">6</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">&gt;=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000">&lt;</span> <span style="color: #993399">160</span> <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">7</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">&gt;=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000">&lt;</span> <span style="color: #993399">160</span> <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">2</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">&gt;=</span> <span style="color: #993399">160</span>, <span style="color: #009900">C</span> <span style="color: #990000">&lt;</span> <span style="color: #993399">192</span> <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">3</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">&gt;=</span> <span style="color: #993399">160</span>, <span style="color: #009900">C</span> <span style="color: #990000">&lt;</span> <span style="color: #993399">192</span> <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">4</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">&gt;=</span> <span style="color: #993399">160</span>, <span style="color: #009900">C</span> <span style="color: #990000">&lt;</span> <span style="color: #993399">192</span> <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">6</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">&gt;=</span> <span style="color: #993399">160</span>, <span style="color: #009900">C</span> <span style="color: #990000">&lt;</span> <span style="color: #993399">192</span> <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">7</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">&gt;=</span> <span style="color: #993399">160</span>, <span style="color: #009900">C</span> <span style="color: #990000">&lt;</span> <span style="color: #993399">192</span> <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">0</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">&gt;=</span> <span style="color: #993399">194</span>, <span style="color: #009900">C</span> <span style="color: #990000">&lt;</span> <span style="color: #993399">224</span> <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #993399">224</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">0</span>) <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">4</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">0</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">&gt;=</span> <span style="color: #993399">225</span>, <span style="color: #009900">C</span> <span style="color: #990000">&lt;</span> <span style="color: #993399">237</span> <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #993399">237</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">0</span>) <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">5</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">0</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">=:=</span> <span style="color: #993399">238</span>; <span style="color: #009900">C</span> <span style="color: #990000">=:=</span> <span style="color: #993399">239</span> <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #993399">240</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">0</span>) <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">6</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">0</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">=:=</span> <span style="color: #993399">241</span>; <span style="color: #009900">C</span> <span style="color: #990000">=:=</span> <span style="color: #993399">242</span>; <span style="color: #009900">C</span> <span style="color: #990000">=:=</span> <span style="color: #993399">243</span> <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">7</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #993399">244</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">0</span>) <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">8</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">_</span>, <span style="color: #990000">_</span>) <span style="color: #990000">-&gt;</span> <span style="color: #993399">1</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Does it look similar to you? So how did we get there?</p></div>
-<div class="paragraph"><p>I started with a naive implementation of the original. First, we
-don&#8217;t need the codepoint calculated and extracted for our validation
-function. We just want to know the data is valid, so we only need to
-calculate the next state. Then, the only thing we needed to be careful
-about was that tuples are 1-based, and that we need to stop processing
-the binary when we get the state 1 or when the binary is empty.</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">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;&gt;&gt;</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-&gt;</span> <span style="color: #009900">State</span>;
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">_</span>, <span style="color: #993399">1</span>) <span style="color: #990000">-&gt;</span> <span style="color: #993399">1</span>;
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-&gt;</span>
- <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="font-weight: bold"><span style="color: #000080">element</span></span>(<span style="color: #993399">257</span> <span style="color: #990000">+</span> <span style="color: #009900">State</span> <span style="color: #990000">*</span> <span style="color: #993399">16</span> <span style="color: #990000">+</span> <span style="font-weight: bold"><span style="color: #000080">element</span></span>(<span style="color: #993399">1</span> <span style="color: #990000">+</span> <span style="color: #009900">C</span>, <span style="font-weight: bold"><span style="color: #000080">?UTF8D</span></span>), <span style="font-weight: bold"><span style="color: #000080">?UTF8D</span></span>))<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The macro <code>?UTF8D</code> is the tuple equivalent of the C array
-in the original code.</p></div>
-<div class="paragraph"><p>Compared to our previous algorithm, this performed about the same.
-In some situations a little faster, in some a little slower. In other words,
-not good enough. But because this new algorithm allows us to avoid a binary
-concatenation this warranted looking further.</p></div>
-<div class="paragraph"><p>It was time to step into crazy land.</p></div>
-<div class="paragraph"><p>Erlang is very good at pattern matching, even more so than doing some
-arithmetic coupled by fetching elements from a tuple. So I decided I was
-going to write all possible clauses for all combinations of <code>C</code>
-and <code>State</code>. And by write I mean generate.</p></div>
-<div class="paragraph"><p>So I opened my Erlang shell, defined the variable <code>D</code> to be
-the tuple <code>?UTF8D</code> with its 400 elements, and then ran the
-following expression (after a bit of trial and error):</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: #993399">16</span><span style="color: #990000">&gt;</span> <span style="font-weight: bold"><span style="color: #000000">file:write_file</span></span>(<span style="color: #FF0000">"out.txt"</span>,
- [<span style="font-weight: bold"><span style="color: #000000">io_lib:format</span></span>(<span style="color: #FF0000">"validate_utf8(&lt;&lt; ~p, Rest/bits &gt;&gt;, ~p) -&gt; ~p;~n"</span>,
- [<span style="color: #009900">C</span>, <span style="color: #009900">S</span>, <span style="font-weight: bold"><span style="color: #000080">element</span></span>(<span style="color: #993399">257</span> <span style="color: #990000">+</span> <span style="color: #009900">S</span> <span style="color: #990000">*</span> <span style="color: #993399">16</span> <span style="color: #990000">+</span> <span style="font-weight: bold"><span style="color: #000080">element</span></span>(<span style="color: #993399">1</span> <span style="color: #990000">+</span> <span style="color: #009900">C</span>, <span style="color: #009900">D</span>), <span style="color: #009900">D</span>)])
- || <span style="color: #009900">C</span> <span style="color: #990000">&lt;-</span> <span style="font-weight: bold"><span style="color: #000000">lists:seq</span></span>(<span style="color: #993399">0</span>,<span style="color: #993399">255</span>), <span style="color: #009900">S</span> <span style="color: #990000">&lt;-</span> <span style="font-weight: bold"><span style="color: #000000">lists:seq</span></span>(<span style="color: #993399">0</span>,<span style="color: #993399">8</span>)])<span style="color: #990000">.</span>
-<span style="color: #FF6600">ok</span></tt></pre></div></div>
-<div class="paragraph"><p>The result is a 2304 lines long file, containing 2304 clauses.
-People who pay attention to what I say on Twitter will remember
-I said something around 3000 clauses, but that was just me not
-using the right number of states in my estimate.</p></div>
-<div class="paragraph"><p>There was a little more work to be done on this generated
-code that I did using regular expressions. We need to recurse
-when the resulting state is not 1. We also need to stop when
-the binary is empty, making it the 2305th clause.</p></div>
-<div class="paragraph"><p>Still, 2305 is a lot. But hey, the code did work, and faster
-than the previous implementation too! But hey, perhaps I could
-find a way to reduce its size.</p></div>
-<div class="paragraph"><p>Removing all the clauses that return 1 and putting a catch-all
-clause at the end instead reduced the number to about 500, and
-showed that many clauses were similar:</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">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #993399">0</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">0</span>) <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #993399">1</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">0</span>) <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #993399">2</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">0</span>) <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #993399">3</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">0</span>) <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #993399">4</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">0</span>) <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #993399">5</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">0</span>) <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #993399">6</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">0</span>) <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #993399">7</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">0</span>) <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);</tt></pre></div></div>
-<div class="paragraph"><p>But 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="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #993399">157</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">2</span>) <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #993399">157</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">3</span>) <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #993399">157</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">5</span>) <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #993399">157</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">6</span>) <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #993399">157</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">7</span>) <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #993399">158</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">2</span>) <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #993399">158</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">3</span>) <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #993399">158</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">5</span>) <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #993399">158</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">6</span>) <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #993399">158</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">7</span>) <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>);</tt></pre></div></div>
-<div class="paragraph"><p>Patterns, my favorites!</p></div>
-<div class="paragraph"><p>A little more time was spent to edit the 500 or so clauses into
-smaller equivalents, testing that performance was not impacted, and
-comitting the result.</p></div>
-<div class="paragraph"><p>The patterns above can be found here in the resulting 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">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">0</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">&lt;</span> <span style="color: #993399">128</span> <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="color: #990000">...</span>
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">2</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">&gt;=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000">&lt;</span> <span style="color: #993399">160</span> <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">0</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">3</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">&gt;=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000">&lt;</span> <span style="color: #993399">160</span> <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">5</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">&gt;=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000">&lt;</span> <span style="color: #993399">160</span> <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">2</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">6</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">&gt;=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000">&lt;</span> <span style="color: #993399">160</span> <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>);
-<span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #990000">&lt;&lt;</span> <span style="color: #009900">C</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">7</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">C</span> <span style="color: #990000">&gt;=</span> <span style="color: #993399">144</span>, <span style="color: #009900">C</span> <span style="color: #990000">&lt;</span> <span style="color: #993399">160</span> <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">validate_utf8</span></span>(<span style="color: #009900">Rest</span>, <span style="color: #993399">3</span>);
-<span style="color: #990000">...</span></tt></pre></div></div>
-<div class="paragraph"><p>I hope you enjoyed this post.</p></div>
-</description> + <description>Yesterday I pushed Websocket permessage-deflate to Cowboy master. I also pushed a change in the way the code validates UTF-8 data (required for text and close frames as per the spec). + When looking into why the permessage-deflate tests in autobahntestsuite were taking such a long time, I found that autobahn is using an adaptation of the algorithm named Flexible and Economical UTF-8 Decoder. This is the C99 implementation: + // Copyright (c) 2008-2009 Bjoern Hoehrmann &lt;bjoern@hoehrmann.</description> </item> <item> @@ -988,124 +141,7 @@ http://www.gnu.org/software/src-highlite --> <pubDate>Fri, 05 Sep 2014 00:00:00 +0100</pubDate> <guid>https://ninenines.eu/articles/on-open-source/</guid> - <description><div class="paragraph"><p>Last week I read a great article
-<a href="http://videlalvaro.github.io/2014/08/on-contributing-to-opensource.html">on
-contributing to open source</a> by Alvaro Videla. He makes
-many great points and I am in agreement with most of it.
-This made me want to properly explain my point of view with
-regard to open source and contributions. Unlike most open
-source evangelism articles I will not talk about ideals or
-any of that crap, but rather my personal feelings and
-experience.</p></div>
-<div class="paragraph"><p>I have been doing open source work for quite some time.
-My very first open source project was a graphics driver
-for (the very early version of) the PCSX2 emulator. That
-was more than ten years ago, and there
-<a href="http://ngemu.com/threads/gstaris-0-6.30469/">isn&#8217;t
-much left to look at today</a>. This was followed by a
-<a href="https://github.com/extend/wee">PHP framework</a>
-(started long before Zend Framework was even a thing) and
-a few other small projects. None of them really took off.
-It&#8217;s alright, that&#8217;s pretty much the fate of most open
-source projects. You spend a lot of work and sweat and
-get very little in return from others.</p></div>
-<div class="paragraph"><p>This sounds harsh but this is the reality of all open
-source projects. If you are thinking of building a project
-and releasing it as open source, you should be prepared
-for that. This is how most of your projects will feel like.
-Don&#8217;t release a project as open source thinking everyone
-will pat you on the back and cheer, this won&#8217;t happen. In
-fact if your project is a too small improvement over existing
-software, what many people will do is say you have NIH
-syndrome, regardless of the improvement you bring. So you
-need not to rely on other people in order to get your
-enjoyment out of building open source software.</p></div>
-<div class="paragraph"><p>In my case I get enjoyment from thinking about problems
-that need solving. Often times the problems are already
-solved, but nevermind that, I still think about them and
-sometimes come up with something I feel is better and then
-write code for it. Writing code is also fun, but not as
-fun as using my brain to imagine solutions.</p></div>
-<div class="paragraph"><p>You don&#8217;t need thousands of users to do that. So are
-users worthless to me then? No, of course not. In fact
-they are an important component: they bring me problems
-that need solving. So users are very important to me.
-But that&#8217;s not the only reason.</p></div>
-<div class="paragraph"><p>I got lucky that the Cowboy project became popular.
-And seeing it be this popular, and some of my other projects
-also do quite well, made me believe I could perhaps work
-full time on open source. If I can work full time then
-I can produce better software. What I had one hour to
-work on before I can now spend a day on, and experiment
-until I am satisfied. This is very useful because that
-means I can get it almost right from the beginning, and
-avoid the million API breaking changes that occured
-before Cowboy 1.0 was released.</p></div>
-<div class="paragraph"><p>To be able to work full time on open source however,
-I need money. This is a largely unspoken topic of open
-source work. The work is never free. You can download the
-product for free, but someone has to pay for the work
-itself. Life is unfortunately not free.</p></div>
-<div class="paragraph"><p>Large projects and some lucky people have their work
-sponsored by their employers. Everyone else has to deal
-with it differently. In my case I was sponsored for a
-while by the <a href="http://leo-project.net/leofs/">LeoFS</a>
-project, but that ended. I also had the Farwest fundraiser,
-which was a success, although the project stalled after that.
-(Fear not, as Farwest will make a comeback as a conglomerate
-of Web development projects in the future.) After that I set
-up the <a href="http://ninenines.eu/support/">sponsoring scheme</a>,
-which I can proudly say today brings in enough money to
-cover my food and shelter. Great!</p></div>
-<div class="paragraph"><p>This is a start, but it&#8217;s of course not enough. Life
-is a little more than food and shelter, and so I am still
-looking for sponsors. This is not a very glorious experience,
-as I am essentially looking for scraps that companies can
-throw away. Still, if a handful more companies were doing
-that, not only would I be able to live comfortably, but I
-would also be able to stop worrying about the future as I
-could put money on the side for when it gets rough.</p></div>
-<div class="paragraph"><p>A few companies giving me some scrap money so I could
-live and work independently is by far the most important
-thing anyone can do to help my projects, including Cowboy.
-Yes, they&#8217;re even more important than code contributions,
-bug reports and feedback. Because this money gives me the
-time I need to handle the code contributions, bug reports
-and feedback.</p></div>
-<div class="paragraph"><p>If Cowboy or another project is a large part of your
-product or infrastructure, then the best thing you can do
-is become a sponsor. The second best is opening tickets
-and/or providing feedback. The third best is providing
-good code contributions.</p></div>
-<div class="paragraph"><p>I will not expand on the feedback part. Feedback is
-very important, and even just a high five or a retweet
-is already good feedback. It&#8217;s not very complicated.</p></div>
-<div class="paragraph"><p>I want to expand a little on code contributions
-however. Not long ago I ran across the term "patch bomb"
-which means dropping patches and expecting the project
-maintainers to merge them and maintain them. I receive
-a lot of patches, and often have to refuse them. Causes
-for refusal vary. Some patches only benefit the people
-who submitted them (or a very small number of people).
-Some patches are not refined enough to be included.
-Others are out of scope of the project. These are some
-of the reasons why I refuse patches. Having limited
-time and resources, I have to focus my efforts on the
-code used by the larger number of users. I have to
-prioritize patches from submitters who are reactive
-and address the issues pointed out. And I have to plainly
-refuse other patches.</p></div>
-<div class="paragraph"><p>I believe this wraps up my thoughts on open source.
-Overall I had a great experience, the Erlang community
-being nice and understanding of the issues at hand in
-general. And if the money problem could be solved soon,
-then I would be one of the luckiest and happiest open
-source developer on Earth.</p></div>
-<div class="paragraph"><p>Think about it the next time you see a donation button
-or a request for funds or sponsoring. You can considerably
-improve an open source developer&#8217;s life with very little
-of your company&#8217;s money.</p></div>
-</description> + <description>Last week I read a great article on contributing to open source by Alvaro Videla. He makes many great points and I am in agreement with most of it. This made me want to properly explain my point of view with regard to open source and contributions. Unlike most open source evangelism articles I will not talk about ideals or any of that crap, but rather my personal feelings and experience.</description> </item> <item> @@ -1114,231 +150,7 @@ of your company&#8217;s money.</p></div> <pubDate>Sat, 23 Aug 2014 00:00:00 +0100</pubDate> <guid>https://ninenines.eu/articles/the-story-so-far/</guid> - <description><div class="paragraph"><p>As I am away from home with little to do (some call this
-a vacation) I wanted to reflect a little on the story so far,
-or how I arrived to Erlang and got to where I am now. The
-raw personal experience. It&#8217;ll be an article that&#8217;s more
-about social aspect, communities and marketing a project than
-technical considerations. As a period piece, it will also
-allow me to reflect on the evolution of Erlang in recent
-years.</p></div>
-<div class="paragraph"><p>Once upon a time-- Okay this isn&#8217;t a fairy tale. The story
-begins with a short chapter in 2010. The year 2010 started
-with a fairly major event in my life: the US servers for the
-online game I stopped playing a few months before, but was
-still involved with through its community, were closing. OMG!
-Someone found a way to log packets and started working on a
-private server; meanwhile the JP servers were still up. And
-that&#8217;s pretty much it.</p></div>
-<div class="paragraph"><p>Fast forward a few months and it became pretty clear that
-the private server was going nowhere considering all the drama
-surrounding it-- which is actually not unusual, but it was
-more entertaining than average and the technical abilities of
-people running the project were obviously lacking so I decided
-to obtain those logged packets and look at things myself. I
-didn&#8217;t want to do a private server yet, I only wanted to take
-a peek to see how things worked, and perhaps organize some
-effort to document the protocol.</p></div>
-<div class="paragraph"><p>There was 10GB of logs. I didn&#8217;t have an easy to use
-language to analyze them, and hex editors wouldn&#8217;t cut it for
-most purposes, so I had to look elsewhere. This was a good
-opportunity to start learning this PHP killer I read about
-before, which also happens to feature syntax for matching
-binaries, called Erlang. To be perfectly honest I wouldn&#8217;t
-have touched the logs if I didn&#8217;t have the added motivation
-to play with and learn a new language.</p></div>
-<div class="paragraph"><p>At the time it was pretty hard to learn Erlang. In my
-experience there was Joe&#8217;s book (which I always recommend
-first as I believe it is the best to learn the Erlang side
-of things; but falls a little short on OTP), and there was
-about 5 chapters of LYSE. There were a couple other books
-I never managed to get into (sorry guys), and there was also
-a few interesting blogs, some of which I can&#8217;t find anymore.
-Finally the #erlang IRC community was there but I was strictly
-lurking at the time.</p></div>
-<div class="paragraph"><p>What a difference compared to 4 years later! (That&#8217;s
-today, by the way!) Now we have more books than I can
-remember, tons of articles covering various aspects of the
-language and platform, many targeting beginners but a good
-number of them also about advanced topics. We even have a
-free online book, LYSE, with more than 30 chapters covering
-pretty much everything. Needless to say I never finished
-reading LYSE as it got written slower than I learnt.</p></div>
-<div class="paragraph"><p>Back to 2010. I wrote a parser for the logs, and
-aggregated those results into one CSV file per packet type
-so I could open them in Gnumeric and aggregate some more,
-but manually this time, and draw conclusions on the packet
-structures. That was pretty easy. Even for a beginner.
-Anyone can go from zero to that level in a day or two.
-Then, having mastered binary pattern matching, I wanted
-to learn some more Erlang, by making this aggregation
-faster. What I had done before worked, but I wasn&#8217;t going
-to wait forever to process everything sequentially. So I
-looked and found a project called <code>plists</code> (still exists,
-but not maintained AFAIK). I downloaded that project and
-replaced my <code>lists:</code> calls to <code>plists:</code>.
-Boom. In just a few minutes all logs were processed, and
-I had learnt something new.</p></div>
-<div class="paragraph"><p>It is particularly interesting to note that the lack of
-a package manager or index never bothered me. Neither before
-nor after learning Erlang. My experience with package
-managers was mostly related to Ubuntu, a little Perl and
-Python, and PHP&#8217;s Pear. Let&#8217;s just stay polite and say it
-was always a terrible experience. So searching on the Web
-didn&#8217;t feel awkward, because even if I used a tool or
-website I would have ended up doing a search or two anyway.
-This is in contrast to the package index feature in
-<a href="https://github.com/ninenines/erlang.mk">Erlang.mk</a>,
-which is meant to simplify specifying dependencies more
-than anything: <code>DEPS = cowboy</code>. It does not
-attempt to solve any other problem, and will only attempt
-to solve one extra problem in the near future, which is
-the discovery of packages. So expect some kind of website
-listing packages soon enough.</p></div>
-<div class="paragraph"><p>I want to use this parenthese to also point out that at
-the time there was a very small number of projects out there,
-at least compared to today. While you sometimes hear people
-complain about lack of certain libraries, it is so much
-better now than it was before! The situation improves very
-quickly, so much that it&#8217;s not going to be that big an issue
-soon enough.</p></div>
-<div class="paragraph"><p>Wanting to know more about that game&#8217;s protocol, in the
-year 2010, I ended up starting to write more Erlang code to
-simulate a server and use the server to query the client and
-see what was happening, documenting the packets and so on.
-This eventually lead to a larger project implementing more
-and more until people got their hopes up for a revival of
-the game, all the while the now competing original server
-project died in a stream of drama and technical incompetence.
-Of course, I ended up doing what any good Internet citizen
-would do, I crushed people&#8217;s hopes, but that&#8217;s not important
-to our story. The important part is that before giving up
-on this project, I not only learnt a good deal of Erlang
-and a little deal of OTP (which I did not touch until 6
-months after I started with Erlang; see the paragraph
-about learning material above), but I also had an intriguing
-idea pop into my mind for what would become my greatest
-success yet.</p></div>
-<div class="paragraph"><p>The giving up part was not easy. Having had financial
-difficulties all year 2010 and part of 2009, I resolved
-to travel back to Paris to try and make it. I ended up
-sleeping in offices for 6 months, being hosted by a shady
-person, and hearing my fair share of stories about
-the dark side of business. While there I also worked for
-another company with someone who would end up becoming
-another high profile Erlang developer. The situation
-slowly improved, I started taking part in the #erlang
-IRC discussions, giving up my status of lurker and, a
-few months into 2011, started working on the Apache killer
-project: Cowboy.</p></div>
-<div class="paragraph"><p>This is the part where I probably should get accused of
-racism and other fun things, but I never did. And I think
-that speaks lots about the Erlang community. In all my time
-writing Erlang code, I can count the number of conflicts I
-had with other people on a single hand. This is the nicest
-programming community I have ever seen, by far. And the
-humblest too. The Erlang community feels like Japan. And
-I love Japan. So I love the Erlang community. I can&#8217;t say
-this enough. This is something that stayed true for all
-my time using Erlang, and despite the rise of alternative
-languages that are not Japan the Erlang community has
-remained very Japan.</p></div>
-<div class="paragraph"><p>The first published version of Cowboy was written in
-two weeks. A little before those two weeks, during, and
-a while after, pretty much everything I said on the
-Internets was that Cowboy was going to be the greatest
-HTTP server ever, that the other servers were problematic
-(and just to be clear, Yaws was rarely if ever mentioned,
-due to being in a perceived different league of "full
-featured servers" while Cowboy was a "lightweight server"),
-and that Cowboy will be the best replacement to a Mochiweb
-or Misultin application. This, alongside a lot of time
-spent on IRC telling people to use Cowboy when they were
-asking for an HTTP server to use, probably made me sound
-very annoying. But it worked, and Cowboy started getting
-its first users, despite being only a few weeks old. Of
-course, as soon as I got my very first user, I started
-claiming Cowboy had "a lot of users".</p></div>
-<div class="paragraph"><p>Looking back today I would definitely find myself annoying,
-this wasn&#8217;t just an idle comment there. For about a year,
-maybe a little more, all I ever said was that Cowboy was
-the best. This probably made me a little dumber in the
-process (as if I wasn&#8217;t enough! I know). Being French, I
-sometimes would also say things quite abruptly. To stay
-polite, I probably sounded like an asshole. I learnt to
-stop being so French over time thankfully.</p></div>
-<div class="paragraph"><p>I think what was most important to Cowboy at the time,
-was three things. First, it felt fresh. It was new, had new
-ideas, tried to do things differently and followed "new" old
-best practices (the OTP way-- which was simply too obscure
-for most people at the time). Second, it had me spending
-all my time telling people to use it whenever they were
-looking for an HTTP server. Third, it had me helping people
-get started with it and guide them all the steps of the way.
-Mostly because it didn&#8217;t have a very good documentation, but
-still, hand holding does wonders.</p></div>
-<div class="paragraph"><p>To be able to help people every time they had a problem,
-I did not spend all my days reading IRC. Instead I simply
-made sure to be notified when someone said <code>cowboy</code>.
-The same way many people subscribe to alerts when their
-company is mentioned in the news. Nothing fancy.</p></div>
-<div class="paragraph"><p>Time went on, Cowboy grew, or as some like to say,
-completely destroyed the competition, and many people
-eventually moved from Mochiweb and Misultin to Cowboy.
-And then Roberto Ostinelli stopped Misultin development
-and told everyone to move to Cowboy. This is the most
-humble and selfless act I have ever seen in the programming
-sphere, and I only have one thing to say about it: GG.
-Thanks for the fish. He left me with the tasks of improving
-Cowboy examples, documentation and strongly believed that
-the Misultin interface was more user friendly out of all
-the servers. So I added many examples, as many lines of
-documentation as we have of code, and strongly believe
-that Cowboy 2.0 will be the most user friendly interface
-out of all servers. But only time will tell.</p></div>
-<div class="paragraph"><p>With the rise of the project and the rise in the number
-of users, my previous strategy (completely incidental, by
-the way, and definitely not a well thought out plan to
-become popular) stopped working. It was taking me too much
-time. The important aspects slowly drifted. If I wanted to
-support more users, I would have to spend less time with
-each individual user. This was actually a hard problem.
-You basically have to make people understand they can&#8217;t
-just come to you directly when they have a problem, they
-have to follow proper channels. It becomes less personal,
-and might be felt like you don&#8217;t care about them anymore.
-You have to hurt some people&#8217;s feelings at this point. It
-is quite unfortunate, and also quite difficult to do. There
-is some unwritten rule that says early adopters deserve
-more, but in the real world it never works like this. So
-I probably hurt some people&#8217;s feelings at some point. But
-that&#8217;s okay. Because even if you make sure to be as nice
-as possible when you tell people to go through proper
-channels from now on, some people will still get offended.
-There&#8217;s nothing you can do about it.</p></div>
-<div class="paragraph"><p>From that point onward the important points about the
-project was getting the documentation done, making sure
-people knew about the proper channels to get help and
-report issues, etc. Basically making myself less needed.
-This is quite a contrast with the first days, but I believe
-Cowboy made that transition successfully.</p></div>
-<div class="paragraph"><p>Not only did I win time by not having to hold hands with
-everyone all the time (not that I didn&#8217;t like it, but you
-know, the sweat), but I also won time thanks to the increased
-project popularity. Indeed, the more users you have, the more
-annoying guys there are to tell people to use your project
-and that it&#8217;s the best and everything. Which is great. At
-least, it&#8217;s great if you don&#8217;t pay too much attention to it.
-Sometimes people will give an advice that is, in your opinion,
-a bad advice. And that&#8217;s okay. Don&#8217;t intervene every time
-someone gives a bad advice, learn to let it go. People will
-figure it out. You learn by making mistakes, after all. Use
-this extra time to make sure other people don&#8217;t end up
-giving the same bad advice instead. Fix the code or the
-documentation that led to this mistake. Slowly improve the
-project and make sure it doesn&#8217;t happen again.</p></div>
-<div class="paragraph"><p>This is my story. So far, anyway.</p></div>
-</description> + <description>As I am away from home with little to do (some call this a vacation) I wanted to reflect a little on the story so far, or how I arrived to Erlang and got to where I am now. The raw personal experience. It&#8217;ll be an article that&#8217;s more about social aspect, communities and marketing a project than technical considerations. As a period piece, it will also allow me to reflect on the evolution of Erlang in recent years.</description> </item> <item> @@ -1347,156 +159,8 @@ project and make sure it doesn&#8217;t happen again.</p></div> <pubDate>Wed, 20 Aug 2014 00:00:00 +0100</pubDate> <guid>https://ninenines.eu/articles/cowboy2-qs/</guid> - <description><div class="paragraph"><p>Now that Cowboy 1.0 is out, I can spend some of my time thinking
-about Cowboy 2.0 that will be released soon after Erlang/OTP 18.0.
-This entry discusses the proposed changes to query string handling
-in Cowboy.</p></div>
-<div class="paragraph"><p>Cowboy 2.0 will respond to user wishes by simplifying the interface
-of the <code>cowboy_req</code> module. Users want two things: less
-juggling with the Req variable, and more maps. Maps is the only
-dynamic key/value data structure in Erlang that we can match directly
-to extract values, allowing users to greatly simplify their code as
-they don&#8217;t need to call functions to do everything anymore.</p></div>
-<div class="paragraph"><p>Query strings are a good candidate for maps. It&#8217;s a list of
-key/values, so it&#8217;s pretty obvious we can win a lot by using maps.
-However query strings have one difference with maps: they can have
-duplicate keys.</p></div>
-<div class="paragraph"><p>How are we expected to handle duplicate keys? There&#8217;s no standard
-behavior. It&#8217;s up to applications. And looking at what is done in
-the wild, there&#8217;s no de facto standard either. While some ignore
-duplicate keys (keeping the first or the last they find), others
-require duplicate keys to end with <code>[]</code> to automatically
-put the values in a list, or even worse, languages like PHP even
-allow you to do things like <code>key[something][other]</code> and
-create a deep structure for it. Finally some allow any key to have
-duplicates and just gives you lists of key/values.</p></div>
-<div class="paragraph"><p>Cowboy so far had functions to retrieve query string values one
-value at a time, and if there were duplicates it would return the
-first it finds. It also has a function returning the entire list
-with all duplicates, allowing you to filter it to get all of them,
-and another function that returns the raw query string.</p></div>
-<div class="paragraph"><p>What are duplicates used for? Not that many things actually.</p></div>
-<div class="paragraph"><p>One use of duplicate keys is with HTML forms. It is common practice
-to give all related checkboxes the same name so you get a list of
-what&#8217;s been checked. When nothing is checked, nothing is sent at all,
-the key is not in the list.</p></div>
-<div class="paragraph"><p>Another use of duplicate keys is when generating forms. A good
-example of that would be a form that allows uploading any number
-of files. When you add a file, client-side code adds another field
-to the form. Repeat up to a certain limit.</p></div>
-<div class="paragraph"><p>And that&#8217;s about it. Of note is that HTML radio elements share
-the same name too, but only one key/value is sent, so they are not
-relevant here.</p></div>
-<div class="paragraph"><p>Normally this would be the part where I tell you how we solve
-this elegantly. But I had doubts. Why? Because there&#8217;s no good
-solutions to solving only this particular problem.</p></div>
-<div class="paragraph"><p>I then stopped thinking about duplicate keys for a minute and
-started to think about the larger problem.</p></div>
-<div class="paragraph"><p>Query strings are input data. They take a particular form,
-and may be sent as part of the URI or as part of the request
-body. We have other kinds of input data. We have headers and
-cookies and the request body in various forms. We also have
-path segments in URIs.</p></div>
-<div class="paragraph"><p>What do you do with input data? Well you use it to do
-something. But there is one thing that you almost always do
-(and if you don&#8217;t, you really should): you validate it and
-you map it into Erlang terms.</p></div>
-<div class="paragraph"><p>Cowboy left the user take care of validation and conversion
-into Erlang terms so far. Rather, it left the user take care
-of it everywhere except one place. Guess where? That&#8217;s right,
-bindings.</p></div>
-<div class="paragraph"><p>If you define routes with bindings then you have the option
-to provide constraints. Constraints can be used to do two things:
-validate the data and convert it in a more appropriate term. For
-example if you use the <code>int</code> constraint, Cowboy will
-make sure the binding is an integer, and will replace the value
-with the integer representation so that you can use it directly.
-In this particular case it not only routes the URI, but also
-validates and converts the bindings directly.</p></div>
-<div class="paragraph"><p>This is very relevant in the case of our duplicate keys,
-because if we have a list with duplicates of a key, chances
-are we want to convert that into a list of Erlang terms, and
-also make sure that all the elements in this list are expected.</p></div>
-<div class="paragraph"><p>The answer to this particular problem is simple. We need a
-function that will parse the query string and apply constraints.
-But this is not all, there is one other problem to be solved.</p></div>
-<div class="paragraph"><p>The other problem is that for the user some keys are mandatory
-and some are optional. Optional keys include the ones that
-correspond to HTML checkboxes: if the key for one or more
-checkbox is missing from the query string, we still want to
-have an empty list in our map so we can easily match. Matching
-maps is great, but not so much when values might be missing,
-so we have to normalize this data a little.</p></div>
-<div class="paragraph"><p>This problem is solved by allowing a default value. If the
-key is missing and a default exists, set it. If no default
-exists, then the key was mandatory and we want to crash.</p></div>
-<div class="paragraph"><p>I therefore make a proposal for changing the query string
-interface to three functions.</p></div>
-<div class="paragraph"><p>The first function already exists, it is <code>cowboy_req:qs(Req)</code>
-and it returns only the query string binary. No more Req returned.</p></div>
-<div class="paragraph"><p>The second function is a renaming of <code>cowboy_req:qs_vals(Req)</code>
-to something more explicit: <code>cowboy_req:parse_qs(Req)</code>.
-The new name implies that a parsing operation is done. It was implicit
-and cached before. It will be explicit and not cached anymore now.
-Again, no more Req returned.</p></div>
-<div class="paragraph"><p>The third function is the one I mentioned above. I think
-the interface <code>cowboy_req:match_qs(Req, Fields)</code> is
-most appropriate. It returns a normalized map that is the same
-regardless of optional fields being provided with the request,
-allowing for easy matching. It crashes if something went wrong.
-Still no Req returned.</p></div>
-<div class="paragraph"><p>I feel that this three function interface provides everything
-one would need to comfortably write applications. You can get
-low level and get the query string directly; you can get a list
-of key/value binaries without any additional processing and do it
-on your own; or you can get a processed map that contains Erlang
-terms ready to be used.</p></div>
-<div class="paragraph"><p>I strongly believe that by democratizing the constraints to
-more than just bindings, but also to query string, cookies and
-other key/values in Cowboy, we can allow the developer to quickly
-and easily go from HTTP request to Erlang function calls. The
-constraints are reusable functions that can serve as guards
-against unwanted data, providing convenience in the process.</p></div>
-<div class="paragraph"><p>Your handlers will not look like an endless series of calls
-to get and convert the input data, they will instead be just
-one call at the beginning followed by the actual application
-logic, thanks to constraints and maps.</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">handle</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-&gt;</span>
- #{<span style="color: #FF6600">name</span><span style="color: #990000">:=</span><span style="color: #009900">Name</span>, <span style="color: #FF6600">email</span><span style="color: #990000">:=</span><span style="color: #009900">Email</span>, <span style="color: #FF6600">choices</span><span style="color: #990000">:=</span><span style="color: #009900">ChoicesList</span>, <span style="color: #FF6600">remember_me</span><span style="color: #990000">:=</span><span style="color: #009900">RememberMe</span>} <span style="color: #990000">=</span>
- <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_qs</span></span>(<span style="color: #009900">Req</span>, [
- <span style="font-weight: bold"><span style="color: #000080">name</span></span>, {<span style="color: #FF6600">email</span>, <span style="color: #FF6600">email</span>},
- {<span style="color: #FF6600">choices</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span> <span style="font-weight: bold"><span style="color: #000000">check_choices</span></span><span style="color: #990000">/</span><span style="color: #993399">1</span>, []},
- {<span style="color: #FF6600">remember_me</span>, <span style="color: #FF6600">boolean</span>, <span style="color: #000080">false</span>}]),
- <span style="font-weight: bold"><span style="color: #000000">save_choices</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Email</span>, <span style="color: #009900">ChoicesList</span>),
- <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #009900">RememberMe</span> <span style="color: #990000">-&gt;</span> <span style="font-weight: bold"><span style="color: #000000">create_account</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Email</span>); <span style="color: #000080">true</span> <span style="color: #990000">-&gt;</span> <span style="color: #FF6600">ok</span> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>,
- {<span style="color: #FF6600">ok</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">check_choices</span></span>(<span style="color: #990000">&lt;&lt;</span><span style="color: #FF0000">"blue"</span><span style="color: #990000">&gt;&gt;</span>) <span style="color: #990000">-&gt;</span> {<span style="color: #000080">true</span>, <span style="color: #FF6600">blue</span>};
-<span style="font-weight: bold"><span style="color: #000000">check_choices</span></span>(<span style="color: #990000">&lt;&lt;</span><span style="color: #FF0000">"red"</span><span style="color: #990000">&gt;&gt;</span>) <span style="color: #990000">-&gt;</span> {<span style="color: #000080">true</span>, <span style="color: #FF6600">red</span>};
-<span style="font-weight: bold"><span style="color: #000000">check_choices</span></span>(<span style="color: #990000">_</span>) <span style="color: #990000">-&gt;</span> <span style="color: #000080">false</span>;</tt></pre></div></div>
-<div class="paragraph"><p>(Don&#8217;t look too closely at the structure yet.)</p></div>
-<div class="paragraph"><p>As you can see in the above snippet, it becomes really easy
-to go from query string to values. You can also use the map
-directly as it is guaranteed to only contain the keys you
-specified, any extra key is not returned.</p></div>
-<div class="paragraph"><p>This would I believe be a huge step up as we can now
-focus on writing applications instead of translating HTTP
-calls. Cowboy can now take care of it.</p></div>
-<div class="paragraph"><p>And to conclude, this also solves our duplicate keys
-dilemma, as they now automatically become a list of binaries,
-and this list is then checked against constraints that
-will fail if they were not expecting a list. And in the
-example above, it even converts the values to atoms for
-easier manipulation.</p></div>
-<div class="paragraph"><p>As usual, feedback is more than welcome, and I apologize
-for the rocky structure of this post as it contains all the
-thoughts that went into this rather than just the conclusion.</p></div>
-</description> + <description>Now that Cowboy 1.0 is out, I can spend some of my time thinking about Cowboy 2.0 that will be released soon after Erlang/OTP 18.0. This entry discusses the proposed changes to query string handling in Cowboy. + Cowboy 2.0 will respond to user wishes by simplifying the interface of the cowboy_req module. Users want two things: less juggling with the Req variable, and more maps. Maps is the only dynamic key/value data structure in Erlang that we can match directly to extract values, allowing users to greatly simplify their code as they don&#8217;t need to call functions to do everything anymore.</description> </item> <item> @@ -1505,147 +169,121 @@ thoughts that went into this rather than just the conclusion.</p></div& <pubDate>Tue, 07 Jan 2014 00:00:00 +0100</pubDate> <guid>https://ninenines.eu/articles/january-2014-status/</guid> - <description><div class="paragraph"><p>I will now be regularly writing posts about project status, plans
-and hopes for the future.</p></div>
-<div class="paragraph"><p>Before that though, there&#8217;s one important news to share.</p></div>
-<div class="paragraph"><p>Until a year ago all development was financed through consulting
-and development services. This worked alright but too much time was
-spent doing things that didn&#8217;t benefit the open source projects.
-And that didn&#8217;t make me happy at all. Because I like being happy
-I stopped that for the most part and spent the year figuring things
-out, experimenting and discussing with people about it.</p></div>
-<div class="paragraph"><p>What makes me happy is answering these "what if" questions.
-Ranch and Cowboy are a direct product of that, as they originate
-from the "what if we could have a server running different protocols
-on different ports but all part of the same application?"; Erlang.mk
-is a bit different: "this works great for me, what if it could
-become the standard solution for building Erlang applications?".</p></div>
-<div class="paragraph"><p>When I successfully answer the question, this becomes a project
-that may end up largely benefiting the Erlang community. I love
-Erlang and I love enabling people to build awesome products based
-on my projects. It&#8217;s a lot more rewarding than activities like
-consulting where you only help one company at a time. And it&#8217;s
-also a much better use of my time as this has a bigger impact on
-the community.</p></div>
-<div class="paragraph"><p>The hard part is to figure out how to be able to spend 100%
-of the time on projects that you basically give away for free,
-and still be able to afford living.</p></div>
-<div class="paragraph"><p>The immediate solution was getting work sponsored by the
-<a href="http://www.leofs.org/">LeoFS project</a>. LeoFS is a great
-distributed file storage that I can only recommend to anyone who
-needs to store files or large pieces of data. The sponsorship
-works pretty great, and spurred development of the SPDY code in
-Cowboy amongst other things, plus a couple upcoming projects
-done more recently and getting a final touch before release.</p></div>
-<div class="paragraph"><p>It turns out sponsoring works great. So I&#8217;m thinking of
-expanding on it and hopefully get enough sponsoring for fulltime
-open source development. So I figured out a few things that
-can give incentive to companies willing to sponsor.</p></div>
-<div class="paragraph"><p>Sponsors can <em>request that a particular version of Cowboy
-be maintained indefinitely</em> (as long as they&#8217;re sponsoring).
-This means fixes will be backported. This doesn&#8217;t include
-features although I can take requests depending on feasability.</p></div>
-<div class="paragraph"><p>Sponsors can <em>have a direct, private line of communication</em>,
-useful when they need help debugging or optimizing their product.</p></div>
-<div class="paragraph"><p>Sponsors can <em>get their name associated with one of the
-project</em> and get a good standing in the community thanks
-to this. They would be featured in the README of the project
-which is viewed by hundreds of developers daily.</p></div>
-<div class="paragraph"><p>Sponsors can <em>be listed on this website</em>. I will modify
-the front page when we get a few more sponsors, they will be
-featured below the carousel of projects.</p></div>
-<div class="paragraph"><p>Please <a href="mailto:[email protected]">contact us</a> if
-you are interested in sponsoring, and say how much you are willing
-to sponsor. The goal here is only to have enough money to make a
-living and attend a few conferences. There&#8217;s an upper limit in the
-amount needed per year, so the more sponsors there are the cheaper
-it becomes to everyone.</p></div>
-<div class="paragraph"><p>The upper limit stems from the new legal entity that will replace
-the current Nine Nines. This is mostly to lower the legal costs and
-simplify the administrative stuff and allow me to dedicate all my
-time on what&#8217;s important. From your point of view it&#8217;s business as
-usual.</p></div>
-<div class="paragraph"><p>Now on to project statuses and future works.</p></div>
-<div class="sect1">
-<h2 id="_cowboy">Cowboy</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy is getting ready for a 1.0 release. Once multipart support
-is in, all that&#8217;s left is finishing the guide, improving tests and
-finishing moving code to the cowlib project. I hope everything will
-be ready around the time R17B is released.</p></div>
-<div class="paragraph"><p>I already dream of some API breaking changes after 1.0, which
-would essentially become 2.0 when they&#8217;re done. An extensive survey
-will be setup after the 1.0 release to get more information on what
-people like and don&#8217;t like about the API.</p></div>
-<div class="paragraph"><p>And of course, when clients start implementing HTTP/2.0 then we
-will too.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_ranch">Ranch</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch is also getting close to 1.0. I am currently writing a
-test suite for upgrades. After that I also would like to write
-a chaos_monkey test suite and add a getting started chapter to the
-guide.</p></div>
-<div class="paragraph"><p>Ranch is pretty solid otherwise, it&#8217;s hard to foresee new
-features at this point.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_erlang_mk">Erlang.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>I didn&#8217;t expect this project to become popular. Glad it did though.</p></div>
-<div class="paragraph"><p>Windows support is planned, but will require GNU Make 4.
-Thankfully, it&#8217;s available at least through cygwin. Make,
-Git and Erlang will be the only required dependencies
-because the rest of the external calls will be converted to
-using Guile, a Scheme included since GNU Make 4. So it is
-Guile that will download the needed files, magically fill
-the list of modules in the <em>.app</em> file and so on, allowing
-us to provide a truly cross-platform solution without
-losing on the performance we benefit from using Make.</p></div>
-<div class="paragraph"><p>Also note that it is possible to check whether Guile
-is available so we will be able to fallback to the current
-code for older systems.</p></div>
-<div class="paragraph"><p>I am also thinking about adding an extra column to the package
-index, indicating the preferred tag or commit number to be used.
-This would allow us to skip the individual <code>dep</code> lines
-entirely if the information in the package index is good enough.
-And committing that file to your project would be the only thing
-needed to lock the dependencies. Of course if a <code>dep</code>
-line is specified this would instead override the file.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_alien_shaman">Alien Shaman</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This is the two-parts project requested by the LeoFS team.
-This is essentially a "distributed bigwig". I am hoping to
-have a prototype up in a few days.</p></div>
-<div class="paragraph"><p>Alien is the part that allows writing and enabling probes
-in your nodes. Probes send events which may get filtered before
-being forwarded to their destination. The events may be sent
-to a local process, a remote process, over UDP, TCP or SSL.
-Events may also be received by a process called a relay, which
-may be used to group or aggregate data before it is being sent
-over the network, reducing the footprint overall.</p></div>
-<div class="paragraph"><p>Shaman is the UI for it. It will ultimately be able to display
-any event as long as it&#8217;s configured to do so. Events may be logs,
-numeric values displayed on graphs updated in real time, lists of
-items like processes and so on.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_feedback">Feedback</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>That&#8217;s it for today! There will be another status update once
-Shaman is out. But for now I have to focus on it.</p></div>
-<div class="paragraph"><p>As always, please send feedback on the projects, this post,
-the sponsoring idea, anything really! Thanks.</p></div>
-</div>
-</div>
-</description> + <description>I will now be regularly writing posts about project status, plans and hopes for the future. + Before that though, there&#8217;s one important news to share. + Until a year ago all development was financed through consulting and development services. This worked alright but too much time was spent doing things that didn&#8217;t benefit the open source projects. And that didn&#8217;t make me happy at all. Because I like being happy I stopped that for the most part and spent the year figuring things out, experimenting and discussing with people about it.</description> + </item> + + <item> + <title>Farwest got funded!</title> + <link>https://ninenines.eu/articles/farwest-funded/</link> + <pubDate>Thu, 27 Jun 2013 00:00:00 +0100</pubDate> + + <guid>https://ninenines.eu/articles/farwest-funded/</guid> + <description>This was a triumph! I&#8217;m making a note here: HUGE SUCCESS!! + It&#8217;s hard to overstate my satisfaction. Thanks to everyone who made this possible. + If you have backed this fundraiser, and haven&#8217;t provided your personal details yet, please do so quickly so that your rewards can be sent! + I am hoping that we will be able to make good use of all that money. The details of the expenses will be published regularly on the 2013 Fundraiser wiki page, giving you full disclosure as to how your money is used.</description> + </item> + + <item> + <title>Build Erlang releases with Erlang.mk and Relx</title> + <link>https://ninenines.eu/articles/erlang.mk-and-relx/</link> + <pubDate>Tue, 28 May 2013 00:00:00 +0100</pubDate> + + <guid>https://ninenines.eu/articles/erlang.mk-and-relx/</guid> + <description>Building OTP releases has always been a difficult task. Tools like Reltool or Rebar have made this simpler, but it&#8217;s no panacea. This article will show you an alternative and hopefully much simpler solution. + There is two steps to building a release. First you need to build the various OTP applications you want to include in the release. Once done, you need to create the release itself, by including the Erlang runtime system alongside the applications, a boot script to start the node and all its applications, and some configuration files.</description> + </item> + + <item> + <title>Xerl: intermediate module</title> + <link>https://ninenines.eu/articles/xerl-0.5-intermediate-module/</link> + <pubDate>Mon, 25 Mar 2013 00:00:00 +0100</pubDate> + + <guid>https://ninenines.eu/articles/xerl-0.5-intermediate-module/</guid> + <description>Today we will start the work on the intermediate module that will be used to run the code for the expressions found in our file&#8217;s body, replacing our interpreter. + This is what we want to have when all the work is done: + xerl -&gt; tokens -&gt; AST -&gt; intermediate -&gt; cerl Today we will perform this work only on the atomic integer expression however, so we will not build any module at the end.</description> + </item> + + <item> + <title>Xerl: expression separator</title> + <link>https://ninenines.eu/articles/xerl-0.4-expression-separator/</link> + <pubDate>Fri, 01 Mar 2013 00:00:00 +0100</pubDate> + + <guid>https://ninenines.eu/articles/xerl-0.4-expression-separator/</guid> + <description>As promised we are adding an expression separator this time. This will be short and easy. + In the tokenizer we only need to add a line recognizing the comma as a valid token. + , : {token, {',', TokenLine}}. Then we need to change the following lines in the parser: + exprs -&gt; expr : ['$1']. exprs -&gt; expr exprs : ['$1' | '$2']. And add a comma between the expressions on the second line:</description> + </item> + + <item> + <title>Erlang Scalability</title> + <link>https://ninenines.eu/articles/erlang-scalability/</link> + <pubDate>Mon, 18 Feb 2013 00:00:00 +0100</pubDate> + + <guid>https://ninenines.eu/articles/erlang-scalability/</guid> + <description>I would like to share some experience and theories on Erlang scalability. + This will be in the form of a series of hints, which may or may not be accompanied with explanations as to why things are this way, or how they improve or reduce the scalability of a system. I will try to do my best to avoid giving falsehoods, even if that means a few things won&#8217;t be explained.</description> + </item> + + <item> + <title>Xerl: atomic expressions</title> + <link>https://ninenines.eu/articles/xerl-0.3-atomic-expressions/</link> + <pubDate>Mon, 18 Feb 2013 00:00:00 +0100</pubDate> + + <guid>https://ninenines.eu/articles/xerl-0.3-atomic-expressions/</guid> + <description>We will be adding atomic integer expressions to our language. These look as follow in Erlang: + 42. And the result of this expression is of course 42. + We will be running this expression at compile time, since we don&#8217;t have the means to run code at runtime yet. This will of course result in no module being compiled, but that&#8217;s OK, it will allow us to discuss a few important things we&#8217;ll have to plan for later on.</description> + </item> + + <item> + <title>Xerl: two modules</title> + <link>https://ninenines.eu/articles/xerl-0.2-two-modules/</link> + <pubDate>Sun, 03 Feb 2013 00:00:00 +0100</pubDate> + + <guid>https://ninenines.eu/articles/xerl-0.2-two-modules/</guid> + <description>Everything is an expression. + This sentence carries profound meaning. We will invoke it many times over the course of these articles. + If everything is an expression, then the language shouldn&#8217;t have any problem with me defining two modules in the same source file. + mod first_module begin end mod second_module begin end Likewise, it shouldn&#8217;t have any problem with me defining a module inside another module. + mod out_module begin mod in_module begin end end Of course, in the context of the Erlang VM, these two snippets are equivalent; there is nothing preventing you from calling the in_module module from any other module.</description> + </item> + + <item> + <title>Xerl: empty modules</title> + <link>https://ninenines.eu/articles/xerl-0.1-empty-modules/</link> + <pubDate>Wed, 30 Jan 2013 00:00:00 +0100</pubDate> + + <guid>https://ninenines.eu/articles/xerl-0.1-empty-modules/</guid> + <description>Let&#8217;s build a programming language. I call it Xerl: eXtended ERLang. It&#8217;ll be an occasion for us to learn a few things, especially me. + Unlike in Erlang, in this language, everything is an expression. This means that modules and functions are expression, and indeed that you can have more than one module per file. + We are just starting, so let&#8217;s no go ahead of ourselves here. We&#8217;ll begin with writing the code allowing us to compile an empty module.</description> + </item> + + <item> + <title>Build an FTP Server with Ranch in 30 Minutes</title> + <link>https://ninenines.eu/articles/ranch-ftp/</link> + <pubDate>Wed, 14 Nov 2012 00:00:00 +0100</pubDate> + + <guid>https://ninenines.eu/articles/ranch-ftp/</guid> + <description>Last week I was speaking at the London Erlang Factory Lite where I presented a live demonstration of building an FTP server using Ranch. As there was no slide, you should use this article as a reference instead. + The goal of this article is to showcase how to use Ranch for writing a network protocol implementation, how Ranch gets out of the way to let you write the code that matters, and the common techniques used when writing servers.</description> + </item> + + <item> + <title>Erlang Tic Tac Toe</title> + <link>https://ninenines.eu/articles/tictactoe/</link> + <pubDate>Wed, 17 Oct 2012 00:00:00 +0100</pubDate> + + <guid>https://ninenines.eu/articles/tictactoe/</guid> + <description>Everyone knows Tic Tac Toe, right? + Players choose either to be the Xs or the Os, then place their symbol on a 3x3 board one after another, trying to create a line of 3 of them. + Writing an algorithm to check for victory sounds easy, right? It&#8217;s easily tested, considering there&#8217;s only 8 possible winning rows (3 horizontal, 3 vertical and 2 diagonal). + In Erlang though, you probably wouldn&#8217;t want an algorithm.</description> </item> </channel> diff --git a/articles/january-2014-status/index.html b/articles/january-2014-status/index.html index aaaa0845..39a776ef 100644 --- a/articles/january-2014-status/index.html +++ b/articles/january-2014-status/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: January 2014 status</title> @@ -74,146 +74,146 @@ </p> </header> -<div class="paragraph"><p>I will now be regularly writing posts about project status, plans
-and hopes for the future.</p></div>
-<div class="paragraph"><p>Before that though, there’s one important news to share.</p></div>
-<div class="paragraph"><p>Until a year ago all development was financed through consulting
-and development services. This worked alright but too much time was
-spent doing things that didn’t benefit the open source projects.
-And that didn’t make me happy at all. Because I like being happy
-I stopped that for the most part and spent the year figuring things
-out, experimenting and discussing with people about it.</p></div>
-<div class="paragraph"><p>What makes me happy is answering these "what if" questions.
-Ranch and Cowboy are a direct product of that, as they originate
-from the "what if we could have a server running different protocols
-on different ports but all part of the same application?"; Erlang.mk
-is a bit different: "this works great for me, what if it could
-become the standard solution for building Erlang applications?".</p></div>
-<div class="paragraph"><p>When I successfully answer the question, this becomes a project
-that may end up largely benefiting the Erlang community. I love
-Erlang and I love enabling people to build awesome products based
-on my projects. It’s a lot more rewarding than activities like
-consulting where you only help one company at a time. And it’s
-also a much better use of my time as this has a bigger impact on
-the community.</p></div>
-<div class="paragraph"><p>The hard part is to figure out how to be able to spend 100%
-of the time on projects that you basically give away for free,
-and still be able to afford living.</p></div>
-<div class="paragraph"><p>The immediate solution was getting work sponsored by the
-<a href="http://www.leofs.org/">LeoFS project</a>. LeoFS is a great
-distributed file storage that I can only recommend to anyone who
-needs to store files or large pieces of data. The sponsorship
-works pretty great, and spurred development of the SPDY code in
-Cowboy amongst other things, plus a couple upcoming projects
-done more recently and getting a final touch before release.</p></div>
-<div class="paragraph"><p>It turns out sponsoring works great. So I’m thinking of
-expanding on it and hopefully get enough sponsoring for fulltime
-open source development. So I figured out a few things that
-can give incentive to companies willing to sponsor.</p></div>
-<div class="paragraph"><p>Sponsors can <em>request that a particular version of Cowboy
-be maintained indefinitely</em> (as long as they’re sponsoring).
-This means fixes will be backported. This doesn’t include
-features although I can take requests depending on feasability.</p></div>
-<div class="paragraph"><p>Sponsors can <em>have a direct, private line of communication</em>,
-useful when they need help debugging or optimizing their product.</p></div>
-<div class="paragraph"><p>Sponsors can <em>get their name associated with one of the
-project</em> and get a good standing in the community thanks
-to this. They would be featured in the README of the project
-which is viewed by hundreds of developers daily.</p></div>
-<div class="paragraph"><p>Sponsors can <em>be listed on this website</em>. I will modify
-the front page when we get a few more sponsors, they will be
-featured below the carousel of projects.</p></div>
-<div class="paragraph"><p>Please <a href="mailto:[email protected]">contact us</a> if
-you are interested in sponsoring, and say how much you are willing
-to sponsor. The goal here is only to have enough money to make a
-living and attend a few conferences. There’s an upper limit in the
-amount needed per year, so the more sponsors there are the cheaper
-it becomes to everyone.</p></div>
-<div class="paragraph"><p>The upper limit stems from the new legal entity that will replace
-the current Nine Nines. This is mostly to lower the legal costs and
-simplify the administrative stuff and allow me to dedicate all my
-time on what’s important. From your point of view it’s business as
-usual.</p></div>
-<div class="paragraph"><p>Now on to project statuses and future works.</p></div>
-<div class="sect1">
-<h2 id="_cowboy">Cowboy</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy is getting ready for a 1.0 release. Once multipart support
-is in, all that’s left is finishing the guide, improving tests and
-finishing moving code to the cowlib project. I hope everything will
-be ready around the time R17B is released.</p></div>
-<div class="paragraph"><p>I already dream of some API breaking changes after 1.0, which
-would essentially become 2.0 when they’re done. An extensive survey
-will be setup after the 1.0 release to get more information on what
-people like and don’t like about the API.</p></div>
-<div class="paragraph"><p>And of course, when clients start implementing HTTP/2.0 then we
-will too.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_ranch">Ranch</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch is also getting close to 1.0. I am currently writing a
-test suite for upgrades. After that I also would like to write
-a chaos_monkey test suite and add a getting started chapter to the
-guide.</p></div>
-<div class="paragraph"><p>Ranch is pretty solid otherwise, it’s hard to foresee new
-features at this point.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_erlang_mk">Erlang.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>I didn’t expect this project to become popular. Glad it did though.</p></div>
-<div class="paragraph"><p>Windows support is planned, but will require GNU Make 4.
-Thankfully, it’s available at least through cygwin. Make,
-Git and Erlang will be the only required dependencies
-because the rest of the external calls will be converted to
-using Guile, a Scheme included since GNU Make 4. So it is
-Guile that will download the needed files, magically fill
-the list of modules in the <em>.app</em> file and so on, allowing
-us to provide a truly cross-platform solution without
-losing on the performance we benefit from using Make.</p></div>
-<div class="paragraph"><p>Also note that it is possible to check whether Guile
-is available so we will be able to fallback to the current
-code for older systems.</p></div>
-<div class="paragraph"><p>I am also thinking about adding an extra column to the package
-index, indicating the preferred tag or commit number to be used.
-This would allow us to skip the individual <code>dep</code> lines
-entirely if the information in the package index is good enough.
-And committing that file to your project would be the only thing
-needed to lock the dependencies. Of course if a <code>dep</code>
-line is specified this would instead override the file.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_alien_shaman">Alien Shaman</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This is the two-parts project requested by the LeoFS team.
-This is essentially a "distributed bigwig". I am hoping to
-have a prototype up in a few days.</p></div>
-<div class="paragraph"><p>Alien is the part that allows writing and enabling probes
-in your nodes. Probes send events which may get filtered before
-being forwarded to their destination. The events may be sent
-to a local process, a remote process, over UDP, TCP or SSL.
-Events may also be received by a process called a relay, which
-may be used to group or aggregate data before it is being sent
-over the network, reducing the footprint overall.</p></div>
-<div class="paragraph"><p>Shaman is the UI for it. It will ultimately be able to display
-any event as long as it’s configured to do so. Events may be logs,
-numeric values displayed on graphs updated in real time, lists of
-items like processes and so on.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_feedback">Feedback</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>That’s it for today! There will be another status update once
-Shaman is out. But for now I have to focus on it.</p></div>
-<div class="paragraph"><p>As always, please send feedback on the projects, this post,
-the sponsoring idea, anything really! Thanks.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>I will now be regularly writing posts about project status, plans +and hopes for the future.</p></div> +<div class="paragraph"><p>Before that though, there’s one important news to share.</p></div> +<div class="paragraph"><p>Until a year ago all development was financed through consulting +and development services. This worked alright but too much time was +spent doing things that didn’t benefit the open source projects. +And that didn’t make me happy at all. Because I like being happy +I stopped that for the most part and spent the year figuring things +out, experimenting and discussing with people about it.</p></div> +<div class="paragraph"><p>What makes me happy is answering these "what if" questions. +Ranch and Cowboy are a direct product of that, as they originate +from the "what if we could have a server running different protocols +on different ports but all part of the same application?"; Erlang.mk +is a bit different: "this works great for me, what if it could +become the standard solution for building Erlang applications?".</p></div> +<div class="paragraph"><p>When I successfully answer the question, this becomes a project +that may end up largely benefiting the Erlang community. I love +Erlang and I love enabling people to build awesome products based +on my projects. It’s a lot more rewarding than activities like +consulting where you only help one company at a time. And it’s +also a much better use of my time as this has a bigger impact on +the community.</p></div> +<div class="paragraph"><p>The hard part is to figure out how to be able to spend 100% +of the time on projects that you basically give away for free, +and still be able to afford living.</p></div> +<div class="paragraph"><p>The immediate solution was getting work sponsored by the +<a href="http://www.leofs.org/">LeoFS project</a>. LeoFS is a great +distributed file storage that I can only recommend to anyone who +needs to store files or large pieces of data. The sponsorship +works pretty great, and spurred development of the SPDY code in +Cowboy amongst other things, plus a couple upcoming projects +done more recently and getting a final touch before release.</p></div> +<div class="paragraph"><p>It turns out sponsoring works great. So I’m thinking of +expanding on it and hopefully get enough sponsoring for fulltime +open source development. So I figured out a few things that +can give incentive to companies willing to sponsor.</p></div> +<div class="paragraph"><p>Sponsors can <em>request that a particular version of Cowboy +be maintained indefinitely</em> (as long as they’re sponsoring). +This means fixes will be backported. This doesn’t include +features although I can take requests depending on feasability.</p></div> +<div class="paragraph"><p>Sponsors can <em>have a direct, private line of communication</em>, +useful when they need help debugging or optimizing their product.</p></div> +<div class="paragraph"><p>Sponsors can <em>get their name associated with one of the +project</em> and get a good standing in the community thanks +to this. They would be featured in the README of the project +which is viewed by hundreds of developers daily.</p></div> +<div class="paragraph"><p>Sponsors can <em>be listed on this website</em>. I will modify +the front page when we get a few more sponsors, they will be +featured below the carousel of projects.</p></div> +<div class="paragraph"><p>Please <a href="mailto:[email protected]">contact us</a> if +you are interested in sponsoring, and say how much you are willing +to sponsor. The goal here is only to have enough money to make a +living and attend a few conferences. There’s an upper limit in the +amount needed per year, so the more sponsors there are the cheaper +it becomes to everyone.</p></div> +<div class="paragraph"><p>The upper limit stems from the new legal entity that will replace +the current Nine Nines. This is mostly to lower the legal costs and +simplify the administrative stuff and allow me to dedicate all my +time on what’s important. From your point of view it’s business as +usual.</p></div> +<div class="paragraph"><p>Now on to project statuses and future works.</p></div> +<div class="sect1"> +<h2 id="_cowboy">Cowboy</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy is getting ready for a 1.0 release. Once multipart support +is in, all that’s left is finishing the guide, improving tests and +finishing moving code to the cowlib project. I hope everything will +be ready around the time R17B is released.</p></div> +<div class="paragraph"><p>I already dream of some API breaking changes after 1.0, which +would essentially become 2.0 when they’re done. An extensive survey +will be setup after the 1.0 release to get more information on what +people like and don’t like about the API.</p></div> +<div class="paragraph"><p>And of course, when clients start implementing HTTP/2.0 then we +will too.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_ranch">Ranch</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch is also getting close to 1.0. I am currently writing a +test suite for upgrades. After that I also would like to write +a chaos_monkey test suite and add a getting started chapter to the +guide.</p></div> +<div class="paragraph"><p>Ranch is pretty solid otherwise, it’s hard to foresee new +features at this point.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_erlang_mk">Erlang.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>I didn’t expect this project to become popular. Glad it did though.</p></div> +<div class="paragraph"><p>Windows support is planned, but will require GNU Make 4. +Thankfully, it’s available at least through cygwin. Make, +Git and Erlang will be the only required dependencies +because the rest of the external calls will be converted to +using Guile, a Scheme included since GNU Make 4. So it is +Guile that will download the needed files, magically fill +the list of modules in the <em>.app</em> file and so on, allowing +us to provide a truly cross-platform solution without +losing on the performance we benefit from using Make.</p></div> +<div class="paragraph"><p>Also note that it is possible to check whether Guile +is available so we will be able to fallback to the current +code for older systems.</p></div> +<div class="paragraph"><p>I am also thinking about adding an extra column to the package +index, indicating the preferred tag or commit number to be used. +This would allow us to skip the individual <code>dep</code> lines +entirely if the information in the package index is good enough. +And committing that file to your project would be the only thing +needed to lock the dependencies. Of course if a <code>dep</code> +line is specified this would instead override the file.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_alien_shaman">Alien Shaman</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This is the two-parts project requested by the LeoFS team. +This is essentially a "distributed bigwig". I am hoping to +have a prototype up in a few days.</p></div> +<div class="paragraph"><p>Alien is the part that allows writing and enabling probes +in your nodes. Probes send events which may get filtered before +being forwarded to their destination. The events may be sent +to a local process, a remote process, over UDP, TCP or SSL. +Events may also be received by a process called a relay, which +may be used to group or aggregate data before it is being sent +over the network, reducing the footprint overall.</p></div> +<div class="paragraph"><p>Shaman is the UI for it. It will ultimately be able to display +any event as long as it’s configured to do so. Events may be logs, +numeric values displayed on graphs updated in real time, lists of +items like processes and so on.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_feedback">Feedback</h2> +<div class="sectionbody"> +<div class="paragraph"><p>That’s it for today! There will be another status update once +Shaman is out. But for now I have to focus on it.</p></div> +<div class="paragraph"><p>As always, please send feedback on the projects, this post, +the sponsoring idea, anything really! Thanks.</p></div> +</div> +</div> </article> </div> @@ -222,55 +222,107 @@ the sponsoring idea, anything really! Thanks.</p></div> <h3>More articles</h3> <ul id="articles-nav" class="extra_margin"> - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + + <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + - <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + + <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + - <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + + <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + - <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + + <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + - <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + + <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + - <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + + <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + - <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + + <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + - <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + + <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + - <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + + <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + - <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + + <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + - <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + </ul> diff --git a/articles/ml-archives/index.html b/articles/ml-archives/index.html index 34fa9ff1..e668b252 100644 --- a/articles/ml-archives/index.html +++ b/articles/ml-archives/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Mailing list archived</title> @@ -74,16 +74,16 @@ </p> </header> -<div class="paragraph"><p>The <a href="/archives/extend">old mailing list archives</a> have been
-added to the site, mainly for referencing purposes.</p></div>
-<div class="paragraph"><p>The mailing list has been shut down and all personal information
-has been deleted.</p></div>
-<div class="paragraph"><p>If you need help with a project, consider either opening a ticket
-on that project’s issues tracker or going through the community
-channels (erlang-questions, #ninenines or #erlang on Freenode).</p></div>
-<div class="paragraph"><p>Prefer tickets; often when people have issues it highlights an
-underlying problem in the project or its documentation.</p></div>
-<div class="paragraph"><p>Thanks.</p></div>
+<div class="paragraph"><p>The <a href="/archives/extend">old mailing list archives</a> have been +added to the site, mainly for referencing purposes.</p></div> +<div class="paragraph"><p>The mailing list has been shut down and all personal information +has been deleted.</p></div> +<div class="paragraph"><p>If you need help with a project, consider either opening a ticket +on that project’s issues tracker or going through the community +channels (erlang-questions, #ninenines or #erlang on Freenode).</p></div> +<div class="paragraph"><p>Prefer tickets; often when people have issues it highlights an +underlying problem in the project or its documentation.</p></div> +<div class="paragraph"><p>Thanks.</p></div> </article> </div> @@ -92,55 +92,107 @@ underlying problem in the project or its documentation.</p></div> <h3>More articles</h3> <ul id="articles-nav" class="extra_margin"> - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + - <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + + <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + - <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + + <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + - <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + + <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + - <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + + <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + - <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + + <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + - <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + + <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + - <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + + <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + - <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + + <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + - <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + + <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + - <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + + </ul> diff --git a/articles/on-open-source/index.html b/articles/on-open-source/index.html index bc587fdd..60564636 100644 --- a/articles/on-open-source/index.html +++ b/articles/on-open-source/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: On open source</title> @@ -74,123 +74,123 @@ </p> </header> -<div class="paragraph"><p>Last week I read a great article
-<a href="http://videlalvaro.github.io/2014/08/on-contributing-to-opensource.html">on
-contributing to open source</a> by Alvaro Videla. He makes
-many great points and I am in agreement with most of it.
-This made me want to properly explain my point of view with
-regard to open source and contributions. Unlike most open
-source evangelism articles I will not talk about ideals or
-any of that crap, but rather my personal feelings and
-experience.</p></div>
-<div class="paragraph"><p>I have been doing open source work for quite some time.
-My very first open source project was a graphics driver
-for (the very early version of) the PCSX2 emulator. That
-was more than ten years ago, and there
-<a href="http://ngemu.com/threads/gstaris-0-6.30469/">isn’t
-much left to look at today</a>. This was followed by a
-<a href="https://github.com/extend/wee">PHP framework</a>
-(started long before Zend Framework was even a thing) and
-a few other small projects. None of them really took off.
-It’s alright, that’s pretty much the fate of most open
-source projects. You spend a lot of work and sweat and
-get very little in return from others.</p></div>
-<div class="paragraph"><p>This sounds harsh but this is the reality of all open
-source projects. If you are thinking of building a project
-and releasing it as open source, you should be prepared
-for that. This is how most of your projects will feel like.
-Don’t release a project as open source thinking everyone
-will pat you on the back and cheer, this won’t happen. In
-fact if your project is a too small improvement over existing
-software, what many people will do is say you have NIH
-syndrome, regardless of the improvement you bring. So you
-need not to rely on other people in order to get your
-enjoyment out of building open source software.</p></div>
-<div class="paragraph"><p>In my case I get enjoyment from thinking about problems
-that need solving. Often times the problems are already
-solved, but nevermind that, I still think about them and
-sometimes come up with something I feel is better and then
-write code for it. Writing code is also fun, but not as
-fun as using my brain to imagine solutions.</p></div>
-<div class="paragraph"><p>You don’t need thousands of users to do that. So are
-users worthless to me then? No, of course not. In fact
-they are an important component: they bring me problems
-that need solving. So users are very important to me.
-But that’s not the only reason.</p></div>
-<div class="paragraph"><p>I got lucky that the Cowboy project became popular.
-And seeing it be this popular, and some of my other projects
-also do quite well, made me believe I could perhaps work
-full time on open source. If I can work full time then
-I can produce better software. What I had one hour to
-work on before I can now spend a day on, and experiment
-until I am satisfied. This is very useful because that
-means I can get it almost right from the beginning, and
-avoid the million API breaking changes that occured
-before Cowboy 1.0 was released.</p></div>
-<div class="paragraph"><p>To be able to work full time on open source however,
-I need money. This is a largely unspoken topic of open
-source work. The work is never free. You can download the
-product for free, but someone has to pay for the work
-itself. Life is unfortunately not free.</p></div>
-<div class="paragraph"><p>Large projects and some lucky people have their work
-sponsored by their employers. Everyone else has to deal
-with it differently. In my case I was sponsored for a
-while by the <a href="http://leo-project.net/leofs/">LeoFS</a>
-project, but that ended. I also had the Farwest fundraiser,
-which was a success, although the project stalled after that.
-(Fear not, as Farwest will make a comeback as a conglomerate
-of Web development projects in the future.) After that I set
-up the <a href="http://ninenines.eu/support/">sponsoring scheme</a>,
-which I can proudly say today brings in enough money to
-cover my food and shelter. Great!</p></div>
-<div class="paragraph"><p>This is a start, but it’s of course not enough. Life
-is a little more than food and shelter, and so I am still
-looking for sponsors. This is not a very glorious experience,
-as I am essentially looking for scraps that companies can
-throw away. Still, if a handful more companies were doing
-that, not only would I be able to live comfortably, but I
-would also be able to stop worrying about the future as I
-could put money on the side for when it gets rough.</p></div>
-<div class="paragraph"><p>A few companies giving me some scrap money so I could
-live and work independently is by far the most important
-thing anyone can do to help my projects, including Cowboy.
-Yes, they’re even more important than code contributions,
-bug reports and feedback. Because this money gives me the
-time I need to handle the code contributions, bug reports
-and feedback.</p></div>
-<div class="paragraph"><p>If Cowboy or another project is a large part of your
-product or infrastructure, then the best thing you can do
-is become a sponsor. The second best is opening tickets
-and/or providing feedback. The third best is providing
-good code contributions.</p></div>
-<div class="paragraph"><p>I will not expand on the feedback part. Feedback is
-very important, and even just a high five or a retweet
-is already good feedback. It’s not very complicated.</p></div>
-<div class="paragraph"><p>I want to expand a little on code contributions
-however. Not long ago I ran across the term "patch bomb"
-which means dropping patches and expecting the project
-maintainers to merge them and maintain them. I receive
-a lot of patches, and often have to refuse them. Causes
-for refusal vary. Some patches only benefit the people
-who submitted them (or a very small number of people).
-Some patches are not refined enough to be included.
-Others are out of scope of the project. These are some
-of the reasons why I refuse patches. Having limited
-time and resources, I have to focus my efforts on the
-code used by the larger number of users. I have to
-prioritize patches from submitters who are reactive
-and address the issues pointed out. And I have to plainly
-refuse other patches.</p></div>
-<div class="paragraph"><p>I believe this wraps up my thoughts on open source.
-Overall I had a great experience, the Erlang community
-being nice and understanding of the issues at hand in
-general. And if the money problem could be solved soon,
-then I would be one of the luckiest and happiest open
-source developer on Earth.</p></div>
-<div class="paragraph"><p>Think about it the next time you see a donation button
-or a request for funds or sponsoring. You can considerably
-improve an open source developer’s life with very little
-of your company’s money.</p></div>
+<div class="paragraph"><p>Last week I read a great article +<a href="http://videlalvaro.github.io/2014/08/on-contributing-to-opensource.html">on +contributing to open source</a> by Alvaro Videla. He makes +many great points and I am in agreement with most of it. +This made me want to properly explain my point of view with +regard to open source and contributions. Unlike most open +source evangelism articles I will not talk about ideals or +any of that crap, but rather my personal feelings and +experience.</p></div> +<div class="paragraph"><p>I have been doing open source work for quite some time. +My very first open source project was a graphics driver +for (the very early version of) the PCSX2 emulator. That +was more than ten years ago, and there +<a href="http://ngemu.com/threads/gstaris-0-6.30469/">isn’t +much left to look at today</a>. This was followed by a +<a href="https://github.com/extend/wee">PHP framework</a> +(started long before Zend Framework was even a thing) and +a few other small projects. None of them really took off. +It’s alright, that’s pretty much the fate of most open +source projects. You spend a lot of work and sweat and +get very little in return from others.</p></div> +<div class="paragraph"><p>This sounds harsh but this is the reality of all open +source projects. If you are thinking of building a project +and releasing it as open source, you should be prepared +for that. This is how most of your projects will feel like. +Don’t release a project as open source thinking everyone +will pat you on the back and cheer, this won’t happen. In +fact if your project is a too small improvement over existing +software, what many people will do is say you have NIH +syndrome, regardless of the improvement you bring. So you +need not to rely on other people in order to get your +enjoyment out of building open source software.</p></div> +<div class="paragraph"><p>In my case I get enjoyment from thinking about problems +that need solving. Often times the problems are already +solved, but nevermind that, I still think about them and +sometimes come up with something I feel is better and then +write code for it. Writing code is also fun, but not as +fun as using my brain to imagine solutions.</p></div> +<div class="paragraph"><p>You don’t need thousands of users to do that. So are +users worthless to me then? No, of course not. In fact +they are an important component: they bring me problems +that need solving. So users are very important to me. +But that’s not the only reason.</p></div> +<div class="paragraph"><p>I got lucky that the Cowboy project became popular. +And seeing it be this popular, and some of my other projects +also do quite well, made me believe I could perhaps work +full time on open source. If I can work full time then +I can produce better software. What I had one hour to +work on before I can now spend a day on, and experiment +until I am satisfied. This is very useful because that +means I can get it almost right from the beginning, and +avoid the million API breaking changes that occured +before Cowboy 1.0 was released.</p></div> +<div class="paragraph"><p>To be able to work full time on open source however, +I need money. This is a largely unspoken topic of open +source work. The work is never free. You can download the +product for free, but someone has to pay for the work +itself. Life is unfortunately not free.</p></div> +<div class="paragraph"><p>Large projects and some lucky people have their work +sponsored by their employers. Everyone else has to deal +with it differently. In my case I was sponsored for a +while by the <a href="http://leo-project.net/leofs/">LeoFS</a> +project, but that ended. I also had the Farwest fundraiser, +which was a success, although the project stalled after that. +(Fear not, as Farwest will make a comeback as a conglomerate +of Web development projects in the future.) After that I set +up the <a href="http://ninenines.eu/support/">sponsoring scheme</a>, +which I can proudly say today brings in enough money to +cover my food and shelter. Great!</p></div> +<div class="paragraph"><p>This is a start, but it’s of course not enough. Life +is a little more than food and shelter, and so I am still +looking for sponsors. This is not a very glorious experience, +as I am essentially looking for scraps that companies can +throw away. Still, if a handful more companies were doing +that, not only would I be able to live comfortably, but I +would also be able to stop worrying about the future as I +could put money on the side for when it gets rough.</p></div> +<div class="paragraph"><p>A few companies giving me some scrap money so I could +live and work independently is by far the most important +thing anyone can do to help my projects, including Cowboy. +Yes, they’re even more important than code contributions, +bug reports and feedback. Because this money gives me the +time I need to handle the code contributions, bug reports +and feedback.</p></div> +<div class="paragraph"><p>If Cowboy or another project is a large part of your +product or infrastructure, then the best thing you can do +is become a sponsor. The second best is opening tickets +and/or providing feedback. The third best is providing +good code contributions.</p></div> +<div class="paragraph"><p>I will not expand on the feedback part. Feedback is +very important, and even just a high five or a retweet +is already good feedback. It’s not very complicated.</p></div> +<div class="paragraph"><p>I want to expand a little on code contributions +however. Not long ago I ran across the term "patch bomb" +which means dropping patches and expecting the project +maintainers to merge them and maintain them. I receive +a lot of patches, and often have to refuse them. Causes +for refusal vary. Some patches only benefit the people +who submitted them (or a very small number of people). +Some patches are not refined enough to be included. +Others are out of scope of the project. These are some +of the reasons why I refuse patches. Having limited +time and resources, I have to focus my efforts on the +code used by the larger number of users. I have to +prioritize patches from submitters who are reactive +and address the issues pointed out. And I have to plainly +refuse other patches.</p></div> +<div class="paragraph"><p>I believe this wraps up my thoughts on open source. +Overall I had a great experience, the Erlang community +being nice and understanding of the issues at hand in +general. And if the money problem could be solved soon, +then I would be one of the luckiest and happiest open +source developer on Earth.</p></div> +<div class="paragraph"><p>Think about it the next time you see a donation button +or a request for funds or sponsoring. You can considerably +improve an open source developer’s life with very little +of your company’s money.</p></div> </article> </div> @@ -199,55 +199,107 @@ of your company’s money.</p></div> <h3>More articles</h3> <ul id="articles-nav" class="extra_margin"> - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + - <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + + <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + - <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + + <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + - <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + + <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + - <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + + <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + - <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + + <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + - <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + + <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + - <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + + <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + - <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + + <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + - <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + + <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + - <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + + </ul> diff --git a/articles/page/1/index.html b/articles/page/1/index.html index 0e547dc4..edf636b5 100644 --- a/articles/page/1/index.html +++ b/articles/page/1/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/articles/</title><link rel="canonical" href="https://ninenines.eu/articles/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/articles/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/articles/</title><link rel="canonical" href="https://ninenines.eu/articles/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/articles/" /></head></html>
\ No newline at end of file diff --git a/articles/page/2/index.html b/articles/page/2/index.html index 6cb50477..75561425 100644 --- a/articles/page/2/index.html +++ b/articles/page/2/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Articles</title> @@ -79,9 +79,9 @@ </p> </header> - <p>We will be adding atomic integer expressions to our language.
These look as follow in Erlang: -
42.
And the result of this expression is of course 42. -
We will be running this expression at compile time, since we
don’t have the means to run code at runtime yet. This will of
course result in no module being compiled, but that’s OK, it will
allow us to discuss a few important things we’ll have to plan for
later on.</p> + <p>We will be adding atomic integer expressions to our language. These look as follow in Erlang: + 42. And the result of this expression is of course 42. + We will be running this expression at compile time, since we don’t have the means to run code at runtime yet. This will of course result in no module being compiled, but that’s OK, it will allow us to discuss a few important things we’ll have to plan for later on.</p> <p style="text-align:right"> <a class="read_more" href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Read More</a> @@ -98,10 +98,10 @@ </header> <p>Everything is an expression. -
This sentence carries profound meaning. We will invoke it many
times over the course of these articles. -
If everything is an expression, then the language shouldn’t have
any problem with me defining two modules in the same source file. -
mod first_module
begin
end
mod second_module
begin
end
Likewise, it shouldn’t have any problem with me defining a
module inside another module. -
mod out_module
begin
mod in_module
begin
end
end
Of course, in the context of the Erlang VM, these two snippets
are equivalent; there is nothing preventing you from calling the
in_module module from any other module.</p> + This sentence carries profound meaning. We will invoke it many times over the course of these articles. + If everything is an expression, then the language shouldn’t have any problem with me defining two modules in the same source file. + mod first_module begin end mod second_module begin end Likewise, it shouldn’t have any problem with me defining a module inside another module. + mod out_module begin mod in_module begin end end Of course, in the context of the Erlang VM, these two snippets are equivalent; there is nothing preventing you from calling the in_module module from any other module.</p> <p style="text-align:right"> <a class="read_more" href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Read More</a> @@ -117,9 +117,9 @@ </p> </header> - <p>Let’s build a programming language. I call it Xerl: eXtended ERLang.
It’ll be an occasion for us to learn a few things, especially me. -
Unlike in Erlang, in this language, everything is an expression.
This means that modules and functions are expression, and indeed that
you can have more than one module per file. -
We are just starting, so let’s no go ahead of ourselves here. We’ll
begin with writing the code allowing us to compile an empty module.</p> + <p>Let’s build a programming language. I call it Xerl: eXtended ERLang. It’ll be an occasion for us to learn a few things, especially me. + Unlike in Erlang, in this language, everything is an expression. This means that modules and functions are expression, and indeed that you can have more than one module per file. + We are just starting, so let’s no go ahead of ourselves here. We’ll begin with writing the code allowing us to compile an empty module.</p> <p style="text-align:right"> <a class="read_more" href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Read More</a> @@ -135,8 +135,8 @@ </p> </header> - <p>Last week I was speaking at the
London Erlang Factory Lite
where I presented a live demonstration of building an FTP server using
Ranch.
As there was no slide, you should use this article as a reference instead. -
The goal of this article is to showcase how to use Ranch for writing
a network protocol implementation, how Ranch gets out of the way to let
you write the code that matters, and the common techniques used when
writing servers.</p> + <p>Last week I was speaking at the London Erlang Factory Lite where I presented a live demonstration of building an FTP server using Ranch. As there was no slide, you should use this article as a reference instead. + The goal of this article is to showcase how to use Ranch for writing a network protocol implementation, how Ranch gets out of the way to let you write the code that matters, and the common techniques used when writing servers.</p> <p style="text-align:right"> <a class="read_more" href="https://ninenines.eu/articles/ranch-ftp/">Read More</a> @@ -152,10 +152,10 @@ </p> </header> - <p>Everyone knows Tic Tac Toe,
right? -
Players choose either to be the Xs or the Os, then place their symbol
on a 3x3 board one after another, trying to create a line of 3 of them. -
Writing an algorithm to check for victory sounds easy, right? It’s
easily tested, considering there’s only 8 possible winning rows (3 horizontal,
3 vertical and 2 diagonal). -
In Erlang though, you probably wouldn’t want an algorithm.</p> + <p>Everyone knows Tic Tac Toe, right? + Players choose either to be the Xs or the Os, then place their symbol on a 3x3 board one after another, trying to create a line of 3 of them. + Writing an algorithm to check for victory sounds easy, right? It’s easily tested, considering there’s only 8 possible winning rows (3 horizontal, 3 vertical and 2 diagonal). + In Erlang though, you probably wouldn’t want an algorithm.</p> <p style="text-align:right"> <a class="read_more" href="https://ninenines.eu/articles/tictactoe/">Read More</a> diff --git a/articles/ranch-1.3/index.html b/articles/ranch-1.3/index.html index 3364c077..db486dc5 100644 --- a/articles/ranch-1.3/index.html +++ b/articles/ranch-1.3/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Ranch 1.3</title> @@ -74,88 +74,88 @@ </p> </header> -<div class="paragraph"><p>Ranch <code>1.3.0</code> has been released!</p></div>
-<div class="paragraph"><p>This release fixes a number of long standing issues and adds
-a small number of features:</p></div>
-<div class="paragraph"><p>The <code>ssl</code> application has been added to the list of dependencies.
-If you don’t need it, you can remove it automatically when fetching
-Ranch or when building the release. If you do need it, you will no
-longer have issues shutting down a node because of Ranch.</p></div>
-<div class="paragraph"><p>The <code>ranch:info/0</code> and <code>ranch:procs/2</code> can be used to retrieve
-information about Ranch’s state. Use it for diagnostic and
-discovery purposes.</p></div>
-<div class="paragraph"><p>SSL listeners can now be configured without a certificate, for setups
-that make use of the SNI extension.</p></div>
-<div class="paragraph"><p>Transport options are now a blacklist, meaning all unknown options
-will be accepted. However Dialyzer will warn if said option is not
-defined in Ranch’s type specifications. Please send a patch when that
-happens!</p></div>
-<div class="paragraph"><p>Various bugs have been fixed, including the bug where the
-number of active connections could become negative. Common
-errors at listener startup should be easier to read (for
-example when the port is already in use).</p></div>
-<div class="paragraph"><p>See the <a href="https://git.ninenines.eu/ranch.git/plain/CHANGELOG.asciidoc">CHANGELOG</a>
-for more details.</p></div>
-<div class="paragraph"><p>Ranch is now tested and supported with Erlang/OTP R16B or above
-on Arch Linux, FreeBSD, OSX, Ubuntu and Windows 7. Contact me
-if you can provide permanent access to another platform for the
-purposes of testing.</p></div>
-<div class="paragraph"><p>Ranch is now available from four locations:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="https://git.ninenines.eu/ranch.git">https://git.ninenines.eu/ranch.git</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://github.com/ninenines/ranch.git">https://github.com/ninenines/ranch.git</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://bitbucket.org/ninenines/ranch.git">https://bitbucket.org/ninenines/ranch.git</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://gitlab.com/ninenines/ranch.git">https://gitlab.com/ninenines/ranch.git</a>
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>They are updated at the same time so there is no real difference.</p></div>
-<div class="paragraph"><p>The most recent Ranch commit is now always signed. You can import the
-<a href="https://pgp.mit.edu/pks/lookup?op=vindex&fingerprint=on&exact=on&search=0xF19F189CECC7439699CEDD7A6EF7A77066CCCC8A">signing key for Loïc Hoguin</a> with:</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>$ gpg --keyserver hkp<span style="color: #990000">:</span>//keys<span style="color: #990000">.</span>gnupg<span style="color: #990000">.</span>net --recv-key 66CCCC8A</tt></pre></div></div>
-<div class="paragraph"><p>The primary key fingerprint is <code>F19F 189C ECC7 4396 99CE DD7A 6EF7 A770 66CC CC8A</code>.</p></div>
-<div class="paragraph"><p>When verifying signatures in git, the following should appear:</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>gpg<span style="color: #990000">:</span> Signature made Sat <span style="color: #993399">26</span> Nov <span style="color: #993399">2016</span> <span style="color: #993399">12</span><span style="color: #990000">:</span><span style="color: #993399">58</span><span style="color: #990000">:</span><span style="color: #993399">35</span> PM CET
-gpg<span style="color: #990000">:</span> using RSA key 71366FF21851DF03
-gpg<span style="color: #990000">:</span> Good signature from <span style="color: #FF0000">"Loïc Hoguin <[email protected]>"</span> <span style="color: #990000">[</span>unknown<span style="color: #990000">]</span>
-gpg<span style="color: #990000">:</span> WARNING<span style="color: #990000">:</span> This key is not certified with a trusted signature<span style="color: #990000">!</span>
-gpg<span style="color: #990000">:</span> There is no indication that the signature belongs to the owner<span style="color: #990000">.</span>
-Primary key fingerprint<span style="color: #990000">:</span> F19F 189C ECC7 <span style="color: #993399">4396</span> 99CE DD7A 6EF7 A770 66CC CC8A
- Subkey fingerprint<span style="color: #990000">:</span> FEDA <span style="color: #993399">6E41</span> B390 F745 A385 5CDC <span style="color: #993399">7136</span> 6FF2 <span style="color: #993399">1851</span> DF03</tt></pre></div></div>
-<div class="paragraph"><p>You can safely ignore the warning if you don’t know what it
-means, as long as everything else is correct.</p></div>
-<div class="paragraph"><p>Mirrors and signature verification will soon be implemented
-directly in Erlang.mk. In the meantime, you will need to
-set them up manually.</p></div>
-<div class="paragraph"><p>Most of this work was done to fix issues in RabbitMQ. Paid
-customers get priority; contact me if you have some issues
-that need fixing sooner rather than later.</p></div>
-<div class="paragraph"><p>Expect future releases to be announced in this space.</p></div>
-<div class="paragraph"><p>Thanks for reading!</p></div>
+<div class="paragraph"><p>Ranch <code>1.3.0</code> has been released!</p></div> +<div class="paragraph"><p>This release fixes a number of long standing issues and adds +a small number of features:</p></div> +<div class="paragraph"><p>The <code>ssl</code> application has been added to the list of dependencies. +If you don’t need it, you can remove it automatically when fetching +Ranch or when building the release. If you do need it, you will no +longer have issues shutting down a node because of Ranch.</p></div> +<div class="paragraph"><p>The <code>ranch:info/0</code> and <code>ranch:procs/2</code> can be used to retrieve +information about Ranch’s state. Use it for diagnostic and +discovery purposes.</p></div> +<div class="paragraph"><p>SSL listeners can now be configured without a certificate, for setups +that make use of the SNI extension.</p></div> +<div class="paragraph"><p>Transport options are now a blacklist, meaning all unknown options +will be accepted. However Dialyzer will warn if said option is not +defined in Ranch’s type specifications. Please send a patch when that +happens!</p></div> +<div class="paragraph"><p>Various bugs have been fixed, including the bug where the +number of active connections could become negative. Common +errors at listener startup should be easier to read (for +example when the port is already in use).</p></div> +<div class="paragraph"><p>See the <a href="https://git.ninenines.eu/ranch.git/plain/CHANGELOG.asciidoc">CHANGELOG</a> +for more details.</p></div> +<div class="paragraph"><p>Ranch is now tested and supported with Erlang/OTP R16B or above +on Arch Linux, FreeBSD, OSX, Ubuntu and Windows 7. Contact me +if you can provide permanent access to another platform for the +purposes of testing.</p></div> +<div class="paragraph"><p>Ranch is now available from four locations:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="https://git.ninenines.eu/ranch.git">https://git.ninenines.eu/ranch.git</a> +</p> +</li> +<li> +<p> +<a href="https://github.com/ninenines/ranch.git">https://github.com/ninenines/ranch.git</a> +</p> +</li> +<li> +<p> +<a href="https://bitbucket.org/ninenines/ranch.git">https://bitbucket.org/ninenines/ranch.git</a> +</p> +</li> +<li> +<p> +<a href="https://gitlab.com/ninenines/ranch.git">https://gitlab.com/ninenines/ranch.git</a> +</p> +</li> +</ul></div> +<div class="paragraph"><p>They are updated at the same time so there is no real difference.</p></div> +<div class="paragraph"><p>The most recent Ranch commit is now always signed. You can import the +<a href="https://pgp.mit.edu/pks/lookup?op=vindex&fingerprint=on&exact=on&search=0xF19F189CECC7439699CEDD7A6EF7A77066CCCC8A">signing key for Loïc Hoguin</a> with:</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>$ gpg --keyserver hkp<span style="color: #990000">:</span>//keys<span style="color: #990000">.</span>gnupg<span style="color: #990000">.</span>net --recv-key 66CCCC8A</tt></pre></div></div> +<div class="paragraph"><p>The primary key fingerprint is <code>F19F 189C ECC7 4396 99CE DD7A 6EF7 A770 66CC CC8A</code>.</p></div> +<div class="paragraph"><p>When verifying signatures in git, the following should appear:</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>gpg<span style="color: #990000">:</span> Signature made Sat <span style="color: #993399">26</span> Nov <span style="color: #993399">2016</span> <span style="color: #993399">12</span><span style="color: #990000">:</span><span style="color: #993399">58</span><span style="color: #990000">:</span><span style="color: #993399">35</span> PM CET +gpg<span style="color: #990000">:</span> using RSA key 71366FF21851DF03 +gpg<span style="color: #990000">:</span> Good signature from <span style="color: #FF0000">"Loïc Hoguin <[email protected]>"</span> <span style="color: #990000">[</span>unknown<span style="color: #990000">]</span> +gpg<span style="color: #990000">:</span> WARNING<span style="color: #990000">:</span> This key is not certified with a trusted signature<span style="color: #990000">!</span> +gpg<span style="color: #990000">:</span> There is no indication that the signature belongs to the owner<span style="color: #990000">.</span> +Primary key fingerprint<span style="color: #990000">:</span> F19F 189C ECC7 <span style="color: #993399">4396</span> 99CE DD7A 6EF7 A770 66CC CC8A + Subkey fingerprint<span style="color: #990000">:</span> FEDA <span style="color: #993399">6E41</span> B390 F745 A385 5CDC <span style="color: #993399">7136</span> 6FF2 <span style="color: #993399">1851</span> DF03</tt></pre></div></div> +<div class="paragraph"><p>You can safely ignore the warning if you don’t know what it +means, as long as everything else is correct.</p></div> +<div class="paragraph"><p>Mirrors and signature verification will soon be implemented +directly in Erlang.mk. In the meantime, you will need to +set them up manually.</p></div> +<div class="paragraph"><p>Most of this work was done to fix issues in RabbitMQ. Paid +customers get priority; contact me if you have some issues +that need fixing sooner rather than later.</p></div> +<div class="paragraph"><p>Expect future releases to be announced in this space.</p></div> +<div class="paragraph"><p>Thanks for reading!</p></div> </article> </div> @@ -164,55 +164,107 @@ that need fixing sooner rather than later.</p></div> <h3>More articles</h3> <ul id="articles-nav" class="extra_margin"> - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + - <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + + <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + - <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + + <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + - <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + + <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + - <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + + <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + - <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + + <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + - <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + + <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + - <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + + <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + - <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + + <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + - <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + + <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + - <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + + </ul> diff --git a/articles/ranch-ftp/index.html b/articles/ranch-ftp/index.html index 727d4b1a..241750f0 100644 --- a/articles/ranch-ftp/index.html +++ b/articles/ranch-ftp/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Build an FTP Server with Ranch in 30 Minutes</title> @@ -74,216 +74,216 @@ </p> </header> -<div class="paragraph"><p>Last week I was speaking at the
-<a href="http://www.erlang-factory.com/conference/London2012/speakers/LoicHoguin">London Erlang Factory Lite</a>
-where I presented a live demonstration of building an FTP server using
-<a href="http://ninenines.eu/docs/en/ranch/HEAD/README">Ranch</a>.
-As there was no slide, you should use this article as a reference instead.</p></div>
-<div class="paragraph"><p>The goal of this article is to showcase how to use Ranch for writing
-a network protocol implementation, how Ranch gets out of the way to let
-you write the code that matters, and the common techniques used when
-writing servers.</p></div>
-<div class="paragraph"><p>Let’s start by creating an empty project. Create a new directory and
-then open a terminal into that directory. The first step is to add Ranch
-as a dependency. Create the <code>rebar.config</code> file and add the
-following 3 lines.</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">deps</span>, [
- {<span style="color: #FF6600">ranch</span>, <span style="color: #FF0000">".*"</span>, {<span style="color: #FF6600">git</span>, <span style="color: #FF0000">"git://github.com/extend/ranch.git"</span>, <span style="color: #FF0000">"master"</span>}}
-]}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>This makes your application depend on the last Ranch version available
-on the <em>master</em> branch. This is fine for development, however when
-you start pushing your application to production you will want to revisit
-this file to hardcode the exact version you are using, to make sure you
-run the same version of dependencies in production.</p></div>
-<div class="paragraph"><p>You can now fetch the dependencies.</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>$ rebar get-deps
-<span style="color: #990000">==></span> ranch_ftp <span style="color: #990000">(</span>get-deps<span style="color: #990000">)</span>
-Pulling ranch from {git<span style="color: #990000">,</span><span style="color: #FF0000">"git://github.com/extend/ranch.git"</span><span style="color: #990000">,</span><span style="color: #FF0000">"master"</span>}
-Cloning into <span style="color: #FF0000">'ranch'</span><span style="color: #990000">...</span>
-<span style="color: #990000">==></span> ranch <span style="color: #990000">(</span>get-deps<span style="color: #990000">)</span></tt></pre></div></div>
-<div class="paragraph"><p>This will create a <em>deps/</em> folder containing Ranch.</p></div>
-<div class="paragraph"><p>We don’t actually need anything else to write the protocol code.
-We could make an application for it, but this isn’t the purpose of this
-article so let’s just move on to writing the protocol itself. Create
-the file <em>ranch_ftp_protocol.erl</em> and open it in your favorite
-editor.</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>$ vim ranch_ftp_protocol<span style="color: #990000">.</span>erl</tt></pre></div></div>
-<div class="paragraph"><p>Let’s start with a blank protocol module.</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: #000080">-module</span></span>(<span style="color: #FF6600">ranch_ftp_protocol</span>)<span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">start_link</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>, <span style="font-weight: bold"><span style="color: #000000">init</span></span><span style="color: #990000">/</span><span style="color: #993399">3</span>])<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">start_link</span></span>(<span style="color: #009900">ListenerPid</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span>
- <span style="color: #009900">Pid</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000080">spawn_link</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, <span style="color: #FF6600">init</span>, [<span style="color: #009900">ListenerPid</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>]),
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Pid</span>}<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">ListenerPid</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"Got a connection!~n"</span>),
- <span style="color: #FF6600">ok</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>When Ranch receives a connection, it will call the <code>start_link/4</code>
-function with the listener’s pid, socket, transport module to be used,
-and the options we define when starting the listener. We don’t need options
-for the purpose of this article, so we don’t pass them to the process we are
-creating.</p></div>
-<div class="paragraph"><p>Let’s open a shell and start a Ranch listener to begin accepting
-connections. We only need to call one function. You should probably open
-it in another terminal and keep it open for convenience. If you quit
-the shell you will have to repeat the commands to proceed.</p></div>
-<div class="paragraph"><p>Also note that you need to type <code>c(ranch_ftp_protocol).</code>
-to recompile and reload the code for the protocol. You do not need to
-restart any process however.</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>$ erl -pa ebin deps<span style="color: #990000">/*</span>/ebin
-Erlang R15B02 <span style="color: #990000">(</span>erts-<span style="color: #993399">5.9</span><span style="color: #990000">.</span><span style="color: #993399">2</span><span style="color: #990000">)</span> <span style="color: #990000">[</span><span style="font-weight: bold"><span style="color: #0000FF">source</span></span><span style="color: #990000">]</span> <span style="color: #990000">[</span><span style="color: #993399">64</span>-bit<span style="color: #990000">]</span> <span style="color: #990000">[</span>smp<span style="color: #990000">:</span><span style="color: #993399">4</span><span style="color: #990000">:</span><span style="color: #993399">4</span><span style="color: #990000">]</span> <span style="color: #990000">[</span>async-threads<span style="color: #990000">:</span><span style="color: #993399">0</span><span style="color: #990000">]</span> <span style="color: #990000">[</span>hipe<span style="color: #990000">]</span> <span style="color: #990000">[</span>kernel-poll<span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #0000FF">false</span></span><span style="color: #990000">]</span>
-
-Eshell V5<span style="color: #990000">.</span><span style="color: #993399">9.2</span> <span style="color: #990000">(</span>abort with <span style="color: #990000">^</span>G<span style="color: #990000">)</span></tt></pre></div></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: #993399">1</span><span style="color: #990000">></span> <span style="font-weight: bold"><span style="color: #000000">application:start</span></span>(<span style="color: #FF6600">ranch</span>)<span style="color: #990000">.</span>
-<span style="color: #FF6600">ok</span>
-<span style="color: #993399">2</span><span style="color: #990000">></span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">my_ftp</span>, <span style="color: #993399">10</span>,
- <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">2121</span>}],
- <span style="color: #FF6600">ranch_ftp_protocol</span>, [])<span style="color: #990000">.</span>
-{<span style="color: #FF6600">ok</span>,<span style="color: #990000"><</span><span style="color: #993399">0.40</span><span style="color: #990000">.</span><span style="color: #993399">0</span><span style="color: #990000">></span>}</tt></pre></div></div>
-<div class="paragraph"><p>This starts a listener named <code>my_ftp</code> that runs your very own
-<code>ranch_ftp_protocol</code> over TCP, listening on port <code>2121</code>.
-The last argument is the options given to the protocol that we ignored
-earlier.</p></div>
-<div class="paragraph"><p>To try your code, you can use the following command. It should be able
-to connect, the server will print a message in the console, and then
-the client will print an error.</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>$ ftp localhost <span style="color: #993399">2121</span></tt></pre></div></div>
-<div class="paragraph"><p>Let’s move on to actually writing the protocol.</p></div>
-<div class="paragraph"><p>Once you have created the new process and returned the pid, Ranch will
-give ownership of the socket to you. This requires a synchronization
-step though.</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">ListenerPid</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>) <span style="color: #990000">-></span>
- <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">ListenerPid</span>),
- <span style="color: #FF6600">ok</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Now that you acknowledged the new connection, you can use it safely.</p></div>
-<div class="paragraph"><p>When an FTP server accepts a connection, it starts by sending a
-welcome message which can be one or more lines starting with the
-code <code>200</code>. Then the server will wait for the client
-to authenticate the user, and if the authentication went successfully,
-which it will always do for the purpose of this article, it will reply
-with a <code>230</code> 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="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">ListenerPid</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>) <span style="color: #990000">-></span>
- <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">ListenerPid</span>),
- <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"200 My cool FTP server welcomes you!\r\n"</span><span style="color: #990000">>></span>),
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">recv</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #993399">0</span>, <span style="color: #993399">30000</span>),
- <span style="font-weight: bold"><span style="color: #000000">auth</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Data</span>)<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">auth</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"USER "</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span><span style="color: #990000">>></span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"User authenticated! ~p~n"</span>, [<span style="color: #009900">Rest</span>]),
- <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"230 Auth OK\r\n"</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>As you can see we don’t need complex parsing code. We can simply
-match on the binary in the argument!</p></div>
-<div class="paragraph"><p>Next we need to loop receiving data commands and optionally
-execute them, if we want our server to become useful.</p></div>
-<div class="paragraph"><p>We will replace the <code>ok.</code> line with the call to
-the following function. The new function is recursive, each call
-receiving data from the socket and sending a response. For now
-we will send an error response for all commands the client sends.</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">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">recv</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #993399">0</span>, <span style="color: #993399">30000</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: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">handle</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Data</span>),
- <span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>);
- {<span style="color: #FF6600">error</span>, <span style="color: #990000">_</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"The client disconnected~n"</span>)
- <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">handle</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Data</span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"Command received ~p~n"</span>, [<span style="color: #009900">Data</span>]),
- <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"500 Bad command\r\n"</span><span style="color: #990000">>></span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>With this we are almost ready to start implementing commands.
-But with code like this we might have errors if the client doesn’t
-send just one command per packet, or if the packets arrive too fast,
-or if a command is split over multiple packets.</p></div>
-<div class="paragraph"><p>To solve this, we need to use a buffer. Each time we receive data,
-we will append to the buffer, and then check if we have received a
-command fully before running it. The code could look similar to the
-following.</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">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Buffer</span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">recv</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #993399">0</span>, <span style="color: #993399">30000</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: #990000">-></span>
- <span style="color: #009900">Buffer2</span> <span style="color: #990000">=</span> <span style="color: #990000"><<</span> <span style="color: #009900">Buffer</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Data</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span> <span style="color: #990000">>></span>,
- {<span style="color: #009900">Commands</span>, <span style="color: #009900">Rest</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">split</span></span>(<span style="color: #009900">Buffer2</span>),
- [<span style="font-weight: bold"><span style="color: #000000">handle</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">C</span>) || <span style="color: #009900">C</span> <span style="color: #990000"><-</span> <span style="color: #009900">Commands</span>],
- <span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Rest</span>);
- {<span style="color: #FF6600">error</span>, <span style="color: #990000">_</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"The client disconnected~n"</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>The implementation of <code>split/1</code> is left as an exercice
-to the reader. You will also probably want to handle the <code>QUIT</code>
-command, which must stop any processing and close the connection.</p></div>
-<div class="paragraph"><p>The attentive reader will also take note that in the case of text-
-based protocols where commands are separated by line breaks, you can
-set an option using <code>Transport:setopts/2</code> and have all the
-buffering done for you for free by Erlang itself.</p></div>
-<div class="paragraph"><p>As you can surely notice by now, Ranch allows us to build network
-applications by getting out of our way entirely past the initial setup.
-It lets you use the power of binary pattern matching to write text and
-binary protocol implementations in just a few lines of code.</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="http://www.erlang-factory.com/conference/London2012/speakers/LoicHoguin">Watch the talk</a>
-</p>
-</li>
-</ul></div>
+<div class="paragraph"><p>Last week I was speaking at the +<a href="http://www.erlang-factory.com/conference/London2012/speakers/LoicHoguin">London Erlang Factory Lite</a> +where I presented a live demonstration of building an FTP server using +<a href="http://ninenines.eu/docs/en/ranch/HEAD/README">Ranch</a>. +As there was no slide, you should use this article as a reference instead.</p></div> +<div class="paragraph"><p>The goal of this article is to showcase how to use Ranch for writing +a network protocol implementation, how Ranch gets out of the way to let +you write the code that matters, and the common techniques used when +writing servers.</p></div> +<div class="paragraph"><p>Let’s start by creating an empty project. Create a new directory and +then open a terminal into that directory. The first step is to add Ranch +as a dependency. Create the <code>rebar.config</code> file and add the +following 3 lines.</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">deps</span>, [ + {<span style="color: #FF6600">ranch</span>, <span style="color: #FF0000">".*"</span>, {<span style="color: #FF6600">git</span>, <span style="color: #FF0000">"git://github.com/extend/ranch.git"</span>, <span style="color: #FF0000">"master"</span>}} +]}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>This makes your application depend on the last Ranch version available +on the <em>master</em> branch. This is fine for development, however when +you start pushing your application to production you will want to revisit +this file to hardcode the exact version you are using, to make sure you +run the same version of dependencies in production.</p></div> +<div class="paragraph"><p>You can now fetch the dependencies.</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>$ rebar get-deps +<span style="color: #990000">==></span> ranch_ftp <span style="color: #990000">(</span>get-deps<span style="color: #990000">)</span> +Pulling ranch from {git<span style="color: #990000">,</span><span style="color: #FF0000">"git://github.com/extend/ranch.git"</span><span style="color: #990000">,</span><span style="color: #FF0000">"master"</span>} +Cloning into <span style="color: #FF0000">'ranch'</span><span style="color: #990000">...</span> +<span style="color: #990000">==></span> ranch <span style="color: #990000">(</span>get-deps<span style="color: #990000">)</span></tt></pre></div></div> +<div class="paragraph"><p>This will create a <em>deps/</em> folder containing Ranch.</p></div> +<div class="paragraph"><p>We don’t actually need anything else to write the protocol code. +We could make an application for it, but this isn’t the purpose of this +article so let’s just move on to writing the protocol itself. Create +the file <em>ranch_ftp_protocol.erl</em> and open it in your favorite +editor.</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>$ vim ranch_ftp_protocol<span style="color: #990000">.</span>erl</tt></pre></div></div> +<div class="paragraph"><p>Let’s start with a blank protocol module.</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: #000080">-module</span></span>(<span style="color: #FF6600">ranch_ftp_protocol</span>)<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">start_link</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>, <span style="font-weight: bold"><span style="color: #000000">init</span></span><span style="color: #990000">/</span><span style="color: #993399">3</span>])<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">start_link</span></span>(<span style="color: #009900">ListenerPid</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span> + <span style="color: #009900">Pid</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000080">spawn_link</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, <span style="color: #FF6600">init</span>, [<span style="color: #009900">ListenerPid</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>]), + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Pid</span>}<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">ListenerPid</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"Got a connection!~n"</span>), + <span style="color: #FF6600">ok</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>When Ranch receives a connection, it will call the <code>start_link/4</code> +function with the listener’s pid, socket, transport module to be used, +and the options we define when starting the listener. We don’t need options +for the purpose of this article, so we don’t pass them to the process we are +creating.</p></div> +<div class="paragraph"><p>Let’s open a shell and start a Ranch listener to begin accepting +connections. We only need to call one function. You should probably open +it in another terminal and keep it open for convenience. If you quit +the shell you will have to repeat the commands to proceed.</p></div> +<div class="paragraph"><p>Also note that you need to type <code>c(ranch_ftp_protocol).</code> +to recompile and reload the code for the protocol. You do not need to +restart any process however.</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>$ erl -pa ebin deps<span style="color: #990000">/*</span>/ebin +Erlang R15B02 <span style="color: #990000">(</span>erts-<span style="color: #993399">5.9</span><span style="color: #990000">.</span><span style="color: #993399">2</span><span style="color: #990000">)</span> <span style="color: #990000">[</span><span style="font-weight: bold"><span style="color: #0000FF">source</span></span><span style="color: #990000">]</span> <span style="color: #990000">[</span><span style="color: #993399">64</span>-bit<span style="color: #990000">]</span> <span style="color: #990000">[</span>smp<span style="color: #990000">:</span><span style="color: #993399">4</span><span style="color: #990000">:</span><span style="color: #993399">4</span><span style="color: #990000">]</span> <span style="color: #990000">[</span>async-threads<span style="color: #990000">:</span><span style="color: #993399">0</span><span style="color: #990000">]</span> <span style="color: #990000">[</span>hipe<span style="color: #990000">]</span> <span style="color: #990000">[</span>kernel-poll<span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #0000FF">false</span></span><span style="color: #990000">]</span> + +Eshell V5<span style="color: #990000">.</span><span style="color: #993399">9.2</span> <span style="color: #990000">(</span>abort with <span style="color: #990000">^</span>G<span style="color: #990000">)</span></tt></pre></div></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: #993399">1</span><span style="color: #990000">></span> <span style="font-weight: bold"><span style="color: #000000">application:start</span></span>(<span style="color: #FF6600">ranch</span>)<span style="color: #990000">.</span> +<span style="color: #FF6600">ok</span> +<span style="color: #993399">2</span><span style="color: #990000">></span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">my_ftp</span>, <span style="color: #993399">10</span>, + <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">2121</span>}], + <span style="color: #FF6600">ranch_ftp_protocol</span>, [])<span style="color: #990000">.</span> +{<span style="color: #FF6600">ok</span>,<span style="color: #990000"><</span><span style="color: #993399">0.40</span><span style="color: #990000">.</span><span style="color: #993399">0</span><span style="color: #990000">></span>}</tt></pre></div></div> +<div class="paragraph"><p>This starts a listener named <code>my_ftp</code> that runs your very own +<code>ranch_ftp_protocol</code> over TCP, listening on port <code>2121</code>. +The last argument is the options given to the protocol that we ignored +earlier.</p></div> +<div class="paragraph"><p>To try your code, you can use the following command. It should be able +to connect, the server will print a message in the console, and then +the client will print an error.</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>$ ftp localhost <span style="color: #993399">2121</span></tt></pre></div></div> +<div class="paragraph"><p>Let’s move on to actually writing the protocol.</p></div> +<div class="paragraph"><p>Once you have created the new process and returned the pid, Ranch will +give ownership of the socket to you. This requires a synchronization +step though.</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">ListenerPid</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>) <span style="color: #990000">-></span> + <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">ListenerPid</span>), + <span style="color: #FF6600">ok</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Now that you acknowledged the new connection, you can use it safely.</p></div> +<div class="paragraph"><p>When an FTP server accepts a connection, it starts by sending a +welcome message which can be one or more lines starting with the +code <code>200</code>. Then the server will wait for the client +to authenticate the user, and if the authentication went successfully, +which it will always do for the purpose of this article, it will reply +with a <code>230</code> 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="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">ListenerPid</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>) <span style="color: #990000">-></span> + <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">ListenerPid</span>), + <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"200 My cool FTP server welcomes you!\r\n"</span><span style="color: #990000">>></span>), + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">recv</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #993399">0</span>, <span style="color: #993399">30000</span>), + <span style="font-weight: bold"><span style="color: #000000">auth</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Data</span>)<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">auth</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"USER "</span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span><span style="color: #990000">>></span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"User authenticated! ~p~n"</span>, [<span style="color: #009900">Rest</span>]), + <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"230 Auth OK\r\n"</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>As you can see we don’t need complex parsing code. We can simply +match on the binary in the argument!</p></div> +<div class="paragraph"><p>Next we need to loop receiving data commands and optionally +execute them, if we want our server to become useful.</p></div> +<div class="paragraph"><p>We will replace the <code>ok.</code> line with the call to +the following function. The new function is recursive, each call +receiving data from the socket and sending a response. For now +we will send an error response for all commands the client sends.</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">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">recv</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #993399">0</span>, <span style="color: #993399">30000</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: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">handle</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Data</span>), + <span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>); + {<span style="color: #FF6600">error</span>, <span style="color: #990000">_</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"The client disconnected~n"</span>) + <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">handle</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Data</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"Command received ~p~n"</span>, [<span style="color: #009900">Data</span>]), + <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"500 Bad command\r\n"</span><span style="color: #990000">>></span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>With this we are almost ready to start implementing commands. +But with code like this we might have errors if the client doesn’t +send just one command per packet, or if the packets arrive too fast, +or if a command is split over multiple packets.</p></div> +<div class="paragraph"><p>To solve this, we need to use a buffer. Each time we receive data, +we will append to the buffer, and then check if we have received a +command fully before running it. The code could look similar to the +following.</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">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Buffer</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">recv</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #993399">0</span>, <span style="color: #993399">30000</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: #990000">-></span> + <span style="color: #009900">Buffer2</span> <span style="color: #990000">=</span> <span style="color: #990000"><<</span> <span style="color: #009900">Buffer</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Data</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span> <span style="color: #990000">>></span>, + {<span style="color: #009900">Commands</span>, <span style="color: #009900">Rest</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">split</span></span>(<span style="color: #009900">Buffer2</span>), + [<span style="font-weight: bold"><span style="color: #000000">handle</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">C</span>) || <span style="color: #009900">C</span> <span style="color: #990000"><-</span> <span style="color: #009900">Commands</span>], + <span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Rest</span>); + {<span style="color: #FF6600">error</span>, <span style="color: #990000">_</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"The client disconnected~n"</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>The implementation of <code>split/1</code> is left as an exercice +to the reader. You will also probably want to handle the <code>QUIT</code> +command, which must stop any processing and close the connection.</p></div> +<div class="paragraph"><p>The attentive reader will also take note that in the case of text- +based protocols where commands are separated by line breaks, you can +set an option using <code>Transport:setopts/2</code> and have all the +buffering done for you for free by Erlang itself.</p></div> +<div class="paragraph"><p>As you can surely notice by now, Ranch allows us to build network +applications by getting out of our way entirely past the initial setup. +It lets you use the power of binary pattern matching to write text and +binary protocol implementations in just a few lines of code.</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="http://www.erlang-factory.com/conference/London2012/speakers/LoicHoguin">Watch the talk</a> +</p> +</li> +</ul></div> </article> </div> @@ -292,55 +292,107 @@ binary protocol implementations in just a few lines of code.</p></div> <h3>More articles</h3> <ul id="articles-nav" class="extra_margin"> - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + + <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + - <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + + <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + - <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + + <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + - <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + + <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + - <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + + <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + - <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + + <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + - <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + + <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + - <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + + <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + - <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + + <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + - <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + + <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + - <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + </ul> diff --git a/articles/the-elephant-in-the-room/index.html b/articles/the-elephant-in-the-room/index.html index c9def49a..a445edfc 100644 --- a/articles/the-elephant-in-the-room/index.html +++ b/articles/the-elephant-in-the-room/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: The elephant in the room</title> @@ -74,139 +74,139 @@ </p> </header> -<div class="paragraph"><p>Have you ever tried telling someone why they should use
-Erlang? You boast the smaller code size, the auto healing
-mechanisms, the distribution and they seem really excited.
-They wonder why they never heard about Erlang before. And
-then you show them what the code looks like. All excitement
-goes away. The smiles disappear. Their face starts
-becoming really serious.</p></div>
-<div class="paragraph"><p>You lost them. You know you lost them. They comment on the
-syntax, or perhaps you do, already admitting defeat. It’s
-unlike anything they have ever used before. And they will
-most likely end up not using it.</p></div>
-<div class="paragraph"><p>What about people who already know what the syntax looks
-like? As soon as you mention Erlang, the topic of the syntax
-comes in. It’s like nothing else matters.</p></div>
-<div class="paragraph"><p>Perhaps the topic of syntax didn’t come up. But they’re
-still not going to try Erlang because of it.</p></div>
-<div class="paragraph"><p>You’re probably not having these kinds of interactions at
-Erlang conferences. This doesn’t happen with people who are
-already somewhat interested in, or need, the features that
-Erlang provides. With them the syntax is at worst a minor
-inconvenience.</p></div>
-<div class="paragraph"><p>This happens because most developers are familiar with
-syntaxes that look nothing like Erlang. To be clear, I
-include language features and other concepts like objects
-as part of "syntax" here. Familiarity is a very important
-factor to drive adoption.</p></div>
-<div class="paragraph"><p>You can see an example of that in the Elixir world, where
-the majority of people come from Ruby or already knew and
-liked Ruby. The 2016 survey tells us that 59% of Elixir
-developers were using Ruby primarily before. That’s in
-large part because of the syntax. They will deny it of
-course and find other reasons. And yet, we don’t see such
-a strong adoption of Erlang from Ruby developers, before
-or after Elixir appeared.</p></div>
-<div class="paragraph"><p>Side note: have you ever wondered why the Elixir community
-is, I quote, much friendlier than the Ruby community?
-Despite having much of the same people?</p></div>
-<div class="paragraph"><p>Before we continue, let me be clear. I love the Erlang
-syntax. It is simple and explicit. It is powerful, especially
-when dealing with binary data. It has very few quirks.
-It has little to no ambiguity. It’s great. Except for
-persuading people to use it.</p></div>
-<div class="paragraph"><p>Over the years I have been writing Erlang, I have seen
-very few people point out that the syntax slows down
-adoption. We have no problem with it, so why would others?
-At the same time, people coming to Erlang come to solve
-a real problem they’re having, so the syntax is fairly
-secondary. Even if they hate it at first, they know they
-can solve their problems despite the syntax.</p></div>
-<div class="paragraph"><p>You don’t build a popular product or language by solving
-people’s problems though. In general you end up solving
-some problems and creating new problems. No, you build
-a popular product by <strong>convincing people to use it</strong>. And
-you make them stay with your product by making them
-<strong>commit</strong> to using it.</p></div>
-<div class="paragraph"><p>Take MongoDB for example. It didn’t become popular by
-working, or even by being practical. It wasn’t performing
-its primary function and was losing people’s data. That
-didn’t stop it from becoming popular. Smart people would
-knowingly use a database that was losing data. Think about
-that for a minute.</p></div>
-<div class="paragraph"><p>MongoDB of course had a huge marketing machine, and they
-focused on that. They helped organize many meetups all
-over the world, complete with various swag items given
-for free, including a small handbook about MongoDB. All
-people had to do was show up.</p></div>
-<div class="paragraph"><p>They didn’t go tell people to look at all the weaknesses
-their product had. They focused on the strengths. On
-what would convince people to try it. They would go
-to meetups, discuss with others, commit to try it (or
-try it at meetups directly), and by doing so sell MongoDB
-to themselves.</p></div>
-<div class="paragraph"><p>How do we get people to meetups though? That’d be the
-first step: you need to <strong>catch their attention</strong>.
-I believe MongoDB did this using benchmark results.
-Ironic isn’t it? MongoDB gets fast benchmark results
-because they lose data, and this gets everyone to buy
-into the product.</p></div>
-<div class="paragraph"><p>The key points to remember about this are:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-catch people’s attention
-</p>
-</li>
-<li>
-<p>
-show your product’s strengths
-</p>
-</li>
-<li>
-<p>
-make people take a commitment
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Once they commit to something, you win. Everyone will not
-end up ultimately using your product of course, but it’s
-at the very least become a consideration. It’s on their
-mind. Their resolve will be stronger when they ultimately
-try it and inevitably run into issues.</p></div>
-<div class="paragraph"><p>Erlang’s syntax is a weakness. Almost nobody looks at the
-Erlang syntax and falls in love with it at first sight.
-No, it takes time to learn it and understand how good it
-is. You need to sell Erlang to people without showing
-the Erlang syntax. If you do show it, then you need to
-hide the parts that feel alien. Function calls are OK.
-Recursion, not so much. Maps are OK. Records, not.</p></div>
-<div class="paragraph"><p>Avoiding code is not always possible when you try
-to sell it, especially to developers. You can however
-prepare them to accept the alien syntax by admitting
-that the syntax is not perfect before you show it.
-You can do this while praising it at the same time.
-For example, "the syntax is a little out there, but
-it matches the concepts perfectly, it will all make
-sense when you start learning".</p></div>
-<div class="paragraph"><p>This might not be the best introduction. Someone will
-need to A/B test it to find the one that gives the
-best results. But that should give you ideas.</p></div>
-<div class="paragraph"><p>When something terrible happens, mentioning that this
-isn’t the end of the world <strong>before</strong> you tell others what
-happened will soften their reaction. When someone
-breaks your favorite item and cries over it calling
-themselves stupid, it’s harder to get mad at them,
-compared to the same event with no emotional reaction.</p></div>
-<div class="paragraph"><p>Our behavior is largely dependent on what’s at the
-top of our mind, so it’s up to you to take advantage
-of this to make your case in the best conditions.</p></div>
-<div class="paragraph"><p>Next time you try to make someone use Erlang, remember
-that you should aim for getting a spoken commitment
-out of them, if possible before you show the syntax.
-If that’s not possible, then prepare them to accept
-the flaws or the weirdness before they see them.</p></div>
+<div class="paragraph"><p>Have you ever tried telling someone why they should use +Erlang? You boast the smaller code size, the auto healing +mechanisms, the distribution and they seem really excited. +They wonder why they never heard about Erlang before. And +then you show them what the code looks like. All excitement +goes away. The smiles disappear. Their face starts +becoming really serious.</p></div> +<div class="paragraph"><p>You lost them. You know you lost them. They comment on the +syntax, or perhaps you do, already admitting defeat. It’s +unlike anything they have ever used before. And they will +most likely end up not using it.</p></div> +<div class="paragraph"><p>What about people who already know what the syntax looks +like? As soon as you mention Erlang, the topic of the syntax +comes in. It’s like nothing else matters.</p></div> +<div class="paragraph"><p>Perhaps the topic of syntax didn’t come up. But they’re +still not going to try Erlang because of it.</p></div> +<div class="paragraph"><p>You’re probably not having these kinds of interactions at +Erlang conferences. This doesn’t happen with people who are +already somewhat interested in, or need, the features that +Erlang provides. With them the syntax is at worst a minor +inconvenience.</p></div> +<div class="paragraph"><p>This happens because most developers are familiar with +syntaxes that look nothing like Erlang. To be clear, I +include language features and other concepts like objects +as part of "syntax" here. Familiarity is a very important +factor to drive adoption.</p></div> +<div class="paragraph"><p>You can see an example of that in the Elixir world, where +the majority of people come from Ruby or already knew and +liked Ruby. The 2016 survey tells us that 59% of Elixir +developers were using Ruby primarily before. That’s in +large part because of the syntax. They will deny it of +course and find other reasons. And yet, we don’t see such +a strong adoption of Erlang from Ruby developers, before +or after Elixir appeared.</p></div> +<div class="paragraph"><p>Side note: have you ever wondered why the Elixir community +is, I quote, much friendlier than the Ruby community? +Despite having much of the same people?</p></div> +<div class="paragraph"><p>Before we continue, let me be clear. I love the Erlang +syntax. It is simple and explicit. It is powerful, especially +when dealing with binary data. It has very few quirks. +It has little to no ambiguity. It’s great. Except for +persuading people to use it.</p></div> +<div class="paragraph"><p>Over the years I have been writing Erlang, I have seen +very few people point out that the syntax slows down +adoption. We have no problem with it, so why would others? +At the same time, people coming to Erlang come to solve +a real problem they’re having, so the syntax is fairly +secondary. Even if they hate it at first, they know they +can solve their problems despite the syntax.</p></div> +<div class="paragraph"><p>You don’t build a popular product or language by solving +people’s problems though. In general you end up solving +some problems and creating new problems. No, you build +a popular product by <strong>convincing people to use it</strong>. And +you make them stay with your product by making them +<strong>commit</strong> to using it.</p></div> +<div class="paragraph"><p>Take MongoDB for example. It didn’t become popular by +working, or even by being practical. It wasn’t performing +its primary function and was losing people’s data. That +didn’t stop it from becoming popular. Smart people would +knowingly use a database that was losing data. Think about +that for a minute.</p></div> +<div class="paragraph"><p>MongoDB of course had a huge marketing machine, and they +focused on that. They helped organize many meetups all +over the world, complete with various swag items given +for free, including a small handbook about MongoDB. All +people had to do was show up.</p></div> +<div class="paragraph"><p>They didn’t go tell people to look at all the weaknesses +their product had. They focused on the strengths. On +what would convince people to try it. They would go +to meetups, discuss with others, commit to try it (or +try it at meetups directly), and by doing so sell MongoDB +to themselves.</p></div> +<div class="paragraph"><p>How do we get people to meetups though? That’d be the +first step: you need to <strong>catch their attention</strong>. +I believe MongoDB did this using benchmark results. +Ironic isn’t it? MongoDB gets fast benchmark results +because they lose data, and this gets everyone to buy +into the product.</p></div> +<div class="paragraph"><p>The key points to remember about this are:</p></div> +<div class="ulist"><ul> +<li> +<p> +catch people’s attention +</p> +</li> +<li> +<p> +show your product’s strengths +</p> +</li> +<li> +<p> +make people take a commitment +</p> +</li> +</ul></div> +<div class="paragraph"><p>Once they commit to something, you win. Everyone will not +end up ultimately using your product of course, but it’s +at the very least become a consideration. It’s on their +mind. Their resolve will be stronger when they ultimately +try it and inevitably run into issues.</p></div> +<div class="paragraph"><p>Erlang’s syntax is a weakness. Almost nobody looks at the +Erlang syntax and falls in love with it at first sight. +No, it takes time to learn it and understand how good it +is. You need to sell Erlang to people without showing +the Erlang syntax. If you do show it, then you need to +hide the parts that feel alien. Function calls are OK. +Recursion, not so much. Maps are OK. Records, not.</p></div> +<div class="paragraph"><p>Avoiding code is not always possible when you try +to sell it, especially to developers. You can however +prepare them to accept the alien syntax by admitting +that the syntax is not perfect before you show it. +You can do this while praising it at the same time. +For example, "the syntax is a little out there, but +it matches the concepts perfectly, it will all make +sense when you start learning".</p></div> +<div class="paragraph"><p>This might not be the best introduction. Someone will +need to A/B test it to find the one that gives the +best results. But that should give you ideas.</p></div> +<div class="paragraph"><p>When something terrible happens, mentioning that this +isn’t the end of the world <strong>before</strong> you tell others what +happened will soften their reaction. When someone +breaks your favorite item and cries over it calling +themselves stupid, it’s harder to get mad at them, +compared to the same event with no emotional reaction.</p></div> +<div class="paragraph"><p>Our behavior is largely dependent on what’s at the +top of our mind, so it’s up to you to take advantage +of this to make your case in the best conditions.</p></div> +<div class="paragraph"><p>Next time you try to make someone use Erlang, remember +that you should aim for getting a spoken commitment +out of them, if possible before you show the syntax. +If that’s not possible, then prepare them to accept +the flaws or the weirdness before they see them.</p></div> </article> </div> @@ -215,55 +215,107 @@ the flaws or the weirdness before they see them.</p></div> <h3>More articles</h3> <ul id="articles-nav" class="extra_margin"> - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + - <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + + <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + - <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + + <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + - <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + + <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + - <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + + <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + - <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + + <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + - <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + + <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + - <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + + <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + - <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + + <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + - <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + + <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + - <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + + </ul> diff --git a/articles/the-story-so-far/index.html b/articles/the-story-so-far/index.html index 72936401..dc642a87 100644 --- a/articles/the-story-so-far/index.html +++ b/articles/the-story-so-far/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: The story so far</title> @@ -74,230 +74,230 @@ </p> </header> -<div class="paragraph"><p>As I am away from home with little to do (some call this
-a vacation) I wanted to reflect a little on the story so far,
-or how I arrived to Erlang and got to where I am now. The
-raw personal experience. It’ll be an article that’s more
-about social aspect, communities and marketing a project than
-technical considerations. As a period piece, it will also
-allow me to reflect on the evolution of Erlang in recent
-years.</p></div>
-<div class="paragraph"><p>Once upon a time-- Okay this isn’t a fairy tale. The story
-begins with a short chapter in 2010. The year 2010 started
-with a fairly major event in my life: the US servers for the
-online game I stopped playing a few months before, but was
-still involved with through its community, were closing. OMG!
-Someone found a way to log packets and started working on a
-private server; meanwhile the JP servers were still up. And
-that’s pretty much it.</p></div>
-<div class="paragraph"><p>Fast forward a few months and it became pretty clear that
-the private server was going nowhere considering all the drama
-surrounding it-- which is actually not unusual, but it was
-more entertaining than average and the technical abilities of
-people running the project were obviously lacking so I decided
-to obtain those logged packets and look at things myself. I
-didn’t want to do a private server yet, I only wanted to take
-a peek to see how things worked, and perhaps organize some
-effort to document the protocol.</p></div>
-<div class="paragraph"><p>There was 10GB of logs. I didn’t have an easy to use
-language to analyze them, and hex editors wouldn’t cut it for
-most purposes, so I had to look elsewhere. This was a good
-opportunity to start learning this PHP killer I read about
-before, which also happens to feature syntax for matching
-binaries, called Erlang. To be perfectly honest I wouldn’t
-have touched the logs if I didn’t have the added motivation
-to play with and learn a new language.</p></div>
-<div class="paragraph"><p>At the time it was pretty hard to learn Erlang. In my
-experience there was Joe’s book (which I always recommend
-first as I believe it is the best to learn the Erlang side
-of things; but falls a little short on OTP), and there was
-about 5 chapters of LYSE. There were a couple other books
-I never managed to get into (sorry guys), and there was also
-a few interesting blogs, some of which I can’t find anymore.
-Finally the #erlang IRC community was there but I was strictly
-lurking at the time.</p></div>
-<div class="paragraph"><p>What a difference compared to 4 years later! (That’s
-today, by the way!) Now we have more books than I can
-remember, tons of articles covering various aspects of the
-language and platform, many targeting beginners but a good
-number of them also about advanced topics. We even have a
-free online book, LYSE, with more than 30 chapters covering
-pretty much everything. Needless to say I never finished
-reading LYSE as it got written slower than I learnt.</p></div>
-<div class="paragraph"><p>Back to 2010. I wrote a parser for the logs, and
-aggregated those results into one CSV file per packet type
-so I could open them in Gnumeric and aggregate some more,
-but manually this time, and draw conclusions on the packet
-structures. That was pretty easy. Even for a beginner.
-Anyone can go from zero to that level in a day or two.
-Then, having mastered binary pattern matching, I wanted
-to learn some more Erlang, by making this aggregation
-faster. What I had done before worked, but I wasn’t going
-to wait forever to process everything sequentially. So I
-looked and found a project called <code>plists</code> (still exists,
-but not maintained AFAIK). I downloaded that project and
-replaced my <code>lists:</code> calls to <code>plists:</code>.
-Boom. In just a few minutes all logs were processed, and
-I had learnt something new.</p></div>
-<div class="paragraph"><p>It is particularly interesting to note that the lack of
-a package manager or index never bothered me. Neither before
-nor after learning Erlang. My experience with package
-managers was mostly related to Ubuntu, a little Perl and
-Python, and PHP’s Pear. Let’s just stay polite and say it
-was always a terrible experience. So searching on the Web
-didn’t feel awkward, because even if I used a tool or
-website I would have ended up doing a search or two anyway.
-This is in contrast to the package index feature in
-<a href="https://github.com/ninenines/erlang.mk">Erlang.mk</a>,
-which is meant to simplify specifying dependencies more
-than anything: <code>DEPS = cowboy</code>. It does not
-attempt to solve any other problem, and will only attempt
-to solve one extra problem in the near future, which is
-the discovery of packages. So expect some kind of website
-listing packages soon enough.</p></div>
-<div class="paragraph"><p>I want to use this parenthese to also point out that at
-the time there was a very small number of projects out there,
-at least compared to today. While you sometimes hear people
-complain about lack of certain libraries, it is so much
-better now than it was before! The situation improves very
-quickly, so much that it’s not going to be that big an issue
-soon enough.</p></div>
-<div class="paragraph"><p>Wanting to know more about that game’s protocol, in the
-year 2010, I ended up starting to write more Erlang code to
-simulate a server and use the server to query the client and
-see what was happening, documenting the packets and so on.
-This eventually lead to a larger project implementing more
-and more until people got their hopes up for a revival of
-the game, all the while the now competing original server
-project died in a stream of drama and technical incompetence.
-Of course, I ended up doing what any good Internet citizen
-would do, I crushed people’s hopes, but that’s not important
-to our story. The important part is that before giving up
-on this project, I not only learnt a good deal of Erlang
-and a little deal of OTP (which I did not touch until 6
-months after I started with Erlang; see the paragraph
-about learning material above), but I also had an intriguing
-idea pop into my mind for what would become my greatest
-success yet.</p></div>
-<div class="paragraph"><p>The giving up part was not easy. Having had financial
-difficulties all year 2010 and part of 2009, I resolved
-to travel back to Paris to try and make it. I ended up
-sleeping in offices for 6 months, being hosted by a shady
-person, and hearing my fair share of stories about
-the dark side of business. While there I also worked for
-another company with someone who would end up becoming
-another high profile Erlang developer. The situation
-slowly improved, I started taking part in the #erlang
-IRC discussions, giving up my status of lurker and, a
-few months into 2011, started working on the Apache killer
-project: Cowboy.</p></div>
-<div class="paragraph"><p>This is the part where I probably should get accused of
-racism and other fun things, but I never did. And I think
-that speaks lots about the Erlang community. In all my time
-writing Erlang code, I can count the number of conflicts I
-had with other people on a single hand. This is the nicest
-programming community I have ever seen, by far. And the
-humblest too. The Erlang community feels like Japan. And
-I love Japan. So I love the Erlang community. I can’t say
-this enough. This is something that stayed true for all
-my time using Erlang, and despite the rise of alternative
-languages that are not Japan the Erlang community has
-remained very Japan.</p></div>
-<div class="paragraph"><p>The first published version of Cowboy was written in
-two weeks. A little before those two weeks, during, and
-a while after, pretty much everything I said on the
-Internets was that Cowboy was going to be the greatest
-HTTP server ever, that the other servers were problematic
-(and just to be clear, Yaws was rarely if ever mentioned,
-due to being in a perceived different league of "full
-featured servers" while Cowboy was a "lightweight server"),
-and that Cowboy will be the best replacement to a Mochiweb
-or Misultin application. This, alongside a lot of time
-spent on IRC telling people to use Cowboy when they were
-asking for an HTTP server to use, probably made me sound
-very annoying. But it worked, and Cowboy started getting
-its first users, despite being only a few weeks old. Of
-course, as soon as I got my very first user, I started
-claiming Cowboy had "a lot of users".</p></div>
-<div class="paragraph"><p>Looking back today I would definitely find myself annoying,
-this wasn’t just an idle comment there. For about a year,
-maybe a little more, all I ever said was that Cowboy was
-the best. This probably made me a little dumber in the
-process (as if I wasn’t enough! I know). Being French, I
-sometimes would also say things quite abruptly. To stay
-polite, I probably sounded like an asshole. I learnt to
-stop being so French over time thankfully.</p></div>
-<div class="paragraph"><p>I think what was most important to Cowboy at the time,
-was three things. First, it felt fresh. It was new, had new
-ideas, tried to do things differently and followed "new" old
-best practices (the OTP way-- which was simply too obscure
-for most people at the time). Second, it had me spending
-all my time telling people to use it whenever they were
-looking for an HTTP server. Third, it had me helping people
-get started with it and guide them all the steps of the way.
-Mostly because it didn’t have a very good documentation, but
-still, hand holding does wonders.</p></div>
-<div class="paragraph"><p>To be able to help people every time they had a problem,
-I did not spend all my days reading IRC. Instead I simply
-made sure to be notified when someone said <code>cowboy</code>.
-The same way many people subscribe to alerts when their
-company is mentioned in the news. Nothing fancy.</p></div>
-<div class="paragraph"><p>Time went on, Cowboy grew, or as some like to say,
-completely destroyed the competition, and many people
-eventually moved from Mochiweb and Misultin to Cowboy.
-And then Roberto Ostinelli stopped Misultin development
-and told everyone to move to Cowboy. This is the most
-humble and selfless act I have ever seen in the programming
-sphere, and I only have one thing to say about it: GG.
-Thanks for the fish. He left me with the tasks of improving
-Cowboy examples, documentation and strongly believed that
-the Misultin interface was more user friendly out of all
-the servers. So I added many examples, as many lines of
-documentation as we have of code, and strongly believe
-that Cowboy 2.0 will be the most user friendly interface
-out of all servers. But only time will tell.</p></div>
-<div class="paragraph"><p>With the rise of the project and the rise in the number
-of users, my previous strategy (completely incidental, by
-the way, and definitely not a well thought out plan to
-become popular) stopped working. It was taking me too much
-time. The important aspects slowly drifted. If I wanted to
-support more users, I would have to spend less time with
-each individual user. This was actually a hard problem.
-You basically have to make people understand they can’t
-just come to you directly when they have a problem, they
-have to follow proper channels. It becomes less personal,
-and might be felt like you don’t care about them anymore.
-You have to hurt some people’s feelings at this point. It
-is quite unfortunate, and also quite difficult to do. There
-is some unwritten rule that says early adopters deserve
-more, but in the real world it never works like this. So
-I probably hurt some people’s feelings at some point. But
-that’s okay. Because even if you make sure to be as nice
-as possible when you tell people to go through proper
-channels from now on, some people will still get offended.
-There’s nothing you can do about it.</p></div>
-<div class="paragraph"><p>From that point onward the important points about the
-project was getting the documentation done, making sure
-people knew about the proper channels to get help and
-report issues, etc. Basically making myself less needed.
-This is quite a contrast with the first days, but I believe
-Cowboy made that transition successfully.</p></div>
-<div class="paragraph"><p>Not only did I win time by not having to hold hands with
-everyone all the time (not that I didn’t like it, but you
-know, the sweat), but I also won time thanks to the increased
-project popularity. Indeed, the more users you have, the more
-annoying guys there are to tell people to use your project
-and that it’s the best and everything. Which is great. At
-least, it’s great if you don’t pay too much attention to it.
-Sometimes people will give an advice that is, in your opinion,
-a bad advice. And that’s okay. Don’t intervene every time
-someone gives a bad advice, learn to let it go. People will
-figure it out. You learn by making mistakes, after all. Use
-this extra time to make sure other people don’t end up
-giving the same bad advice instead. Fix the code or the
-documentation that led to this mistake. Slowly improve the
-project and make sure it doesn’t happen again.</p></div>
-<div class="paragraph"><p>This is my story. So far, anyway.</p></div>
+<div class="paragraph"><p>As I am away from home with little to do (some call this +a vacation) I wanted to reflect a little on the story so far, +or how I arrived to Erlang and got to where I am now. The +raw personal experience. It’ll be an article that’s more +about social aspect, communities and marketing a project than +technical considerations. As a period piece, it will also +allow me to reflect on the evolution of Erlang in recent +years.</p></div> +<div class="paragraph"><p>Once upon a time-- Okay this isn’t a fairy tale. The story +begins with a short chapter in 2010. The year 2010 started +with a fairly major event in my life: the US servers for the +online game I stopped playing a few months before, but was +still involved with through its community, were closing. OMG! +Someone found a way to log packets and started working on a +private server; meanwhile the JP servers were still up. And +that’s pretty much it.</p></div> +<div class="paragraph"><p>Fast forward a few months and it became pretty clear that +the private server was going nowhere considering all the drama +surrounding it-- which is actually not unusual, but it was +more entertaining than average and the technical abilities of +people running the project were obviously lacking so I decided +to obtain those logged packets and look at things myself. I +didn’t want to do a private server yet, I only wanted to take +a peek to see how things worked, and perhaps organize some +effort to document the protocol.</p></div> +<div class="paragraph"><p>There was 10GB of logs. I didn’t have an easy to use +language to analyze them, and hex editors wouldn’t cut it for +most purposes, so I had to look elsewhere. This was a good +opportunity to start learning this PHP killer I read about +before, which also happens to feature syntax for matching +binaries, called Erlang. To be perfectly honest I wouldn’t +have touched the logs if I didn’t have the added motivation +to play with and learn a new language.</p></div> +<div class="paragraph"><p>At the time it was pretty hard to learn Erlang. In my +experience there was Joe’s book (which I always recommend +first as I believe it is the best to learn the Erlang side +of things; but falls a little short on OTP), and there was +about 5 chapters of LYSE. There were a couple other books +I never managed to get into (sorry guys), and there was also +a few interesting blogs, some of which I can’t find anymore. +Finally the #erlang IRC community was there but I was strictly +lurking at the time.</p></div> +<div class="paragraph"><p>What a difference compared to 4 years later! (That’s +today, by the way!) Now we have more books than I can +remember, tons of articles covering various aspects of the +language and platform, many targeting beginners but a good +number of them also about advanced topics. We even have a +free online book, LYSE, with more than 30 chapters covering +pretty much everything. Needless to say I never finished +reading LYSE as it got written slower than I learnt.</p></div> +<div class="paragraph"><p>Back to 2010. I wrote a parser for the logs, and +aggregated those results into one CSV file per packet type +so I could open them in Gnumeric and aggregate some more, +but manually this time, and draw conclusions on the packet +structures. That was pretty easy. Even for a beginner. +Anyone can go from zero to that level in a day or two. +Then, having mastered binary pattern matching, I wanted +to learn some more Erlang, by making this aggregation +faster. What I had done before worked, but I wasn’t going +to wait forever to process everything sequentially. So I +looked and found a project called <code>plists</code> (still exists, +but not maintained AFAIK). I downloaded that project and +replaced my <code>lists:</code> calls to <code>plists:</code>. +Boom. In just a few minutes all logs were processed, and +I had learnt something new.</p></div> +<div class="paragraph"><p>It is particularly interesting to note that the lack of +a package manager or index never bothered me. Neither before +nor after learning Erlang. My experience with package +managers was mostly related to Ubuntu, a little Perl and +Python, and PHP’s Pear. Let’s just stay polite and say it +was always a terrible experience. So searching on the Web +didn’t feel awkward, because even if I used a tool or +website I would have ended up doing a search or two anyway. +This is in contrast to the package index feature in +<a href="https://github.com/ninenines/erlang.mk">Erlang.mk</a>, +which is meant to simplify specifying dependencies more +than anything: <code>DEPS = cowboy</code>. It does not +attempt to solve any other problem, and will only attempt +to solve one extra problem in the near future, which is +the discovery of packages. So expect some kind of website +listing packages soon enough.</p></div> +<div class="paragraph"><p>I want to use this parenthese to also point out that at +the time there was a very small number of projects out there, +at least compared to today. While you sometimes hear people +complain about lack of certain libraries, it is so much +better now than it was before! The situation improves very +quickly, so much that it’s not going to be that big an issue +soon enough.</p></div> +<div class="paragraph"><p>Wanting to know more about that game’s protocol, in the +year 2010, I ended up starting to write more Erlang code to +simulate a server and use the server to query the client and +see what was happening, documenting the packets and so on. +This eventually lead to a larger project implementing more +and more until people got their hopes up for a revival of +the game, all the while the now competing original server +project died in a stream of drama and technical incompetence. +Of course, I ended up doing what any good Internet citizen +would do, I crushed people’s hopes, but that’s not important +to our story. The important part is that before giving up +on this project, I not only learnt a good deal of Erlang +and a little deal of OTP (which I did not touch until 6 +months after I started with Erlang; see the paragraph +about learning material above), but I also had an intriguing +idea pop into my mind for what would become my greatest +success yet.</p></div> +<div class="paragraph"><p>The giving up part was not easy. Having had financial +difficulties all year 2010 and part of 2009, I resolved +to travel back to Paris to try and make it. I ended up +sleeping in offices for 6 months, being hosted by a shady +person, and hearing my fair share of stories about +the dark side of business. While there I also worked for +another company with someone who would end up becoming +another high profile Erlang developer. The situation +slowly improved, I started taking part in the #erlang +IRC discussions, giving up my status of lurker and, a +few months into 2011, started working on the Apache killer +project: Cowboy.</p></div> +<div class="paragraph"><p>This is the part where I probably should get accused of +racism and other fun things, but I never did. And I think +that speaks lots about the Erlang community. In all my time +writing Erlang code, I can count the number of conflicts I +had with other people on a single hand. This is the nicest +programming community I have ever seen, by far. And the +humblest too. The Erlang community feels like Japan. And +I love Japan. So I love the Erlang community. I can’t say +this enough. This is something that stayed true for all +my time using Erlang, and despite the rise of alternative +languages that are not Japan the Erlang community has +remained very Japan.</p></div> +<div class="paragraph"><p>The first published version of Cowboy was written in +two weeks. A little before those two weeks, during, and +a while after, pretty much everything I said on the +Internets was that Cowboy was going to be the greatest +HTTP server ever, that the other servers were problematic +(and just to be clear, Yaws was rarely if ever mentioned, +due to being in a perceived different league of "full +featured servers" while Cowboy was a "lightweight server"), +and that Cowboy will be the best replacement to a Mochiweb +or Misultin application. This, alongside a lot of time +spent on IRC telling people to use Cowboy when they were +asking for an HTTP server to use, probably made me sound +very annoying. But it worked, and Cowboy started getting +its first users, despite being only a few weeks old. Of +course, as soon as I got my very first user, I started +claiming Cowboy had "a lot of users".</p></div> +<div class="paragraph"><p>Looking back today I would definitely find myself annoying, +this wasn’t just an idle comment there. For about a year, +maybe a little more, all I ever said was that Cowboy was +the best. This probably made me a little dumber in the +process (as if I wasn’t enough! I know). Being French, I +sometimes would also say things quite abruptly. To stay +polite, I probably sounded like an asshole. I learnt to +stop being so French over time thankfully.</p></div> +<div class="paragraph"><p>I think what was most important to Cowboy at the time, +was three things. First, it felt fresh. It was new, had new +ideas, tried to do things differently and followed "new" old +best practices (the OTP way-- which was simply too obscure +for most people at the time). Second, it had me spending +all my time telling people to use it whenever they were +looking for an HTTP server. Third, it had me helping people +get started with it and guide them all the steps of the way. +Mostly because it didn’t have a very good documentation, but +still, hand holding does wonders.</p></div> +<div class="paragraph"><p>To be able to help people every time they had a problem, +I did not spend all my days reading IRC. Instead I simply +made sure to be notified when someone said <code>cowboy</code>. +The same way many people subscribe to alerts when their +company is mentioned in the news. Nothing fancy.</p></div> +<div class="paragraph"><p>Time went on, Cowboy grew, or as some like to say, +completely destroyed the competition, and many people +eventually moved from Mochiweb and Misultin to Cowboy. +And then Roberto Ostinelli stopped Misultin development +and told everyone to move to Cowboy. This is the most +humble and selfless act I have ever seen in the programming +sphere, and I only have one thing to say about it: GG. +Thanks for the fish. He left me with the tasks of improving +Cowboy examples, documentation and strongly believed that +the Misultin interface was more user friendly out of all +the servers. So I added many examples, as many lines of +documentation as we have of code, and strongly believe +that Cowboy 2.0 will be the most user friendly interface +out of all servers. But only time will tell.</p></div> +<div class="paragraph"><p>With the rise of the project and the rise in the number +of users, my previous strategy (completely incidental, by +the way, and definitely not a well thought out plan to +become popular) stopped working. It was taking me too much +time. The important aspects slowly drifted. If I wanted to +support more users, I would have to spend less time with +each individual user. This was actually a hard problem. +You basically have to make people understand they can’t +just come to you directly when they have a problem, they +have to follow proper channels. It becomes less personal, +and might be felt like you don’t care about them anymore. +You have to hurt some people’s feelings at this point. It +is quite unfortunate, and also quite difficult to do. There +is some unwritten rule that says early adopters deserve +more, but in the real world it never works like this. So +I probably hurt some people’s feelings at some point. But +that’s okay. Because even if you make sure to be as nice +as possible when you tell people to go through proper +channels from now on, some people will still get offended. +There’s nothing you can do about it.</p></div> +<div class="paragraph"><p>From that point onward the important points about the +project was getting the documentation done, making sure +people knew about the proper channels to get help and +report issues, etc. Basically making myself less needed. +This is quite a contrast with the first days, but I believe +Cowboy made that transition successfully.</p></div> +<div class="paragraph"><p>Not only did I win time by not having to hold hands with +everyone all the time (not that I didn’t like it, but you +know, the sweat), but I also won time thanks to the increased +project popularity. Indeed, the more users you have, the more +annoying guys there are to tell people to use your project +and that it’s the best and everything. Which is great. At +least, it’s great if you don’t pay too much attention to it. +Sometimes people will give an advice that is, in your opinion, +a bad advice. And that’s okay. Don’t intervene every time +someone gives a bad advice, learn to let it go. People will +figure it out. You learn by making mistakes, after all. Use +this extra time to make sure other people don’t end up +giving the same bad advice instead. Fix the code or the +documentation that led to this mistake. Slowly improve the +project and make sure it doesn’t happen again.</p></div> +<div class="paragraph"><p>This is my story. So far, anyway.</p></div> </article> </div> @@ -306,55 +306,107 @@ project and make sure it doesn’t happen again.</p></div> <h3>More articles</h3> <ul id="articles-nav" class="extra_margin"> - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + - <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + + <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + - <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + + <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + - <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + + <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + - <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + + <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + - <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + + <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + - <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + + <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + - <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + + <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + - <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + + <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + - <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + + <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + - <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + + </ul> diff --git a/articles/tictactoe/index.html b/articles/tictactoe/index.html index e466f27d..15498ed7 100644 --- a/articles/tictactoe/index.html +++ b/articles/tictactoe/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Erlang Tic Tac Toe</title> @@ -74,89 +74,89 @@ </p> </header> -<div class="paragraph"><p>Everyone knows <a href="http://en.wikipedia.org/wiki/Tic-tac-toe">Tic Tac Toe</a>,
-right?</p></div>
-<div class="paragraph"><p>Players choose either to be the Xs or the Os, then place their symbol
-on a 3x3 board one after another, trying to create a line of 3 of them.</p></div>
-<div class="paragraph"><p>Writing an algorithm to check for victory sounds easy, right? It’s
-easily tested, considering there’s only 8 possible winning rows (3 horizontal,
-3 vertical and 2 diagonal).</p></div>
-<div class="paragraph"><p>In Erlang though, you probably wouldn’t want an algorithm. Erlang has
-this cool feature called pattern matching which will allow us to completely
-avoid writing the algorithm by instead letting us match directly on the
-solutions.</p></div>
-<div class="paragraph"><p>Let’s first create a board. A board is a list of 3 rows each containing
-3 columns. It can also be thought of as a tuple containing 9 elements.
-A tuple is easier to manipulate so this is what we are going to use.
-Each position can either contain an <code>x</code>, an <code>o</code>,
-or be <code>undefined</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="font-weight: bold"><span style="color: #000000">new</span></span>() <span style="color: #990000">-></span>
- {<span style="color: #000080">undefined</span>, <span style="color: #000080">undefined</span>, <span style="color: #000080">undefined</span>,
- <span style="color: #000080">undefined</span>, <span style="color: #000080">undefined</span>, <span style="color: #000080">undefined</span>,
- <span style="color: #000080">undefined</span>, <span style="color: #000080">undefined</span>, <span style="color: #000080">undefined</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Now that we have a board, if we want to play, we need a function that
-will allow players to, you know, actually play their moves. Rows and
-columns are numbered 1 to 3 so we need a little math to correctly
-deduce the element’s position.</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">play</span></span>(<span style="color: #009900">Who</span>, <span style="color: #009900">X</span>, <span style="color: #009900">Y</span>, <span style="color: #009900">Board</span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000080">setelement</span></span>((<span style="color: #009900">Y</span> <span style="color: #990000">-</span> <span style="color: #993399">1</span>) <span style="color: #990000">*</span> <span style="color: #993399">3</span> <span style="color: #990000">+</span> <span style="color: #009900">X</span>, <span style="color: #009900">Board</span>, <span style="color: #009900">Who</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>This function returns the board with the element modified. Of course,
-as you probably noticed, we aren’t checking that the arguments are correct,
-or that the element was already set. This is left as an exercise to the
-reader.</p></div>
-<div class="paragraph"><p>After playing the move, we need to check whether someone won. That’s
-where you’d write an algorithm, and that’s where I wouldn’t. Let’s just
-pattern match all of them!</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">check</span></span>(<span style="color: #009900">Board</span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="color: #009900">Board</span> <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- {<span style="color: #FF6600">x</span>, <span style="color: #FF6600">x</span>, <span style="color: #FF6600">x</span>,
- <span style="color: #990000">_</span>, <span style="color: #990000">_</span>, <span style="color: #990000">_</span>,
- <span style="color: #990000">_</span>, <span style="color: #990000">_</span>, <span style="color: #990000">_</span>} <span style="color: #990000">-></span> {<span style="color: #FF6600">victory</span>, <span style="color: #FF6600">x</span>};
-
- {<span style="color: #FF6600">x</span>, <span style="color: #990000">_</span>, <span style="color: #990000">_</span>,
- <span style="color: #990000">_</span>, <span style="color: #FF6600">x</span>, <span style="color: #990000">_</span>,
- <span style="color: #990000">_</span>, <span style="color: #990000">_</span>, <span style="color: #FF6600">x</span>} <span style="color: #990000">-></span> {<span style="color: #FF6600">victory</span>, <span style="color: #FF6600">x</span>};
-
- {<span style="color: #FF6600">x</span>, <span style="color: #990000">_</span>, <span style="color: #990000">_</span>,
- <span style="color: #FF6600">x</span>, <span style="color: #990000">_</span>, <span style="color: #990000">_</span>,
- <span style="color: #FF6600">x</span>, <span style="color: #990000">_</span>, <span style="color: #990000">_</span>} <span style="color: #990000">-></span> {<span style="color: #FF6600">victory</span>, <span style="color: #FF6600">x</span>};
-
- <span style="font-style: italic"><span style="color: #9A1900">%% [snip]</span></span>
-
- <span style="color: #990000">_</span> <span style="color: #990000">-></span> <span style="color: #FF6600">ok</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>Pattern matching allows us to simply <em>draw</em> the solutions
-directly inside our code, and if the board matches any of them, then we
-have a victory or a draw, otherwise the game can continue.</p></div>
-<div class="paragraph"><p>The <code>_</code> variable is special in that it always matches,
-allowing us to focus strictly on the winning row. And because it’s very
-graphical, if we were to have messed up somewhere, then we’d only need
-take a quick glance to be sure the winning solutions are the right ones.</p></div>
-<div class="paragraph"><p>Erlang allows us to transform algorithms into very graphical code thanks
-to its pattern matching feature, and let us focus on doing things instead
-of writing algorithms to do things.</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="/res/tictactoe.erl">tictactoe.erl</a>
-</p>
-</li>
-</ul></div>
+<div class="paragraph"><p>Everyone knows <a href="http://en.wikipedia.org/wiki/Tic-tac-toe">Tic Tac Toe</a>, +right?</p></div> +<div class="paragraph"><p>Players choose either to be the Xs or the Os, then place their symbol +on a 3x3 board one after another, trying to create a line of 3 of them.</p></div> +<div class="paragraph"><p>Writing an algorithm to check for victory sounds easy, right? It’s +easily tested, considering there’s only 8 possible winning rows (3 horizontal, +3 vertical and 2 diagonal).</p></div> +<div class="paragraph"><p>In Erlang though, you probably wouldn’t want an algorithm. Erlang has +this cool feature called pattern matching which will allow us to completely +avoid writing the algorithm by instead letting us match directly on the +solutions.</p></div> +<div class="paragraph"><p>Let’s first create a board. A board is a list of 3 rows each containing +3 columns. It can also be thought of as a tuple containing 9 elements. +A tuple is easier to manipulate so this is what we are going to use. +Each position can either contain an <code>x</code>, an <code>o</code>, +or be <code>undefined</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="font-weight: bold"><span style="color: #000000">new</span></span>() <span style="color: #990000">-></span> + {<span style="color: #000080">undefined</span>, <span style="color: #000080">undefined</span>, <span style="color: #000080">undefined</span>, + <span style="color: #000080">undefined</span>, <span style="color: #000080">undefined</span>, <span style="color: #000080">undefined</span>, + <span style="color: #000080">undefined</span>, <span style="color: #000080">undefined</span>, <span style="color: #000080">undefined</span>}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Now that we have a board, if we want to play, we need a function that +will allow players to, you know, actually play their moves. Rows and +columns are numbered 1 to 3 so we need a little math to correctly +deduce the element’s position.</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">play</span></span>(<span style="color: #009900">Who</span>, <span style="color: #009900">X</span>, <span style="color: #009900">Y</span>, <span style="color: #009900">Board</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000080">setelement</span></span>((<span style="color: #009900">Y</span> <span style="color: #990000">-</span> <span style="color: #993399">1</span>) <span style="color: #990000">*</span> <span style="color: #993399">3</span> <span style="color: #990000">+</span> <span style="color: #009900">X</span>, <span style="color: #009900">Board</span>, <span style="color: #009900">Who</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>This function returns the board with the element modified. Of course, +as you probably noticed, we aren’t checking that the arguments are correct, +or that the element was already set. This is left as an exercise to the +reader.</p></div> +<div class="paragraph"><p>After playing the move, we need to check whether someone won. That’s +where you’d write an algorithm, and that’s where I wouldn’t. Let’s just +pattern match all of them!</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">check</span></span>(<span style="color: #009900">Board</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="color: #009900">Board</span> <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + {<span style="color: #FF6600">x</span>, <span style="color: #FF6600">x</span>, <span style="color: #FF6600">x</span>, + <span style="color: #990000">_</span>, <span style="color: #990000">_</span>, <span style="color: #990000">_</span>, + <span style="color: #990000">_</span>, <span style="color: #990000">_</span>, <span style="color: #990000">_</span>} <span style="color: #990000">-></span> {<span style="color: #FF6600">victory</span>, <span style="color: #FF6600">x</span>}; + + {<span style="color: #FF6600">x</span>, <span style="color: #990000">_</span>, <span style="color: #990000">_</span>, + <span style="color: #990000">_</span>, <span style="color: #FF6600">x</span>, <span style="color: #990000">_</span>, + <span style="color: #990000">_</span>, <span style="color: #990000">_</span>, <span style="color: #FF6600">x</span>} <span style="color: #990000">-></span> {<span style="color: #FF6600">victory</span>, <span style="color: #FF6600">x</span>}; + + {<span style="color: #FF6600">x</span>, <span style="color: #990000">_</span>, <span style="color: #990000">_</span>, + <span style="color: #FF6600">x</span>, <span style="color: #990000">_</span>, <span style="color: #990000">_</span>, + <span style="color: #FF6600">x</span>, <span style="color: #990000">_</span>, <span style="color: #990000">_</span>} <span style="color: #990000">-></span> {<span style="color: #FF6600">victory</span>, <span style="color: #FF6600">x</span>}; + + <span style="font-style: italic"><span style="color: #9A1900">%% [snip]</span></span> + + <span style="color: #990000">_</span> <span style="color: #990000">-></span> <span style="color: #FF6600">ok</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>Pattern matching allows us to simply <em>draw</em> the solutions +directly inside our code, and if the board matches any of them, then we +have a victory or a draw, otherwise the game can continue.</p></div> +<div class="paragraph"><p>The <code>_</code> variable is special in that it always matches, +allowing us to focus strictly on the winning row. And because it’s very +graphical, if we were to have messed up somewhere, then we’d only need +take a quick glance to be sure the winning solutions are the right ones.</p></div> +<div class="paragraph"><p>Erlang allows us to transform algorithms into very graphical code thanks +to its pattern matching feature, and let us focus on doing things instead +of writing algorithms to do things.</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="/res/tictactoe.erl">tictactoe.erl</a> +</p> +</li> +</ul></div> </article> </div> @@ -165,55 +165,107 @@ of writing algorithms to do things.</p></div> <h3>More articles</h3> <ul id="articles-nav" class="extra_margin"> - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + + <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + - <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + + <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + - <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + + <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + - <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + + <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + - <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + + <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + - <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + + <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + - <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + + <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + - <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + + <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + - <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + + <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + - <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + + <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + - <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + </ul> diff --git a/articles/website-update/index.html b/articles/website-update/index.html index 8df1c432..b13c1402 100644 --- a/articles/website-update/index.html +++ b/articles/website-update/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Website update</title> @@ -74,63 +74,63 @@ </p> </header> -<div class="paragraph"><p>Last week-end I updated the Nine Nines website.</p></div>
-<div class="paragraph"><p>I switched to <a href="http://gohugo.io/">Hugo</a>. The site is
-now built from <a href="http://asciidoc.org/">Asciidoc</a>
-documents. You probably saw me switch to Asciidoc
-for documentation this past year. This is the
-natural conclusion to that story. The great thing
-is that with a little bit of Makefile magic I can
-just copy the documentation files into Hugo and
-poof, they appear on the website.</p></div>
-<div class="paragraph"><p>I am very happy with that new setup. I can now
-post my thoughts again. Woo! Expect regular posts
-from now on. I will try to replace my long series
-of tweets with posts.</p></div>
-<div class="paragraph"><p>The sections have been rearranged. There used to
-be a separate training section; now
-<a href="/services">all my services</a> are described in
-one page. I have also clarified my areas of
-expertise. There used to be confusion in the past,
-so now it should be clearer that I am not a
-distributed systems expert.</p></div>
-<div class="paragraph"><p>On that note, if you are looking for my
-services right now, I’m not available. I’ll have
-to work 7 days a week for a while. Try again in a
-couple months. More on that in a future post.</p></div>
-<div class="paragraph"><p>The <a href="/docs">documentation</a> becomes a first class
-citizen. Bullet and Cowlib don’t have proper
-documentation… yet. I have started working on the
-Cowlib documentation, and Bullet shouldn’t take too
-long. All these projects will be documented when
-Cowboy gets to 2.0, and will all be supported
-equally. Note that the Cowboy 1.0 documentation
-still has the old website templates and links.
-Don’t worry about it.</p></div>
-<div class="paragraph"><p>The mailing lists link has been removed. I did
-announce a few months back that mailing lists were
-going to go. They’re still up right now, but not
-for long. I am planning to put the archives
-read-only, link to them from a future post and
-be done with it. If you have a question, open a
-ticket on Github. Then I can just decide to leave
-the ticket open if I want to do improvements based
-on your feedback.</p></div>
-<div class="paragraph"><p>I have replaced most of the "we" by "I". I am
-a one-man company right now. Have been for a while.
-Doesn’t make sense to keep a facade. I want to be
-close to users, not put a barrier between us.</p></div>
-<div class="paragraph"><p>The RSS changed. The old link doesn’t work anymore.
-The new link is at <a href="/index.xml">/index.xml</a>,
-or <a href="/articles/index.xml">/articles/index.xml</a>
-if you only care about my posts. I guess that’s the
-one most people want.</p></div>
-<div class="paragraph"><p>I still have some tweaks to do, but it will take a
-while. My long term plan is to remove Bootstrap, use
-vanilla CSS and as little JS as possible. The reason
-for that is that it’s cheaper than upgrading libraries
-every few years. Life is too short to spend it
-upgrading JS libraries.</p></div>
+<div class="paragraph"><p>Last week-end I updated the Nine Nines website.</p></div> +<div class="paragraph"><p>I switched to <a href="http://gohugo.io/">Hugo</a>. The site is +now built from <a href="http://asciidoc.org/">Asciidoc</a> +documents. You probably saw me switch to Asciidoc +for documentation this past year. This is the +natural conclusion to that story. The great thing +is that with a little bit of Makefile magic I can +just copy the documentation files into Hugo and +poof, they appear on the website.</p></div> +<div class="paragraph"><p>I am very happy with that new setup. I can now +post my thoughts again. Woo! Expect regular posts +from now on. I will try to replace my long series +of tweets with posts.</p></div> +<div class="paragraph"><p>The sections have been rearranged. There used to +be a separate training section; now +<a href="/services">all my services</a> are described in +one page. I have also clarified my areas of +expertise. There used to be confusion in the past, +so now it should be clearer that I am not a +distributed systems expert.</p></div> +<div class="paragraph"><p>On that note, if you are looking for my +services right now, I’m not available. I’ll have +to work 7 days a week for a while. Try again in a +couple months. More on that in a future post.</p></div> +<div class="paragraph"><p>The <a href="/docs">documentation</a> becomes a first class +citizen. Bullet and Cowlib don’t have proper +documentation… yet. I have started working on the +Cowlib documentation, and Bullet shouldn’t take too +long. All these projects will be documented when +Cowboy gets to 2.0, and will all be supported +equally. Note that the Cowboy 1.0 documentation +still has the old website templates and links. +Don’t worry about it.</p></div> +<div class="paragraph"><p>The mailing lists link has been removed. I did +announce a few months back that mailing lists were +going to go. They’re still up right now, but not +for long. I am planning to put the archives +read-only, link to them from a future post and +be done with it. If you have a question, open a +ticket on Github. Then I can just decide to leave +the ticket open if I want to do improvements based +on your feedback.</p></div> +<div class="paragraph"><p>I have replaced most of the "we" by "I". I am +a one-man company right now. Have been for a while. +Doesn’t make sense to keep a facade. I want to be +close to users, not put a barrier between us.</p></div> +<div class="paragraph"><p>The RSS changed. The old link doesn’t work anymore. +The new link is at <a href="/index.xml">/index.xml</a>, +or <a href="/articles/index.xml">/articles/index.xml</a> +if you only care about my posts. I guess that’s the +one most people want.</p></div> +<div class="paragraph"><p>I still have some tweaks to do, but it will take a +while. My long term plan is to remove Bootstrap, use +vanilla CSS and as little JS as possible. The reason +for that is that it’s cheaper than upgrading libraries +every few years. Life is too short to spend it +upgrading JS libraries.</p></div> </article> </div> @@ -139,55 +139,107 @@ upgrading JS libraries.</p></div> <h3>More articles</h3> <ul id="articles-nav" class="extra_margin"> - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + - <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + + <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + - <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + + <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + - <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + + <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + - <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + + <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + - <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + + <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + - <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + + <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + - <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + + <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + - <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + + <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + - <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + + <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + - <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + + </ul> diff --git a/articles/xerl-0.1-empty-modules/index.html b/articles/xerl-0.1-empty-modules/index.html index 0a113770..c541ecdc 100644 --- a/articles/xerl-0.1-empty-modules/index.html +++ b/articles/xerl-0.1-empty-modules/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Xerl: empty modules</title> @@ -74,144 +74,144 @@ </p> </header> -<div class="paragraph"><p>Let’s build a programming language. I call it Xerl: eXtended ERLang.
-It’ll be an occasion for us to learn a few things, especially me.</p></div>
-<div class="paragraph"><p>Unlike in Erlang, in this language, everything is an expression.
-This means that modules and functions are expression, and indeed that
-you can have more than one module per file.</p></div>
-<div class="paragraph"><p>We are just starting, so let’s no go ahead of ourselves here. We’ll
-begin with writing the code allowing us to compile an empty module.</p></div>
-<div class="paragraph"><p>We will compile to Core Erlang: this is one of the many intermediate
-step your Erlang code compiles to before it becomes BEAM machine code.
-Core Erlang is a very neat language for machine generated code, and we
-will learn many things about it.</p></div>
-<div class="paragraph"><p>Today we will only focus on compiling the following 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: #FF6600">mod</span> <span style="color: #FF6600">my_module</span>
-<span style="font-weight: bold"><span style="color: #0000FF">begin</span></span>
-<span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
-<div class="paragraph"><p>Compilation will be done in a few steps. First, the source file will
-be transformed in a tree of tokens by the lexer. Then, the parser will
-use that tree of tokens and convert it to the AST, bringing semantical
-meaning to our representation. Finally, the code generator will transform
-this AST to Core Erlang AST, which will then be compiled.</p></div>
-<div class="paragraph"><p>We will use <em>leex</em> for the lexer. This lexer uses .xrl files
-which are then compiled to .erl files that you can then compile to BEAM.
-The file is divided in three parts: definitions, rules and Erlang code.
-Definitions and Erlang code are obvious; rules are what concerns us.</p></div>
-<div class="paragraph"><p>We only need two things: atoms and whitespaces. Atoms are a lowercase
-letter followed by any letter, number, _ or @. Whitespace is either a
-space, an horizontal tab, \r or \n. There exists other kinds of whitespaces
-but we simply do not allow them in the Xerl language.</p></div>
-<div class="paragraph"><p>Rules consist of a regular expression followed by Erlang code. The
-latter must return a token representation or the atom <code>skip_token</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">L</span>}{<span style="color: #009900">A</span>}<span style="color: #990000">*</span> <span style="color: #990000">:</span>
- <span style="color: #009900">Atom</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000080">list_to_atom</span></span>(<span style="color: #009900">TokenChars</span>),
- {<span style="color: #FF6600">token</span>, <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">reserved_word</span></span>(<span style="color: #009900">Atom</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">Atom</span>, <span style="color: #009900">TokenLine</span>};
- <span style="color: #000080">false</span> <span style="color: #990000">-></span> {<span style="font-weight: bold"><span style="color: #000080">atom</span></span>, <span style="color: #009900">TokenLine</span>, <span style="color: #009900">Atom</span>}
- <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>}<span style="color: #990000">.</span>
-
-{<span style="color: #009900">WS</span>}<span style="color: #990000">+</span> <span style="color: #990000">:</span> <span style="color: #FF6600">skip_token</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The first rule matches an atom, which is converted to either a special
-representation for reserved words, or an atom tuple. The
-<code>TokenChars</code> variable represents the match as a string, and
-the <code>TokenLine</code> variable contains the line number.
-<a href="https://github.com/extend/xerl/blob/0.1/src/xerl_lexer.xrl">View the complete file</a>.</p></div>
-<div class="paragraph"><p>We obtain the following result from the lexer:</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">mod</span>,<span style="color: #993399">1</span>},{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>,<span style="color: #993399">1</span>,<span style="color: #FF6600">my_module</span>},{<span style="color: #FF6600">'begin'</span>,<span style="color: #993399">2</span>},{<span style="color: #FF6600">'end'</span>,<span style="color: #993399">3</span>}]</tt></pre></div></div>
-<div class="paragraph"><p>The second step is to parse this list of tokens to add semantic meaning
-and generate what is called an <em>abstract syntax tree</em>. We will be
-using the <em>yecc</em> parser generator for this. This time it will take
-.yrl files but the process is the same as before. The file is a little
-more complex than for the lexer, we need to define at the very least
-terminals, nonterminals and root symbols, the grammar itself, and
-optionally some Erlang code.</p></div>
-<div class="paragraph"><p>To compile our module, we need a few things. First, everything is an
-expression. We thus need list of expressions and individual expressions.
-We will support a single expression for now, the <code>mod</code>
-expression which defines a module. And that’s it! We end up with the
-following grammar:</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">exprs</span> <span style="color: #990000">-></span> <span style="color: #FF6600">expr</span> <span style="color: #990000">:</span> [<span style="color: #FF6600">'$1'</span>]<span style="color: #990000">.</span>
-<span style="color: #FF6600">exprs</span> <span style="color: #990000">-></span> <span style="color: #FF6600">expr</span> <span style="color: #FF6600">exprs</span> <span style="color: #990000">:</span> [<span style="color: #FF6600">'$1'</span> | <span style="color: #FF6600">'$2'</span>]<span style="color: #990000">.</span>
-
-<span style="color: #FF6600">expr</span> <span style="color: #990000">-></span> <span style="color: #FF6600">module</span> <span style="color: #990000">:</span> <span style="color: #FF6600">'$1'</span><span style="color: #990000">.</span>
-
-<span style="color: #FF6600">module</span> <span style="color: #990000">-></span> <span style="color: #FF6600">'mod'</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span> <span style="color: #FF6600">'begin'</span> <span style="color: #FF6600">'end'</span> <span style="color: #990000">:</span>
- {<span style="color: #FF6600">'mod'</span>, <span style="font-weight: bold"><span style="color: #000080">?line</span></span>(<span style="color: #FF6600">'$1'</span>), <span style="color: #FF6600">'$2'</span>, []}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p><a href="https://github.com/extend/xerl/blob/0.1/src/xerl_parser.yrl">View the complete file</a>.</p></div>
-<div class="paragraph"><p>We obtain the following result from the parser:</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">mod</span>,<span style="color: #993399">1</span>,{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>,<span style="color: #993399">1</span>,<span style="color: #FF6600">my_module</span>},[]}]</tt></pre></div></div>
-<div class="paragraph"><p>We obtain a list of a single <code>mod</code> expression. Just like
-we wanted. Last step is generating the Core Erlang code from it.</p></div>
-<div class="paragraph"><p>Code generation generally is comprised of several steps. We will
-discuss these in more details later on. For now, we will focus on the
-minimal needed for successful compilation.</p></div>
-<div class="paragraph"><p>We can use the <code>cerl</code> module to generate Core Erlang AST.
-We will simply be using functions, which allows us to avoid learning
-and keeping up to date with the internal representation.</p></div>
-<div class="paragraph"><p>There’s one important thing to do when generating Core Erlang AST
-for a module: create the <code>module_info/{0,1}</code> functions.
-Indeed, these are added to Erlang before it becomes Core Erlang, and
-so we need to replicate this ourselves. Do not be concerned however,
-as this only takes a few lines of extra code.</p></div>
-<div class="paragraph"><p>As you can see by
-<a href="https://github.com/extend/xerl/blob/0.1/src/xerl_codegen.erl">looking at the complete file</a>,
-the code generator echoes the grammar we defined in the parser, and
-simply applies the appropriate Core Erlang functions for each expressions.</p></div>
-<div class="paragraph"><p>We obtain the following pretty-printed Core Erlang generated 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: #FF6600">module</span> <span style="color: #FF6600">'my_module'</span> [<span style="color: #FF6600">'module_info'</span><span style="color: #990000">/</span><span style="color: #993399">0</span>,
- <span style="color: #FF6600">'module_info'</span><span style="color: #990000">/</span><span style="color: #993399">1</span>]
- <span style="color: #FF6600">attributes</span> []
-<span style="color: #FF6600">'module_info'</span><span style="color: #990000">/</span><span style="color: #993399">0</span> <span style="color: #990000">=</span>
- <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span> () <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000080">call</span></span> <span style="color: #FF6600">'erlang'</span><span style="color: #990000">:</span><span style="color: #FF6600">'get_module_info'</span>
- (<span style="color: #FF6600">'empty_module'</span>)
-<span style="color: #FF6600">'module_info'</span><span style="color: #990000">/</span><span style="color: #993399">1</span> <span style="color: #990000">=</span>
- <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span> (<span style="color: #009900">Key</span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000080">call</span></span> <span style="color: #FF6600">'erlang'</span><span style="color: #990000">:</span><span style="color: #FF6600">'get_module_info'</span>
- (<span style="color: #FF6600">'empty_module'</span>, <span style="color: #009900">Key</span>)
-<span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
-<div class="paragraph"><p>For convenience I added all the steps in a <code>xerl:compile/1</code>
-function that you can use against your own .xerl files.</p></div>
-<div class="paragraph"><p>That’s it for today! We will go into more details over each steps in
-the next few articles.</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="https://github.com/extend/xerl/blob/0.1/">View the source</a>
-</p>
-</li>
-</ul></div>
+<div class="paragraph"><p>Let’s build a programming language. I call it Xerl: eXtended ERLang. +It’ll be an occasion for us to learn a few things, especially me.</p></div> +<div class="paragraph"><p>Unlike in Erlang, in this language, everything is an expression. +This means that modules and functions are expression, and indeed that +you can have more than one module per file.</p></div> +<div class="paragraph"><p>We are just starting, so let’s no go ahead of ourselves here. We’ll +begin with writing the code allowing us to compile an empty module.</p></div> +<div class="paragraph"><p>We will compile to Core Erlang: this is one of the many intermediate +step your Erlang code compiles to before it becomes BEAM machine code. +Core Erlang is a very neat language for machine generated code, and we +will learn many things about it.</p></div> +<div class="paragraph"><p>Today we will only focus on compiling the following 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: #FF6600">mod</span> <span style="color: #FF6600">my_module</span> +<span style="font-weight: bold"><span style="color: #0000FF">begin</span></span> +<span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div> +<div class="paragraph"><p>Compilation will be done in a few steps. First, the source file will +be transformed in a tree of tokens by the lexer. Then, the parser will +use that tree of tokens and convert it to the AST, bringing semantical +meaning to our representation. Finally, the code generator will transform +this AST to Core Erlang AST, which will then be compiled.</p></div> +<div class="paragraph"><p>We will use <em>leex</em> for the lexer. This lexer uses .xrl files +which are then compiled to .erl files that you can then compile to BEAM. +The file is divided in three parts: definitions, rules and Erlang code. +Definitions and Erlang code are obvious; rules are what concerns us.</p></div> +<div class="paragraph"><p>We only need two things: atoms and whitespaces. Atoms are a lowercase +letter followed by any letter, number, _ or @. Whitespace is either a +space, an horizontal tab, \r or \n. There exists other kinds of whitespaces +but we simply do not allow them in the Xerl language.</p></div> +<div class="paragraph"><p>Rules consist of a regular expression followed by Erlang code. The +latter must return a token representation or the atom <code>skip_token</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">L</span>}{<span style="color: #009900">A</span>}<span style="color: #990000">*</span> <span style="color: #990000">:</span> + <span style="color: #009900">Atom</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000080">list_to_atom</span></span>(<span style="color: #009900">TokenChars</span>), + {<span style="color: #FF6600">token</span>, <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">reserved_word</span></span>(<span style="color: #009900">Atom</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">Atom</span>, <span style="color: #009900">TokenLine</span>}; + <span style="color: #000080">false</span> <span style="color: #990000">-></span> {<span style="font-weight: bold"><span style="color: #000080">atom</span></span>, <span style="color: #009900">TokenLine</span>, <span style="color: #009900">Atom</span>} + <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>}<span style="color: #990000">.</span> + +{<span style="color: #009900">WS</span>}<span style="color: #990000">+</span> <span style="color: #990000">:</span> <span style="color: #FF6600">skip_token</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The first rule matches an atom, which is converted to either a special +representation for reserved words, or an atom tuple. The +<code>TokenChars</code> variable represents the match as a string, and +the <code>TokenLine</code> variable contains the line number. +<a href="https://github.com/extend/xerl/blob/0.1/src/xerl_lexer.xrl">View the complete file</a>.</p></div> +<div class="paragraph"><p>We obtain the following result from the lexer:</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">mod</span>,<span style="color: #993399">1</span>},{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>,<span style="color: #993399">1</span>,<span style="color: #FF6600">my_module</span>},{<span style="color: #FF6600">'begin'</span>,<span style="color: #993399">2</span>},{<span style="color: #FF6600">'end'</span>,<span style="color: #993399">3</span>}]</tt></pre></div></div> +<div class="paragraph"><p>The second step is to parse this list of tokens to add semantic meaning +and generate what is called an <em>abstract syntax tree</em>. We will be +using the <em>yecc</em> parser generator for this. This time it will take +.yrl files but the process is the same as before. The file is a little +more complex than for the lexer, we need to define at the very least +terminals, nonterminals and root symbols, the grammar itself, and +optionally some Erlang code.</p></div> +<div class="paragraph"><p>To compile our module, we need a few things. First, everything is an +expression. We thus need list of expressions and individual expressions. +We will support a single expression for now, the <code>mod</code> +expression which defines a module. And that’s it! We end up with the +following grammar:</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">exprs</span> <span style="color: #990000">-></span> <span style="color: #FF6600">expr</span> <span style="color: #990000">:</span> [<span style="color: #FF6600">'$1'</span>]<span style="color: #990000">.</span> +<span style="color: #FF6600">exprs</span> <span style="color: #990000">-></span> <span style="color: #FF6600">expr</span> <span style="color: #FF6600">exprs</span> <span style="color: #990000">:</span> [<span style="color: #FF6600">'$1'</span> | <span style="color: #FF6600">'$2'</span>]<span style="color: #990000">.</span> + +<span style="color: #FF6600">expr</span> <span style="color: #990000">-></span> <span style="color: #FF6600">module</span> <span style="color: #990000">:</span> <span style="color: #FF6600">'$1'</span><span style="color: #990000">.</span> + +<span style="color: #FF6600">module</span> <span style="color: #990000">-></span> <span style="color: #FF6600">'mod'</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span> <span style="color: #FF6600">'begin'</span> <span style="color: #FF6600">'end'</span> <span style="color: #990000">:</span> + {<span style="color: #FF6600">'mod'</span>, <span style="font-weight: bold"><span style="color: #000080">?line</span></span>(<span style="color: #FF6600">'$1'</span>), <span style="color: #FF6600">'$2'</span>, []}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p><a href="https://github.com/extend/xerl/blob/0.1/src/xerl_parser.yrl">View the complete file</a>.</p></div> +<div class="paragraph"><p>We obtain the following result from the parser:</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">mod</span>,<span style="color: #993399">1</span>,{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>,<span style="color: #993399">1</span>,<span style="color: #FF6600">my_module</span>},[]}]</tt></pre></div></div> +<div class="paragraph"><p>We obtain a list of a single <code>mod</code> expression. Just like +we wanted. Last step is generating the Core Erlang code from it.</p></div> +<div class="paragraph"><p>Code generation generally is comprised of several steps. We will +discuss these in more details later on. For now, we will focus on the +minimal needed for successful compilation.</p></div> +<div class="paragraph"><p>We can use the <code>cerl</code> module to generate Core Erlang AST. +We will simply be using functions, which allows us to avoid learning +and keeping up to date with the internal representation.</p></div> +<div class="paragraph"><p>There’s one important thing to do when generating Core Erlang AST +for a module: create the <code>module_info/{0,1}</code> functions. +Indeed, these are added to Erlang before it becomes Core Erlang, and +so we need to replicate this ourselves. Do not be concerned however, +as this only takes a few lines of extra code.</p></div> +<div class="paragraph"><p>As you can see by +<a href="https://github.com/extend/xerl/blob/0.1/src/xerl_codegen.erl">looking at the complete file</a>, +the code generator echoes the grammar we defined in the parser, and +simply applies the appropriate Core Erlang functions for each expressions.</p></div> +<div class="paragraph"><p>We obtain the following pretty-printed Core Erlang generated 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: #FF6600">module</span> <span style="color: #FF6600">'my_module'</span> [<span style="color: #FF6600">'module_info'</span><span style="color: #990000">/</span><span style="color: #993399">0</span>, + <span style="color: #FF6600">'module_info'</span><span style="color: #990000">/</span><span style="color: #993399">1</span>] + <span style="color: #FF6600">attributes</span> [] +<span style="color: #FF6600">'module_info'</span><span style="color: #990000">/</span><span style="color: #993399">0</span> <span style="color: #990000">=</span> + <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span> () <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000080">call</span></span> <span style="color: #FF6600">'erlang'</span><span style="color: #990000">:</span><span style="color: #FF6600">'get_module_info'</span> + (<span style="color: #FF6600">'empty_module'</span>) +<span style="color: #FF6600">'module_info'</span><span style="color: #990000">/</span><span style="color: #993399">1</span> <span style="color: #990000">=</span> + <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span> (<span style="color: #009900">Key</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000080">call</span></span> <span style="color: #FF6600">'erlang'</span><span style="color: #990000">:</span><span style="color: #FF6600">'get_module_info'</span> + (<span style="color: #FF6600">'empty_module'</span>, <span style="color: #009900">Key</span>) +<span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div> +<div class="paragraph"><p>For convenience I added all the steps in a <code>xerl:compile/1</code> +function that you can use against your own .xerl files.</p></div> +<div class="paragraph"><p>That’s it for today! We will go into more details over each steps in +the next few articles.</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="https://github.com/extend/xerl/blob/0.1/">View the source</a> +</p> +</li> +</ul></div> </article> </div> @@ -220,55 +220,107 @@ the next few articles.</p></div> <h3>More articles</h3> <ul id="articles-nav" class="extra_margin"> - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + + <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + - <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + + <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + - <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + + <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + - <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + + <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + - <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + + <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + - <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + + <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + - <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + + <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + - <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + + <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + - <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + + <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + - <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + + <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + - <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + </ul> diff --git a/articles/xerl-0.2-two-modules/index.html b/articles/xerl-0.2-two-modules/index.html index 632248a0..279aaa23 100644 --- a/articles/xerl-0.2-two-modules/index.html +++ b/articles/xerl-0.2-two-modules/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Xerl: two modules</title> @@ -74,149 +74,149 @@ </p> </header> -<div class="paragraph"><p>Everything is an expression.</p></div>
-<div class="paragraph"><p>This sentence carries profound meaning. We will invoke it many
-times over the course of these articles.</p></div>
-<div class="paragraph"><p>If everything is an expression, then the language shouldn’t have
-any problem with me defining two modules in the same source 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: #FF6600">mod</span> <span style="color: #FF6600">first_module</span>
-<span style="font-weight: bold"><span style="color: #0000FF">begin</span></span>
-<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
-
-<span style="color: #FF6600">mod</span> <span style="color: #FF6600">second_module</span>
-<span style="font-weight: bold"><span style="color: #0000FF">begin</span></span>
-<span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
-<div class="paragraph"><p>Likewise, it shouldn’t have any problem with me defining a
-module inside another module.</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">mod</span> <span style="color: #FF6600">out_module</span>
-<span style="font-weight: bold"><span style="color: #0000FF">begin</span></span>
- <span style="color: #FF6600">mod</span> <span style="color: #FF6600">in_module</span>
- <span style="font-weight: bold"><span style="color: #0000FF">begin</span></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></tt></pre></div></div>
-<div class="paragraph"><p>Of course, in the context of the Erlang VM, these two snippets
-are equivalent; there is nothing preventing you from calling the
-<code>in_module</code> module from any other module. The <code>mod</code>
-instruction means a module should be created in the Erlang VM,
-with no concept of scope attached.</p></div>
-<div class="paragraph"><p>Still we need to handle both. To do this we will add a step
-between the parser and the code generator that will walk over the
-abstract syntax tree, from here onward shortened as <em>AST</em>,
-and transform the AST by executing it where applicable.</p></div>
-<div class="paragraph"><p>What happens when you execute a <code>mod</code> instruction?
-A module is created. Since we are compiling, that simply means
-the compiler will branch out and create a module.</p></div>
-<div class="paragraph"><p>If everything is an expression, does that mean this will allow
-me to create modules at runtime using the same syntax? Yes, but
-let’s not get ahead of ourselves yet.</p></div>
-<div class="paragraph"><p>For now we will just iterate over the AST, and will compile
-a module for each <code>mod</code> found. Modules cannot contain
-expressions yet, so there’s no need to recurse over it at this
-point. This should solve the compilation of our first snippet.</p></div>
-<div class="paragraph"><p>The <code>compile/1</code> function becomes:</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">compile</span></span>(<span style="color: #009900">Filename</span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"Compiling ~s...~n"</span>, [<span style="color: #009900">Filename</span>]),
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Src</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:read_file</span></span>(<span style="color: #009900">Filename</span>),
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Tokens</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">xerl_lexer:string</span></span>(<span style="font-weight: bold"><span style="color: #000080">binary_to_list</span></span>(<span style="color: #009900">Src</span>)),
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Exprs</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">xerl_parser:parse</span></span>(<span style="color: #009900">Tokens</span>),
- <span style="font-weight: bold"><span style="color: #000000">execute</span></span>(<span style="color: #009900">Filename</span>, <span style="color: #009900">Exprs</span>, [])<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">execute</span></span>(<span style="color: #990000">_</span>, [], <span style="color: #009900">Modules</span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"Done...~n"</span>),
- {<span style="color: #FF6600">ok</span>, <span style="font-weight: bold"><span style="color: #000000">lists:reverse</span></span>(<span style="color: #009900">Modules</span>)};
-<span style="font-weight: bold"><span style="color: #000000">execute</span></span>(<span style="color: #009900">Filename</span>, [<span style="color: #009900">Expr</span> <span style="color: #990000">=</span> {<span style="color: #FF6600">mod</span>, <span style="color: #990000">_</span>, {<span style="font-weight: bold"><span style="color: #000080">atom</span></span>, <span style="color: #990000">_</span>, <span style="color: #009900">Name</span>}, []}|<span style="color: #009900">Tail</span>], <span style="color: #009900">Modules</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, [<span style="color: #009900">Core</span>]} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">xerl_codegen:exprs</span></span>([<span style="color: #009900">Expr</span>]),
- {<span style="color: #FF6600">ok</span>, [{<span style="color: #009900">Name</span>, []}]} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">core_lint:module</span></span>(<span style="color: #009900">Core</span>),
- <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"~s~n"</span>, [<span style="font-weight: bold"><span style="color: #000000">core_pp:format</span></span>(<span style="color: #009900">Core</span>)]),
- {<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>, <span style="color: #009900">Beam</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">compile:forms</span></span>(<span style="color: #009900">Core</span>,
- [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #FF6600">from_core</span>, <span style="color: #FF6600">return_errors</span>, {<span style="color: #FF6600">source</span>, <span style="color: #009900">Filename</span>}]),
- {<span style="color: #FF6600">module</span>, <span style="color: #009900">Name</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">code:load_binary</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Filename</span>, <span style="color: #009900">Beam</span>),
- <span style="font-weight: bold"><span style="color: #000000">execute</span></span>(<span style="color: #009900">Filename</span>, <span style="color: #009900">Tail</span>, [<span style="color: #009900">Name</span>|<span style="color: #009900">Modules</span>])<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Running this compiler over the first snippet yields the following
-result:</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">Compiling</span> <span style="font-weight: bold"><span style="color: #000000">test</span></span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000000">mod_SUITE_data</span></span><span style="color: #990000">/</span><span style="color: #FF6600">two_modules</span><span style="color: #990000">.</span><span style="color: #FF6600">xerl</span><span style="color: #990000">...</span>
-<span style="color: #FF6600">module</span> <span style="color: #FF6600">'first_module'</span> [<span style="color: #FF6600">'module_info'</span><span style="color: #990000">/</span><span style="color: #993399">0</span>,
- <span style="color: #FF6600">'module_info'</span><span style="color: #990000">/</span><span style="color: #993399">1</span>]
- <span style="color: #FF6600">attributes</span> []
-<span style="color: #FF6600">'module_info'</span><span style="color: #990000">/</span><span style="color: #993399">0</span> <span style="color: #990000">=</span>
- <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span> () <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000080">call</span></span> <span style="color: #FF6600">'erlang'</span><span style="color: #990000">:</span><span style="color: #FF6600">'get_module_info'</span>
- (<span style="color: #FF6600">'first_module'</span>)
-<span style="color: #FF6600">'module_info'</span><span style="color: #990000">/</span><span style="color: #993399">1</span> <span style="color: #990000">=</span>
- <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span> (<span style="color: #009900">Key</span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000080">call</span></span> <span style="color: #FF6600">'erlang'</span><span style="color: #990000">:</span><span style="color: #FF6600">'get_module_info'</span>
- (<span style="color: #FF6600">'first_module'</span>, <span style="color: #009900">Key</span>)
-<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
-<span style="color: #FF6600">module</span> <span style="color: #FF6600">'second_module'</span> [<span style="color: #FF6600">'module_info'</span><span style="color: #990000">/</span><span style="color: #993399">0</span>,
- <span style="color: #FF6600">'module_info'</span><span style="color: #990000">/</span><span style="color: #993399">1</span>]
- <span style="color: #FF6600">attributes</span> []
-<span style="color: #FF6600">'module_info'</span><span style="color: #990000">/</span><span style="color: #993399">0</span> <span style="color: #990000">=</span>
- <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span> () <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000080">call</span></span> <span style="color: #FF6600">'erlang'</span><span style="color: #990000">:</span><span style="color: #FF6600">'get_module_info'</span>
- (<span style="color: #FF6600">'second_module'</span>)
-<span style="color: #FF6600">'module_info'</span><span style="color: #990000">/</span><span style="color: #993399">1</span> <span style="color: #990000">=</span>
- <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span> (<span style="color: #009900">Key</span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000080">call</span></span> <span style="color: #FF6600">'erlang'</span><span style="color: #990000">:</span><span style="color: #FF6600">'get_module_info'</span>
- (<span style="color: #FF6600">'second_module'</span>, <span style="color: #009900">Key</span>)
-<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
-<span style="color: #009900">Done</span><span style="color: #990000">...</span>
-{<span style="color: #FF6600">ok</span>,[<span style="color: #FF6600">first_module</span>,<span style="color: #FF6600">second_module</span>]}</tt></pre></div></div>
-<div class="paragraph"><p>Everything looks fine. And we can check that the two modules have
-been loaded into the VM:</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: #993399">9</span><span style="color: #990000">></span> <span style="color: #FF6600">m</span>(<span style="color: #FF6600">first_module</span>)<span style="color: #990000">.</span>
-<span style="color: #009900">Module</span> <span style="color: #FF6600">first_module</span> <span style="color: #FF6600">compiled</span><span style="color: #990000">:</span> <span style="color: #009900">Date</span><span style="color: #990000">:</span> <span style="color: #009900">February</span> <span style="color: #993399">2</span> <span style="color: #993399">2013</span>, <span style="color: #009900">Time</span><span style="color: #990000">:</span> <span style="color: #993399">14.56</span>
-<span style="color: #009900">Compiler</span> <span style="color: #FF6600">options</span><span style="color: #990000">:</span> [<span style="color: #FF6600">from_core</span>]
-<span style="color: #009900">Object</span> <span style="font-weight: bold"><span style="color: #000000">file: test</span></span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000000">mod_SUITE_data</span></span><span style="color: #990000">/</span><span style="color: #FF6600">two_modules</span><span style="color: #990000">.</span><span style="color: #FF6600">xerl</span>
-<span style="color: #009900">Exports</span><span style="color: #990000">:</span>
- <span style="font-weight: bold"><span style="color: #000080">module_info</span></span><span style="color: #990000">/</span><span style="color: #993399">0</span>
- <span style="font-weight: bold"><span style="color: #000080">module_info</span></span><span style="color: #990000">/</span><span style="color: #993399">1</span>
-<span style="color: #FF6600">ok</span>
-<span style="color: #993399">10</span><span style="color: #990000">></span> <span style="color: #FF6600">m</span>(<span style="color: #FF6600">second_module</span>)<span style="color: #990000">.</span>
-<span style="color: #009900">Module</span> <span style="color: #FF6600">second_module</span> <span style="color: #FF6600">compiled</span><span style="color: #990000">:</span> <span style="color: #009900">Date</span><span style="color: #990000">:</span> <span style="color: #009900">February</span> <span style="color: #993399">2</span> <span style="color: #993399">2013</span>, <span style="color: #009900">Time</span><span style="color: #990000">:</span> <span style="color: #993399">14.56</span>
-<span style="color: #009900">Compiler</span> <span style="color: #FF6600">options</span><span style="color: #990000">:</span> [<span style="color: #FF6600">from_core</span>]
-<span style="color: #009900">Object</span> <span style="font-weight: bold"><span style="color: #000000">file: test</span></span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000000">mod_SUITE_data</span></span><span style="color: #990000">/</span><span style="color: #FF6600">two_modules</span><span style="color: #990000">.</span><span style="color: #FF6600">xerl</span>
-<span style="color: #009900">Exports</span><span style="color: #990000">:</span>
- <span style="font-weight: bold"><span style="color: #000080">module_info</span></span><span style="color: #990000">/</span><span style="color: #993399">0</span>
- <span style="font-weight: bold"><span style="color: #000080">module_info</span></span><span style="color: #990000">/</span><span style="color: #993399">1</span>
-<span style="color: #FF6600">ok</span></tt></pre></div></div>
-<div class="paragraph"><p>So far so good!</p></div>
-<div class="paragraph"><p>What about the second snippet? It brings up many questions. What
-happens once a <code>mod</code> expression has been executed at
-compile time? If it’s an expression then it has to have a result,
-right? Right. We are still a bit lacking with expressions for now,
-though, so let’s get back to it after we add more.</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="https://github.com/extend/xerl/blob/0.2/">View the source</a>
-</p>
-</li>
-</ul></div>
+<div class="paragraph"><p>Everything is an expression.</p></div> +<div class="paragraph"><p>This sentence carries profound meaning. We will invoke it many +times over the course of these articles.</p></div> +<div class="paragraph"><p>If everything is an expression, then the language shouldn’t have +any problem with me defining two modules in the same source 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: #FF6600">mod</span> <span style="color: #FF6600">first_module</span> +<span style="font-weight: bold"><span style="color: #0000FF">begin</span></span> +<span style="font-weight: bold"><span style="color: #0000FF">end</span></span> + +<span style="color: #FF6600">mod</span> <span style="color: #FF6600">second_module</span> +<span style="font-weight: bold"><span style="color: #0000FF">begin</span></span> +<span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div> +<div class="paragraph"><p>Likewise, it shouldn’t have any problem with me defining a +module inside another module.</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">mod</span> <span style="color: #FF6600">out_module</span> +<span style="font-weight: bold"><span style="color: #0000FF">begin</span></span> + <span style="color: #FF6600">mod</span> <span style="color: #FF6600">in_module</span> + <span style="font-weight: bold"><span style="color: #0000FF">begin</span></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></tt></pre></div></div> +<div class="paragraph"><p>Of course, in the context of the Erlang VM, these two snippets +are equivalent; there is nothing preventing you from calling the +<code>in_module</code> module from any other module. The <code>mod</code> +instruction means a module should be created in the Erlang VM, +with no concept of scope attached.</p></div> +<div class="paragraph"><p>Still we need to handle both. To do this we will add a step +between the parser and the code generator that will walk over the +abstract syntax tree, from here onward shortened as <em>AST</em>, +and transform the AST by executing it where applicable.</p></div> +<div class="paragraph"><p>What happens when you execute a <code>mod</code> instruction? +A module is created. Since we are compiling, that simply means +the compiler will branch out and create a module.</p></div> +<div class="paragraph"><p>If everything is an expression, does that mean this will allow +me to create modules at runtime using the same syntax? Yes, but +let’s not get ahead of ourselves yet.</p></div> +<div class="paragraph"><p>For now we will just iterate over the AST, and will compile +a module for each <code>mod</code> found. Modules cannot contain +expressions yet, so there’s no need to recurse over it at this +point. This should solve the compilation of our first snippet.</p></div> +<div class="paragraph"><p>The <code>compile/1</code> function becomes:</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">compile</span></span>(<span style="color: #009900">Filename</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"Compiling ~s...~n"</span>, [<span style="color: #009900">Filename</span>]), + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Src</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:read_file</span></span>(<span style="color: #009900">Filename</span>), + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Tokens</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">xerl_lexer:string</span></span>(<span style="font-weight: bold"><span style="color: #000080">binary_to_list</span></span>(<span style="color: #009900">Src</span>)), + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Exprs</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">xerl_parser:parse</span></span>(<span style="color: #009900">Tokens</span>), + <span style="font-weight: bold"><span style="color: #000000">execute</span></span>(<span style="color: #009900">Filename</span>, <span style="color: #009900">Exprs</span>, [])<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">execute</span></span>(<span style="color: #990000">_</span>, [], <span style="color: #009900">Modules</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"Done...~n"</span>), + {<span style="color: #FF6600">ok</span>, <span style="font-weight: bold"><span style="color: #000000">lists:reverse</span></span>(<span style="color: #009900">Modules</span>)}; +<span style="font-weight: bold"><span style="color: #000000">execute</span></span>(<span style="color: #009900">Filename</span>, [<span style="color: #009900">Expr</span> <span style="color: #990000">=</span> {<span style="color: #FF6600">mod</span>, <span style="color: #990000">_</span>, {<span style="font-weight: bold"><span style="color: #000080">atom</span></span>, <span style="color: #990000">_</span>, <span style="color: #009900">Name</span>}, []}|<span style="color: #009900">Tail</span>], <span style="color: #009900">Modules</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, [<span style="color: #009900">Core</span>]} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">xerl_codegen:exprs</span></span>([<span style="color: #009900">Expr</span>]), + {<span style="color: #FF6600">ok</span>, [{<span style="color: #009900">Name</span>, []}]} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">core_lint:module</span></span>(<span style="color: #009900">Core</span>), + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"~s~n"</span>, [<span style="font-weight: bold"><span style="color: #000000">core_pp:format</span></span>(<span style="color: #009900">Core</span>)]), + {<span style="color: #FF6600">ok</span>, <span style="color: #990000">_</span>, <span style="color: #009900">Beam</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">compile:forms</span></span>(<span style="color: #009900">Core</span>, + [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #FF6600">from_core</span>, <span style="color: #FF6600">return_errors</span>, {<span style="color: #FF6600">source</span>, <span style="color: #009900">Filename</span>}]), + {<span style="color: #FF6600">module</span>, <span style="color: #009900">Name</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">code:load_binary</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Filename</span>, <span style="color: #009900">Beam</span>), + <span style="font-weight: bold"><span style="color: #000000">execute</span></span>(<span style="color: #009900">Filename</span>, <span style="color: #009900">Tail</span>, [<span style="color: #009900">Name</span>|<span style="color: #009900">Modules</span>])<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Running this compiler over the first snippet yields the following +result:</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">Compiling</span> <span style="font-weight: bold"><span style="color: #000000">test</span></span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000000">mod_SUITE_data</span></span><span style="color: #990000">/</span><span style="color: #FF6600">two_modules</span><span style="color: #990000">.</span><span style="color: #FF6600">xerl</span><span style="color: #990000">...</span> +<span style="color: #FF6600">module</span> <span style="color: #FF6600">'first_module'</span> [<span style="color: #FF6600">'module_info'</span><span style="color: #990000">/</span><span style="color: #993399">0</span>, + <span style="color: #FF6600">'module_info'</span><span style="color: #990000">/</span><span style="color: #993399">1</span>] + <span style="color: #FF6600">attributes</span> [] +<span style="color: #FF6600">'module_info'</span><span style="color: #990000">/</span><span style="color: #993399">0</span> <span style="color: #990000">=</span> + <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span> () <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000080">call</span></span> <span style="color: #FF6600">'erlang'</span><span style="color: #990000">:</span><span style="color: #FF6600">'get_module_info'</span> + (<span style="color: #FF6600">'first_module'</span>) +<span style="color: #FF6600">'module_info'</span><span style="color: #990000">/</span><span style="color: #993399">1</span> <span style="color: #990000">=</span> + <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span> (<span style="color: #009900">Key</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000080">call</span></span> <span style="color: #FF6600">'erlang'</span><span style="color: #990000">:</span><span style="color: #FF6600">'get_module_info'</span> + (<span style="color: #FF6600">'first_module'</span>, <span style="color: #009900">Key</span>) +<span style="font-weight: bold"><span style="color: #0000FF">end</span></span> +<span style="color: #FF6600">module</span> <span style="color: #FF6600">'second_module'</span> [<span style="color: #FF6600">'module_info'</span><span style="color: #990000">/</span><span style="color: #993399">0</span>, + <span style="color: #FF6600">'module_info'</span><span style="color: #990000">/</span><span style="color: #993399">1</span>] + <span style="color: #FF6600">attributes</span> [] +<span style="color: #FF6600">'module_info'</span><span style="color: #990000">/</span><span style="color: #993399">0</span> <span style="color: #990000">=</span> + <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span> () <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000080">call</span></span> <span style="color: #FF6600">'erlang'</span><span style="color: #990000">:</span><span style="color: #FF6600">'get_module_info'</span> + (<span style="color: #FF6600">'second_module'</span>) +<span style="color: #FF6600">'module_info'</span><span style="color: #990000">/</span><span style="color: #993399">1</span> <span style="color: #990000">=</span> + <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span> (<span style="color: #009900">Key</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000080">call</span></span> <span style="color: #FF6600">'erlang'</span><span style="color: #990000">:</span><span style="color: #FF6600">'get_module_info'</span> + (<span style="color: #FF6600">'second_module'</span>, <span style="color: #009900">Key</span>) +<span style="font-weight: bold"><span style="color: #0000FF">end</span></span> +<span style="color: #009900">Done</span><span style="color: #990000">...</span> +{<span style="color: #FF6600">ok</span>,[<span style="color: #FF6600">first_module</span>,<span style="color: #FF6600">second_module</span>]}</tt></pre></div></div> +<div class="paragraph"><p>Everything looks fine. And we can check that the two modules have +been loaded into the VM:</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: #993399">9</span><span style="color: #990000">></span> <span style="color: #FF6600">m</span>(<span style="color: #FF6600">first_module</span>)<span style="color: #990000">.</span> +<span style="color: #009900">Module</span> <span style="color: #FF6600">first_module</span> <span style="color: #FF6600">compiled</span><span style="color: #990000">:</span> <span style="color: #009900">Date</span><span style="color: #990000">:</span> <span style="color: #009900">February</span> <span style="color: #993399">2</span> <span style="color: #993399">2013</span>, <span style="color: #009900">Time</span><span style="color: #990000">:</span> <span style="color: #993399">14.56</span> +<span style="color: #009900">Compiler</span> <span style="color: #FF6600">options</span><span style="color: #990000">:</span> [<span style="color: #FF6600">from_core</span>] +<span style="color: #009900">Object</span> <span style="font-weight: bold"><span style="color: #000000">file: test</span></span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000000">mod_SUITE_data</span></span><span style="color: #990000">/</span><span style="color: #FF6600">two_modules</span><span style="color: #990000">.</span><span style="color: #FF6600">xerl</span> +<span style="color: #009900">Exports</span><span style="color: #990000">:</span> + <span style="font-weight: bold"><span style="color: #000080">module_info</span></span><span style="color: #990000">/</span><span style="color: #993399">0</span> + <span style="font-weight: bold"><span style="color: #000080">module_info</span></span><span style="color: #990000">/</span><span style="color: #993399">1</span> +<span style="color: #FF6600">ok</span> +<span style="color: #993399">10</span><span style="color: #990000">></span> <span style="color: #FF6600">m</span>(<span style="color: #FF6600">second_module</span>)<span style="color: #990000">.</span> +<span style="color: #009900">Module</span> <span style="color: #FF6600">second_module</span> <span style="color: #FF6600">compiled</span><span style="color: #990000">:</span> <span style="color: #009900">Date</span><span style="color: #990000">:</span> <span style="color: #009900">February</span> <span style="color: #993399">2</span> <span style="color: #993399">2013</span>, <span style="color: #009900">Time</span><span style="color: #990000">:</span> <span style="color: #993399">14.56</span> +<span style="color: #009900">Compiler</span> <span style="color: #FF6600">options</span><span style="color: #990000">:</span> [<span style="color: #FF6600">from_core</span>] +<span style="color: #009900">Object</span> <span style="font-weight: bold"><span style="color: #000000">file: test</span></span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000000">mod_SUITE_data</span></span><span style="color: #990000">/</span><span style="color: #FF6600">two_modules</span><span style="color: #990000">.</span><span style="color: #FF6600">xerl</span> +<span style="color: #009900">Exports</span><span style="color: #990000">:</span> + <span style="font-weight: bold"><span style="color: #000080">module_info</span></span><span style="color: #990000">/</span><span style="color: #993399">0</span> + <span style="font-weight: bold"><span style="color: #000080">module_info</span></span><span style="color: #990000">/</span><span style="color: #993399">1</span> +<span style="color: #FF6600">ok</span></tt></pre></div></div> +<div class="paragraph"><p>So far so good!</p></div> +<div class="paragraph"><p>What about the second snippet? It brings up many questions. What +happens once a <code>mod</code> expression has been executed at +compile time? If it’s an expression then it has to have a result, +right? Right. We are still a bit lacking with expressions for now, +though, so let’s get back to it after we add more.</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="https://github.com/extend/xerl/blob/0.2/">View the source</a> +</p> +</li> +</ul></div> </article> </div> @@ -225,55 +225,107 @@ though, so let’s get back to it after we add more.</p></div> <h3>More articles</h3> <ul id="articles-nav" class="extra_margin"> - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + + <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + - <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + + <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + - <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + + <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + - <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + + <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + - <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + + <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + - <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + + <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + - <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + + <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + - <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + + <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + - <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + + <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + - <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + + <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + - <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + </ul> diff --git a/articles/xerl-0.3-atomic-expressions/index.html b/articles/xerl-0.3-atomic-expressions/index.html index f3042180..b49b5613 100644 --- a/articles/xerl-0.3-atomic-expressions/index.html +++ b/articles/xerl-0.3-atomic-expressions/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Xerl: atomic expressions</title> @@ -74,153 +74,153 @@ </p> </header> -<div class="paragraph"><p>We will be adding atomic integer expressions to our language.
-These look as follow in Erlang:</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: #993399">42</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>And the result of this expression is of course 42.</p></div>
-<div class="paragraph"><p>We will be running this expression at compile time, since we
-don’t have the means to run code at runtime yet. This will of
-course result in no module being compiled, but that’s OK, it will
-allow us to discuss a few important things we’ll have to plan for
-later on.</p></div>
-<div class="paragraph"><p>First, we must of course accept integers in the tokenizer.</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">D</span>}<span style="color: #990000">+</span> <span style="color: #990000">:</span> {<span style="color: #FF6600">token</span>, {<span style="font-weight: bold"><span style="color: #000080">integer</span></span>, <span style="color: #009900">TokenLine</span>, <span style="font-weight: bold"><span style="color: #000080">list_to_integer</span></span>(<span style="color: #009900">TokenChars</span>)}}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>We must then accept atomic integer expressions in the parser.
-This is a simple change. The integer token is terminal so we need
-to add it to the list of terminals, and then we only need to add
-it as a possible expression.</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">expr</span> <span style="color: #990000">-></span> <span style="color: #FF6600">integer</span> <span style="color: #990000">:</span> <span style="color: #FF6600">'$1'</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>A file containing only the number 42 (with no terminating dot)
-will give the following result when parsing it. This is incidentally
-the same result as when tokenizing.</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: #000080">integer</span></span>,<span style="color: #993399">1</span>,<span style="color: #993399">42</span>}]</tt></pre></div></div>
-<div class="paragraph"><p>We must then evaluate it. We’re going to interpret it for now.
-Since the result of this expression is not stored in a variable,
-we are going to simply print it on the screen and discard 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="font-weight: bold"><span style="color: #000000">execute</span></span>(<span style="color: #009900">Filename</span>, [{<span style="font-weight: bold"><span style="color: #000080">integer</span></span>, <span style="color: #990000">_</span>, <span style="color: #009900">Int</span>}|<span style="color: #009900">Tail</span>], <span style="color: #009900">Modules</span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"integer ~p~n"</span>, [<span style="color: #009900">Int</span>]),
- <span style="font-weight: bold"><span style="color: #000000">execute</span></span>(<span style="color: #009900">Filename</span>, <span style="color: #009900">Tail</span>, <span style="color: #009900">Modules</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You might think by now that what we’ve done so far this time
-is useless. It brings up many interesting questions though.</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-What happens if a file contains two integers?
-</p>
-</li>
-<li>
-<p>
-Can we live without expression separators?
-</p>
-</li>
-<li>
-<p>
-Do we need an interpreter for the compile step?
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>This is what happens when we create a file that contains two
-integers on two separate lines:</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: #000080">integer</span></span>,<span style="color: #993399">1</span>,<span style="color: #993399">42</span>},{<span style="font-weight: bold"><span style="color: #000080">integer</span></span>,<span style="color: #993399">2</span>,<span style="color: #993399">43</span>}]</tt></pre></div></div>
-<div class="paragraph"><p>And on the same lines:</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: #000080">integer</span></span>,<span style="color: #993399">1</span>,<span style="color: #993399">42</span>},{<span style="font-weight: bold"><span style="color: #000080">integer</span></span>,<span style="color: #993399">1</span>,<span style="color: #993399">43</span>}]</tt></pre></div></div>
-<div class="paragraph"><p>Does this mean we do not need separators between expressions?
-Not quite. The <code>+</code> and <code>-</code> operators are an
-example of why we can’t have nice things. They are ambiguous. They
-have two different meanings: make an atomic integer positive or
-negative, or perform an addition or a substraction between two
-integers. Without a separator you won’t be able to know if the
-following snippet is one or two expressions:</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: #993399">42</span> <span style="color: #990000">-</span> <span style="color: #993399">12</span></tt></pre></div></div>
-<div class="paragraph"><p>Can we use the line ending as an expression separator then?
-Some languages make whitespace important, often the line
-separator becomes the expression separator. I do not think this
-is the best idea, it can lead to errors. For example the following
-snippet would be two expressions:</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">Var</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">some_module:some_function</span></span>() <span style="color: #990000">+</span> <span style="font-weight: bold"><span style="color: #000000">some_module:other_function</span></span>()
- <span style="color: #990000">+</span> <span style="font-weight: bold"><span style="color: #000000">another_module:another_function</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>It is not obvious what would happen unless you are a veteran
-of the language, and so we will not go down that road. We will use
-an expression separator just like in Erlang: the comma. We will
-however allow a trailing comma to make copy pasting code easier,
-even if this means some old academics guy will go nuts about it
-later on. This trailing comma will be optional and simply discarded
-by the parser when encountered. We will implement this next.</p></div>
-<div class="paragraph"><p>The question as to how we will handle running expressions
-remains. We have two choices here: we can write an interpreter,
-or we can compile the code and run it. Writing an interpreter
-would require us to do twice the work, and we are lazy, so we will
-not do that.</p></div>
-<div class="paragraph"><p>You might already know that Erlang does not use the same code
-for compiling and for evaluating commands in the shell. The main
-reason for this is that in Erlang everything isn’t an expression.
-Indeed, the compiler compiles forms which contain expressions,
-but you can’t have forms in the shell.</p></div>
-<div class="paragraph"><p>How are we going to compile the code that isn’t part of a module
-then? What do we need to run at compile-time, anyway? The body of
-the file itself, of course. The body of module declarations. That’s
-about it.</p></div>
-<div class="paragraph"><p>For the file itself, we can simply compile it as a big function
-that will be executed. Then, everytime we encounter a module
-declaration, we will run the compiler on its body, making its body
-essentially a big function that will be executed. The same mechanism
-will be applied when we encounter a module declaration at runtime.</p></div>
-<div class="paragraph"><p>At runtime there’s nothing else for us to do, the result of this
-operation will load all the compiled modules. At compile time we
-will also want to save them to a file. We’ll see later how we can
-do that.</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="https://github.com/extend/xerl/blob/0.3/">View the source</a>
-</p>
-</li>
-</ul></div>
+<div class="paragraph"><p>We will be adding atomic integer expressions to our language. +These look as follow in Erlang:</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: #993399">42</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>And the result of this expression is of course 42.</p></div> +<div class="paragraph"><p>We will be running this expression at compile time, since we +don’t have the means to run code at runtime yet. This will of +course result in no module being compiled, but that’s OK, it will +allow us to discuss a few important things we’ll have to plan for +later on.</p></div> +<div class="paragraph"><p>First, we must of course accept integers in the tokenizer.</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">D</span>}<span style="color: #990000">+</span> <span style="color: #990000">:</span> {<span style="color: #FF6600">token</span>, {<span style="font-weight: bold"><span style="color: #000080">integer</span></span>, <span style="color: #009900">TokenLine</span>, <span style="font-weight: bold"><span style="color: #000080">list_to_integer</span></span>(<span style="color: #009900">TokenChars</span>)}}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>We must then accept atomic integer expressions in the parser. +This is a simple change. The integer token is terminal so we need +to add it to the list of terminals, and then we only need to add +it as a possible expression.</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">expr</span> <span style="color: #990000">-></span> <span style="color: #FF6600">integer</span> <span style="color: #990000">:</span> <span style="color: #FF6600">'$1'</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>A file containing only the number 42 (with no terminating dot) +will give the following result when parsing it. This is incidentally +the same result as when tokenizing.</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: #000080">integer</span></span>,<span style="color: #993399">1</span>,<span style="color: #993399">42</span>}]</tt></pre></div></div> +<div class="paragraph"><p>We must then evaluate it. We’re going to interpret it for now. +Since the result of this expression is not stored in a variable, +we are going to simply print it on the screen and discard 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="font-weight: bold"><span style="color: #000000">execute</span></span>(<span style="color: #009900">Filename</span>, [{<span style="font-weight: bold"><span style="color: #000080">integer</span></span>, <span style="color: #990000">_</span>, <span style="color: #009900">Int</span>}|<span style="color: #009900">Tail</span>], <span style="color: #009900">Modules</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"integer ~p~n"</span>, [<span style="color: #009900">Int</span>]), + <span style="font-weight: bold"><span style="color: #000000">execute</span></span>(<span style="color: #009900">Filename</span>, <span style="color: #009900">Tail</span>, <span style="color: #009900">Modules</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You might think by now that what we’ve done so far this time +is useless. It brings up many interesting questions though.</p></div> +<div class="ulist"><ul> +<li> +<p> +What happens if a file contains two integers? +</p> +</li> +<li> +<p> +Can we live without expression separators? +</p> +</li> +<li> +<p> +Do we need an interpreter for the compile step? +</p> +</li> +</ul></div> +<div class="paragraph"><p>This is what happens when we create a file that contains two +integers on two separate lines:</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: #000080">integer</span></span>,<span style="color: #993399">1</span>,<span style="color: #993399">42</span>},{<span style="font-weight: bold"><span style="color: #000080">integer</span></span>,<span style="color: #993399">2</span>,<span style="color: #993399">43</span>}]</tt></pre></div></div> +<div class="paragraph"><p>And on the same lines:</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: #000080">integer</span></span>,<span style="color: #993399">1</span>,<span style="color: #993399">42</span>},{<span style="font-weight: bold"><span style="color: #000080">integer</span></span>,<span style="color: #993399">1</span>,<span style="color: #993399">43</span>}]</tt></pre></div></div> +<div class="paragraph"><p>Does this mean we do not need separators between expressions? +Not quite. The <code>+</code> and <code>-</code> operators are an +example of why we can’t have nice things. They are ambiguous. They +have two different meanings: make an atomic integer positive or +negative, or perform an addition or a substraction between two +integers. Without a separator you won’t be able to know if the +following snippet is one or two expressions:</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: #993399">42</span> <span style="color: #990000">-</span> <span style="color: #993399">12</span></tt></pre></div></div> +<div class="paragraph"><p>Can we use the line ending as an expression separator then? +Some languages make whitespace important, often the line +separator becomes the expression separator. I do not think this +is the best idea, it can lead to errors. For example the following +snippet would be two expressions:</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">Var</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">some_module:some_function</span></span>() <span style="color: #990000">+</span> <span style="font-weight: bold"><span style="color: #000000">some_module:other_function</span></span>() + <span style="color: #990000">+</span> <span style="font-weight: bold"><span style="color: #000000">another_module:another_function</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>It is not obvious what would happen unless you are a veteran +of the language, and so we will not go down that road. We will use +an expression separator just like in Erlang: the comma. We will +however allow a trailing comma to make copy pasting code easier, +even if this means some old academics guy will go nuts about it +later on. This trailing comma will be optional and simply discarded +by the parser when encountered. We will implement this next.</p></div> +<div class="paragraph"><p>The question as to how we will handle running expressions +remains. We have two choices here: we can write an interpreter, +or we can compile the code and run it. Writing an interpreter +would require us to do twice the work, and we are lazy, so we will +not do that.</p></div> +<div class="paragraph"><p>You might already know that Erlang does not use the same code +for compiling and for evaluating commands in the shell. The main +reason for this is that in Erlang everything isn’t an expression. +Indeed, the compiler compiles forms which contain expressions, +but you can’t have forms in the shell.</p></div> +<div class="paragraph"><p>How are we going to compile the code that isn’t part of a module +then? What do we need to run at compile-time, anyway? The body of +the file itself, of course. The body of module declarations. That’s +about it.</p></div> +<div class="paragraph"><p>For the file itself, we can simply compile it as a big function +that will be executed. Then, everytime we encounter a module +declaration, we will run the compiler on its body, making its body +essentially a big function that will be executed. The same mechanism +will be applied when we encounter a module declaration at runtime.</p></div> +<div class="paragraph"><p>At runtime there’s nothing else for us to do, the result of this +operation will load all the compiled modules. At compile time we +will also want to save them to a file. We’ll see later how we can +do that.</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="https://github.com/extend/xerl/blob/0.3/">View the source</a> +</p> +</li> +</ul></div> </article> </div> @@ -229,55 +229,107 @@ do that.</p></div> <h3>More articles</h3> <ul id="articles-nav" class="extra_margin"> - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + - <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + + <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + - <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + + <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + - <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + + <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + - <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + + <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + - <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + + <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + - <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + + <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + - <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + + <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + - <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + + <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + - <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + + <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + - <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + + </ul> diff --git a/articles/xerl-0.4-expression-separator/index.html b/articles/xerl-0.4-expression-separator/index.html index 4bf4a3e8..75298905 100644 --- a/articles/xerl-0.4-expression-separator/index.html +++ b/articles/xerl-0.4-expression-separator/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Xerl: expression separator</title> @@ -74,58 +74,58 @@ </p> </header> -<div class="paragraph"><p>As promised we are adding an expression separator this time.
-This will be short and easy.</p></div>
-<div class="paragraph"><p>In the tokenizer we only need to add a line recognizing the
-comma as a valid token.</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: #FF6600">token</span>, {<span style="color: #FF6600">','</span>, <span style="color: #009900">TokenLine</span>}}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Then we need to change the following lines in the parser:</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">exprs</span> <span style="color: #990000">-></span> <span style="color: #FF6600">expr</span> <span style="color: #990000">:</span> [<span style="color: #FF6600">'$1'</span>]<span style="color: #990000">.</span>
-<span style="color: #FF6600">exprs</span> <span style="color: #990000">-></span> <span style="color: #FF6600">expr</span> <span style="color: #FF6600">exprs</span> <span style="color: #990000">:</span> [<span style="color: #FF6600">'$1'</span> | <span style="color: #FF6600">'$2'</span>]<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>And add a comma between the expressions on the second line:</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">exprs</span> <span style="color: #990000">-></span> <span style="color: #FF6600">expr</span> <span style="color: #990000">:</span> [<span style="color: #FF6600">'$1'</span>]<span style="color: #990000">.</span>
-<span style="color: #FF6600">exprs</span> <span style="color: #990000">-></span> <span style="color: #FF6600">expr</span> <span style="color: #FF6600">','</span> <span style="color: #FF6600">exprs</span> <span style="color: #990000">:</span> [<span style="color: #FF6600">'$1'</span> | <span style="color: #FF6600">'$3'</span>]<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>That takes care of everything except the optional trailing
-comma at the end of our lists of expressions. We just need an
-additional rule to take care of 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: #FF6600">exprs</span> <span style="color: #990000">-></span> <span style="color: #FF6600">expr</span> <span style="color: #FF6600">','</span> <span style="color: #990000">:</span> [<span style="color: #FF6600">'$1'</span>]<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>That’s it.</p></div>
-<div class="paragraph"><p>Wondering why we don’t have this optional trailing comma in
-Erlang considering how easy it was and the number of people
-complaining about it? Yeah, me too. But that’s for someone else
-to answer.</p></div>
-<div class="paragraph"><p>Another change I want to talk about is a simple modification
-of the compiler code to use an <code>#env{}</code> record for
-tracking state instead of passing around individual variables.
-This will be required later on when we make modules into proper
-expressions so I thought it was a good idea to anticipate.</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="https://github.com/extend/xerl/blob/0.4/">View the source</a>
-</p>
-</li>
-</ul></div>
+<div class="paragraph"><p>As promised we are adding an expression separator this time. +This will be short and easy.</p></div> +<div class="paragraph"><p>In the tokenizer we only need to add a line recognizing the +comma as a valid token.</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: #FF6600">token</span>, {<span style="color: #FF6600">','</span>, <span style="color: #009900">TokenLine</span>}}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Then we need to change the following lines in the parser:</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">exprs</span> <span style="color: #990000">-></span> <span style="color: #FF6600">expr</span> <span style="color: #990000">:</span> [<span style="color: #FF6600">'$1'</span>]<span style="color: #990000">.</span> +<span style="color: #FF6600">exprs</span> <span style="color: #990000">-></span> <span style="color: #FF6600">expr</span> <span style="color: #FF6600">exprs</span> <span style="color: #990000">:</span> [<span style="color: #FF6600">'$1'</span> | <span style="color: #FF6600">'$2'</span>]<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>And add a comma between the expressions on the second line:</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">exprs</span> <span style="color: #990000">-></span> <span style="color: #FF6600">expr</span> <span style="color: #990000">:</span> [<span style="color: #FF6600">'$1'</span>]<span style="color: #990000">.</span> +<span style="color: #FF6600">exprs</span> <span style="color: #990000">-></span> <span style="color: #FF6600">expr</span> <span style="color: #FF6600">','</span> <span style="color: #FF6600">exprs</span> <span style="color: #990000">:</span> [<span style="color: #FF6600">'$1'</span> | <span style="color: #FF6600">'$3'</span>]<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>That takes care of everything except the optional trailing +comma at the end of our lists of expressions. We just need an +additional rule to take care of 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: #FF6600">exprs</span> <span style="color: #990000">-></span> <span style="color: #FF6600">expr</span> <span style="color: #FF6600">','</span> <span style="color: #990000">:</span> [<span style="color: #FF6600">'$1'</span>]<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>That’s it.</p></div> +<div class="paragraph"><p>Wondering why we don’t have this optional trailing comma in +Erlang considering how easy it was and the number of people +complaining about it? Yeah, me too. But that’s for someone else +to answer.</p></div> +<div class="paragraph"><p>Another change I want to talk about is a simple modification +of the compiler code to use an <code>#env{}</code> record for +tracking state instead of passing around individual variables. +This will be required later on when we make modules into proper +expressions so I thought it was a good idea to anticipate.</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="https://github.com/extend/xerl/blob/0.4/">View the source</a> +</p> +</li> +</ul></div> </article> </div> @@ -134,55 +134,107 @@ expressions so I thought it was a good idea to anticipate.</p></div> <h3>More articles</h3> <ul id="articles-nav" class="extra_margin"> - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + - <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + + <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + - <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + + <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + - <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + + <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + - <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + + <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + - <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + + <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + - <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + + <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + - <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + + <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + - <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + + <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + - <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + + <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + - <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + + + </ul> diff --git a/articles/xerl-0.5-intermediate-module/index.html b/articles/xerl-0.5-intermediate-module/index.html index dc9f2a2a..38627277 100644 --- a/articles/xerl-0.5-intermediate-module/index.html +++ b/articles/xerl-0.5-intermediate-module/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Xerl: intermediate module</title> @@ -74,136 +74,136 @@ </p> </header> -<div class="paragraph"><p>Today we will start the work on the intermediate module
-that will be used to run the code for the expressions found
-in our file’s body, replacing our interpreter.</p></div>
-<div class="paragraph"><p>This is what we want to have when all the work is done:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>xerl -> tokens -> AST -> intermediate -> cerl</code></pre>
-</div></div>
-<div class="paragraph"><p>Today we will perform this work only on the atomic integer
-expression however, so we will not build any module at the end.
-We have a few more things to take care of before getting there.
-This does mean that we completely break compilation of modules
-though, so hopefully we can resolve that soon.</p></div>
-<div class="paragraph"><p>This intermediate representation is in the form of a module
-which contains a single function: <code>run/0</code>. This function
-contains all the expressions from our Xerl source file.</p></div>
-<div class="paragraph"><p>In the case of a Xerl source file only containing the integer
-<code>42</code>, we will obtain the following module ready to
-be executed:</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: #000080">-module</span></span>(<span style="color: #FF6600">'$xerl_intermediate'</span>)<span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">run</span></span><span style="color: #990000">/</span><span style="color: #993399">0</span>])<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">run</span></span>() <span style="color: #990000">-></span>
- <span style="color: #993399">42</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Running it will of course give us a result of <code>42</code>,
-the same we had when interpreting expressions.</p></div>
-<div class="paragraph"><p>The resulting Core Erlang code looks 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: #FF6600">module</span> <span style="color: #FF6600">'$xerl_intermediate'</span> [<span style="color: #FF6600">'run'</span><span style="color: #990000">/</span><span style="color: #993399">0</span>]
- <span style="color: #FF6600">attributes</span> []
-<span style="color: #FF6600">'run'</span><span style="color: #990000">/</span><span style="color: #993399">0</span> <span style="color: #990000">=</span>
- <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span> () <span style="color: #990000">-></span>
- <span style="color: #993399">42</span>
-<span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
-<div class="paragraph"><p>The nice thing about doing it like this is that other than the
-definition of the intermediate module and its <code>run/0</code>
-function, we can use the same code we are using for generating
-the final Beam file. It may also be faster than interpreting
-if you have complex modules.</p></div>
-<div class="paragraph"><p>Of course this here only works for the simplest cases, as you
-cannot declare a module or a function inside another Erlang function.
-We will need to wrap these into function calls to the Xerl compiler
-that will take care of compiling them, making them available for
-any subsequent expression. We will also need to pass the environment
-to the <code>run</code> function to keep track of all this.</p></div>
-<div class="paragraph"><p>This does mean that we will have different code for compiling
-<code>fun</code> and <code>mod</code> expressions when creating
-the intermediate module. But the many other expressions don’t need
-any special care.</p></div>
-<div class="paragraph"><p>Right now we’ve used the <code>'$xerl_intermediate'</code> atom
-for the intermediate module name because we only have one, but we
-will need to have a more random name later on when we’ll implement
-modules this way.</p></div>
-<div class="paragraph"><p>The attentive mind will know by now that when compiling a Xerl
-file containing one module, we will need to compile two intermediate
-modules: one for the file body, and one for the module’s body. Worry
-not though, if we only detect <code>mod</code> instructions in the file
-body, we can just skip this phase.</p></div>
-<div class="paragraph"><p>While we’re at it, we’ll modify our code generator to handle lists
-of expressions, which didn’t actually work with integer literals
-before.</p></div>
-<div class="paragraph"><p>We’re going to use Core Erlang sequences for running the many
-expressions. Sequences work like <code>let</code>, except no value
-is actually bound. Perfect for our case, since we don’t support
-binding values at this time anyway.</p></div>
-<div class="paragraph"><p>Sequences have an argument and a body, both being Core Erlang
-expressions. The simplest way to have many expressions is to use
-a simple expression for the argument and a sequence for the rest
-of the expressions. When we encounter the last expression in the
-list, we do not create a sequence.</p></div>
-<div class="paragraph"><p>The result is this very simple 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">comp_body</span></span>([<span style="color: #009900">Expr</span>]) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">expr</span></span>(<span style="color: #009900">Expr</span>);
-<span style="font-weight: bold"><span style="color: #000000">comp_body</span></span>([<span style="color: #009900">Expr</span>|<span style="color: #009900">Exprs</span>]) <span style="color: #990000">-></span>
- <span style="color: #009900">Arg</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">expr</span></span>(<span style="color: #009900">Expr</span>),
- <span style="color: #009900">Body</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">comp_body</span></span>(<span style="color: #009900">Exprs</span>),
- <span style="font-weight: bold"><span style="color: #000000">cerl:c_seq</span></span>(<span style="color: #009900">Arg</span>, <span style="color: #009900">Body</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>In the case of our example above, a sequence will not be created,
-we only have one expression. If we were to have <code>42, 43, 44</code>
-in our Xerl source file, we would have a result equivalent to the
-following before optimization:</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: #000080">-module</span></span>(<span style="color: #FF6600">'$xerl_intermediate'</span>)<span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">run</span></span><span style="color: #990000">/</span><span style="color: #993399">0</span>])<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">run</span></span>() <span style="color: #990000">-></span>
- <span style="color: #993399">42</span>,
- <span style="color: #993399">43</span>,
- <span style="color: #993399">44</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>And the result is of course <code>44</code>.</p></div>
-<div class="paragraph"><p>The resulting Core Erlang code looks 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: #FF6600">module</span> <span style="color: #FF6600">'$xerl_intermediate'</span> [<span style="color: #FF6600">'run'</span><span style="color: #990000">/</span><span style="color: #993399">0</span>]
- <span style="color: #FF6600">attributes</span> []
-<span style="color: #FF6600">'run'</span><span style="color: #990000">/</span><span style="color: #993399">0</span> <span style="color: #990000">=</span>
- <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span> () <span style="color: #990000">-></span>
- <span style="color: #FF6600">do</span> <span style="color: #993399">42</span>
- <span style="color: #FF6600">do</span> <span style="color: #993399">43</span>
- <span style="color: #993399">44</span>
-<span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>
-<div class="paragraph"><p>Feels very lisp-y, right? Yep.</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="https://github.com/extend/xerl/blob/0.5/">View the source</a>
-</p>
-</li>
-</ul></div>
+<div class="paragraph"><p>Today we will start the work on the intermediate module +that will be used to run the code for the expressions found +in our file’s body, replacing our interpreter.</p></div> +<div class="paragraph"><p>This is what we want to have when all the work is done:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><code>xerl -> tokens -> AST -> intermediate -> cerl</code></pre> +</div></div> +<div class="paragraph"><p>Today we will perform this work only on the atomic integer +expression however, so we will not build any module at the end. +We have a few more things to take care of before getting there. +This does mean that we completely break compilation of modules +though, so hopefully we can resolve that soon.</p></div> +<div class="paragraph"><p>This intermediate representation is in the form of a module +which contains a single function: <code>run/0</code>. This function +contains all the expressions from our Xerl source file.</p></div> +<div class="paragraph"><p>In the case of a Xerl source file only containing the integer +<code>42</code>, we will obtain the following module ready to +be executed:</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: #000080">-module</span></span>(<span style="color: #FF6600">'$xerl_intermediate'</span>)<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">run</span></span><span style="color: #990000">/</span><span style="color: #993399">0</span>])<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">run</span></span>() <span style="color: #990000">-></span> + <span style="color: #993399">42</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Running it will of course give us a result of <code>42</code>, +the same we had when interpreting expressions.</p></div> +<div class="paragraph"><p>The resulting Core Erlang code looks 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: #FF6600">module</span> <span style="color: #FF6600">'$xerl_intermediate'</span> [<span style="color: #FF6600">'run'</span><span style="color: #990000">/</span><span style="color: #993399">0</span>] + <span style="color: #FF6600">attributes</span> [] +<span style="color: #FF6600">'run'</span><span style="color: #990000">/</span><span style="color: #993399">0</span> <span style="color: #990000">=</span> + <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span> () <span style="color: #990000">-></span> + <span style="color: #993399">42</span> +<span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div> +<div class="paragraph"><p>The nice thing about doing it like this is that other than the +definition of the intermediate module and its <code>run/0</code> +function, we can use the same code we are using for generating +the final Beam file. It may also be faster than interpreting +if you have complex modules.</p></div> +<div class="paragraph"><p>Of course this here only works for the simplest cases, as you +cannot declare a module or a function inside another Erlang function. +We will need to wrap these into function calls to the Xerl compiler +that will take care of compiling them, making them available for +any subsequent expression. We will also need to pass the environment +to the <code>run</code> function to keep track of all this.</p></div> +<div class="paragraph"><p>This does mean that we will have different code for compiling +<code>fun</code> and <code>mod</code> expressions when creating +the intermediate module. But the many other expressions don’t need +any special care.</p></div> +<div class="paragraph"><p>Right now we’ve used the <code>'$xerl_intermediate'</code> atom +for the intermediate module name because we only have one, but we +will need to have a more random name later on when we’ll implement +modules this way.</p></div> +<div class="paragraph"><p>The attentive mind will know by now that when compiling a Xerl +file containing one module, we will need to compile two intermediate +modules: one for the file body, and one for the module’s body. Worry +not though, if we only detect <code>mod</code> instructions in the file +body, we can just skip this phase.</p></div> +<div class="paragraph"><p>While we’re at it, we’ll modify our code generator to handle lists +of expressions, which didn’t actually work with integer literals +before.</p></div> +<div class="paragraph"><p>We’re going to use Core Erlang sequences for running the many +expressions. Sequences work like <code>let</code>, except no value +is actually bound. Perfect for our case, since we don’t support +binding values at this time anyway.</p></div> +<div class="paragraph"><p>Sequences have an argument and a body, both being Core Erlang +expressions. The simplest way to have many expressions is to use +a simple expression for the argument and a sequence for the rest +of the expressions. When we encounter the last expression in the +list, we do not create a sequence.</p></div> +<div class="paragraph"><p>The result is this very simple 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">comp_body</span></span>([<span style="color: #009900">Expr</span>]) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">expr</span></span>(<span style="color: #009900">Expr</span>); +<span style="font-weight: bold"><span style="color: #000000">comp_body</span></span>([<span style="color: #009900">Expr</span>|<span style="color: #009900">Exprs</span>]) <span style="color: #990000">-></span> + <span style="color: #009900">Arg</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">expr</span></span>(<span style="color: #009900">Expr</span>), + <span style="color: #009900">Body</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">comp_body</span></span>(<span style="color: #009900">Exprs</span>), + <span style="font-weight: bold"><span style="color: #000000">cerl:c_seq</span></span>(<span style="color: #009900">Arg</span>, <span style="color: #009900">Body</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>In the case of our example above, a sequence will not be created, +we only have one expression. If we were to have <code>42, 43, 44</code> +in our Xerl source file, we would have a result equivalent to the +following before optimization:</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: #000080">-module</span></span>(<span style="color: #FF6600">'$xerl_intermediate'</span>)<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">run</span></span><span style="color: #990000">/</span><span style="color: #993399">0</span>])<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">run</span></span>() <span style="color: #990000">-></span> + <span style="color: #993399">42</span>, + <span style="color: #993399">43</span>, + <span style="color: #993399">44</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>And the result is of course <code>44</code>.</p></div> +<div class="paragraph"><p>The resulting Core Erlang code looks 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: #FF6600">module</span> <span style="color: #FF6600">'$xerl_intermediate'</span> [<span style="color: #FF6600">'run'</span><span style="color: #990000">/</span><span style="color: #993399">0</span>] + <span style="color: #FF6600">attributes</span> [] +<span style="color: #FF6600">'run'</span><span style="color: #990000">/</span><span style="color: #993399">0</span> <span style="color: #990000">=</span> + <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span> () <span style="color: #990000">-></span> + <span style="color: #FF6600">do</span> <span style="color: #993399">42</span> + <span style="color: #FF6600">do</span> <span style="color: #993399">43</span> + <span style="color: #993399">44</span> +<span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div> +<div class="paragraph"><p>Feels very lisp-y, right? Yep.</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="https://github.com/extend/xerl/blob/0.5/">View the source</a> +</p> +</li> +</ul></div> </article> </div> @@ -212,55 +212,107 @@ http://www.gnu.org/software/src-highlite --> <h3>More articles</h3> <ul id="articles-nav" class="extra_margin"> - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.2/">Cowboy 2.0 release candidate 2</a></li> + + + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1/">Cowboy 2.0 release candidate 1</a></li> + + <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + - <li><a href="https://ninenines.eu/articles/the-elephant-in-the-room/">The elephant in the room</a></li> + + <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + - <li><a href="https://ninenines.eu/articles/dont-let-it-crash/">Don't let it crash</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy-2.0.0-pre.4/">Cowboy 2.0 pre-release 4</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-1.3/">Ranch 1.3</a></li> + + <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + - <li><a href="https://ninenines.eu/articles/ml-archives/">Mailing list archived</a></li> + + <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + - <li><a href="https://ninenines.eu/articles/website-update/">Website update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook-september-2015-update/">The Erlanger Playbook September 2015 Update</a></li> + + <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + - <li><a href="https://ninenines.eu/articles/erlanger-playbook/">The Erlanger Playbook</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-validate-utf8/">Validating UTF-8 binaries with Erlang</a></li> + + <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + - <li><a href="https://ninenines.eu/articles/on-open-source/">On open source</a></li> + + <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + - <li><a href="https://ninenines.eu/articles/the-story-so-far/">The story so far</a></li> + + <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + - <li><a href="https://ninenines.eu/articles/cowboy2-qs/">Cowboy 2.0 and query strings</a></li> + + <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + - <li><a href="https://ninenines.eu/articles/january-2014-status/">January 2014 status</a></li> + + <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + - <li><a href="https://ninenines.eu/articles/farwest-funded/">Farwest got funded!</a></li> + + <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + - <li><a href="https://ninenines.eu/articles/erlang.mk-and-relx/">Build Erlang releases with Erlang.mk and Relx</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.5-intermediate-module/">Xerl: intermediate module</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.4-expression-separator/">Xerl: expression separator</a></li> + + <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + - <li><a href="https://ninenines.eu/articles/erlang-scalability/">Erlang Scalability</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.3-atomic-expressions/">Xerl: atomic expressions</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.2-two-modules/">Xerl: two modules</a></li> + + <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + - <li><a href="https://ninenines.eu/articles/xerl-0.1-empty-modules/">Xerl: empty modules</a></li> + + <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + - <li><a href="https://ninenines.eu/articles/ranch-ftp/">Build an FTP Server with Ranch in 30 Minutes</a></li> + + <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + - <li><a href="https://ninenines.eu/articles/tictactoe/">Erlang Tic Tac Toe</a></li> + </ul> diff --git a/categories/index.html b/categories/index.html index 8c270718..f7aec9ba 100644 --- a/categories/index.html +++ b/categories/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Categories</title> diff --git a/categories/index.xml b/categories/index.xml new file mode 100644 index 00000000..28dfb867 --- /dev/null +++ b/categories/index.xml @@ -0,0 +1,14 @@ +<?xml version="1.0" encoding="utf-8" standalone="yes" ?> +<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"> + <channel> + <title>Categories on Nine Nines</title> + <link>https://ninenines.eu/categories/</link> + <description>Recent content in Categories on Nine Nines</description> + <generator>Hugo -- gohugo.io</generator> + <language>en-us</language> + + <atom:link href="https://ninenines.eu/categories/index.xml" rel="self" type="application/rss+xml" /> + + + </channel> +</rss>
\ No newline at end of file diff --git a/docs/en/cowboy/1.0/index.html b/docs/en/cowboy/1.0/index.html index d87c4243..0194031a 100644 --- a/docs/en/cowboy/1.0/index.html +++ b/docs/en/cowboy/1.0/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file diff --git a/docs/en/cowboy/2.0/guide/constraints/index.html b/docs/en/cowboy/2.0/guide/constraints/index.html index 110adf07..570f49fe 100644 --- a/docs/en/cowboy/2.0/guide/constraints/index.html +++ b/docs/en/cowboy/2.0/guide/constraints/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Constraints</title> @@ -67,147 +67,150 @@ <h1 class="lined-header"><span>Constraints</span></h1> -<div class="paragraph"><p>Constraints are validation and conversion functions applied
-to user input.</p></div>
-<div class="paragraph"><p>They are used in various places in Cowboy, including the
-router and the <code>cowboy_req</code> match functions.</p></div>
-<div class="sect1">
-<h2 id="_syntax">Syntax</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Constraints are provided as a list of fields. For each field
-in the list, specific constraints can be applied, as well as
-a default value if the field is missing.</p></div>
-<div class="paragraph"><p>A field can take the form of an atom <code>field</code>, a tuple with
-constraints <code>{field, Constraints}</code> or a tuple with constraints
-and a default value <code>{field, Constraints, Default}</code>.
-The <code>field</code> form indicates the field is mandatory.</p></div>
-<div class="paragraph"><p>Note that when used with the router, only the second form
-makes sense, as it does not use the default and the field
-is always defined.</p></div>
-<div class="paragraph"><p>Constraints for each field are provided as an ordered list
-of atoms or funs to apply. Built-in constraints are provided
-as atoms, while custom constraints are provided as funs.</p></div>
-<div class="paragraph"><p>When multiple constraints are provided, they are applied in
-the order given. If the value has been modified by a constraint
-then the next one receives the new value.</p></div>
-<div class="paragraph"><p>For example, the following constraints will first validate
-and convert the field <code>my_value</code> to an integer, and then
-check that the integer is positive:</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">PositiveFun</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>
- (<span style="color: #990000">_</span>, <span style="color: #009900">V</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">V</span> <span style="color: #990000">></span> <span style="color: #993399">0</span> <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">V</span>};
- (<span style="color: #990000">_</span>, <span style="color: #990000">_</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">not_positive</span>}
-<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>,
-{<span style="color: #FF6600">my_value</span>, [<span style="color: #FF6600">int</span>, <span style="color: #009900">PositiveFun</span>]}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>We ignore the first fun argument in this snippet. We shouldn’t.
-We will simply learn what it is later in this chapter.</p></div>
-<div class="paragraph"><p>When there’s only one constraint, it can be provided directly
-without wrapping it into a list:</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">my_value</span>, <span style="color: #FF6600">int</span>}</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_built_in_constraints">Built-in constraints</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Built-in constraints are specified as an atom:</p></div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="border"
-cellspacing="0" cellpadding="4">
-<col width="50%" />
-<col width="50%" />
-<thead>
-<tr>
-<th align="left" valign="top"> Constraint </th>
-<th align="left" valign="top"> Description</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table">int</p></td>
-<td align="left" valign="top"><p class="table">Converts binary value to integer.</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">nonempty</p></td>
-<td align="left" valign="top"><p class="table">Ensures the binary value is non-empty.</p></td>
-</tr>
-</tbody>
-</table>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_custom_constraints">Custom constraints</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Custom constraints are specified as a fun. This fun takes
-two arguments. The first argument indicates the operation
-to be performed, and the second is the value. What the
-value is and what must be returned depends on the operation.</p></div>
-<div class="paragraph"><p>Cowboy currently defines three operations. The operation
-used for validating and converting user input is the <code>forward</code>
-operation.</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">int</span></span>(<span style="color: #FF6600">forward</span>, <span style="color: #009900">Value</span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #0000FF">try</span></span>
- {<span style="color: #FF6600">ok</span>, <span style="font-weight: bold"><span style="color: #000000">binary_to_integer</span></span>(<span style="color: #009900">Value</span>)}
- <span style="font-weight: bold"><span style="color: #0000FF">catch</span></span> <span style="color: #990000">_:_</span> <span style="color: #990000">-></span>
- {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">not_an_integer</span>}
- <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>;</tt></pre></div></div>
-<div class="paragraph"><p>The value must be returned even if it is not converted
-by the constraint.</p></div>
-<div class="paragraph"><p>The <code>reverse</code> operation does the opposite: it
-takes a converted value and changes it back to what the
-user input would have been.</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">int</span></span>(<span style="color: #FF6600">reverse</span>, <span style="color: #009900">Value</span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #0000FF">try</span></span>
- {<span style="color: #FF6600">ok</span>, <span style="font-weight: bold"><span style="color: #000000">integer_to_binary</span></span>(<span style="color: #009900">Value</span>)}
- <span style="font-weight: bold"><span style="color: #0000FF">catch</span></span> <span style="color: #990000">_:_</span> <span style="color: #990000">-></span>
- {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">not_an_integer</span>}
- <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>;</tt></pre></div></div>
-<div class="paragraph"><p>Finally, the <code>format_error</code> operation takes an error
-returned by any other operation and returns a formatted
-human-readable error message.</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">int</span></span>(<span style="color: #FF6600">format_error</span>, {<span style="color: #FF6600">not_an_integer</span>, <span style="color: #009900">Value</span>}) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">io_lib:format</span></span>(<span style="color: #FF0000">"The value ~p is not an integer."</span>, [<span style="color: #009900">Value</span>])<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Notice that for this case you get both the error and
-the value that was given to the constraint that produced
-this error.</p></div>
-<div class="paragraph"><p>Cowboy will not catch exceptions coming from constraint
-functions. They should be written to not emit any exceptions.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Constraints are validation and conversion functions applied +to user input.</p></div> +<div class="paragraph"><p>They are used in various places in Cowboy, including the +router and the <code>cowboy_req</code> match functions.</p></div> +<div class="sect1"> +<h2 id="_syntax">Syntax</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Constraints are provided as a list of fields. For each field +in the list, specific constraints can be applied, as well as +a default value if the field is missing.</p></div> +<div class="paragraph"><p>A field can take the form of an atom <code>field</code>, a tuple with +constraints <code>{field, Constraints}</code> or a tuple with constraints +and a default value <code>{field, Constraints, Default}</code>. +The <code>field</code> form indicates the field is mandatory.</p></div> +<div class="paragraph"><p>Note that when used with the router, only the second form +makes sense, as it does not use the default and the field +is always defined.</p></div> +<div class="paragraph"><p>Constraints for each field are provided as an ordered list +of atoms or funs to apply. Built-in constraints are provided +as atoms, while custom constraints are provided as funs.</p></div> +<div class="paragraph"><p>When multiple constraints are provided, they are applied in +the order given. If the value has been modified by a constraint +then the next one receives the new value.</p></div> +<div class="paragraph"><p>For example, the following constraints will first validate +and convert the field <code>my_value</code> to an integer, and then +check that the integer is positive:</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">PositiveFun</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span> + (<span style="color: #990000">_</span>, <span style="color: #009900">V</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">V</span> <span style="color: #990000">></span> <span style="color: #993399">0</span> <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">V</span>}; + (<span style="color: #990000">_</span>, <span style="color: #990000">_</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">not_positive</span>} +<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>, +{<span style="color: #FF6600">my_value</span>, [<span style="color: #FF6600">int</span>, <span style="color: #009900">PositiveFun</span>]}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>We ignore the first fun argument in this snippet. We shouldn’t. +We will simply learn what it is later in this chapter.</p></div> +<div class="paragraph"><p>When there’s only one constraint, it can be provided directly +without wrapping it into a list:</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">my_value</span>, <span style="color: #FF6600">int</span>}</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_built_in_constraints">Built-in constraints</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Built-in constraints are specified as an atom:</p></div> +<div class="tableblock"> +<table rules="all" +width="100%" +frame="border" +cellspacing="0" cellpadding="4"> +<col width="50%" /> +<col width="50%" /> +<thead> +<tr> +<th align="left" valign="top"> Constraint </th> +<th align="left" valign="top"> Description</th> +</tr> +</thead> +<tbody> +<tr> +<td align="left" valign="top"><p class="table">int</p></td> +<td align="left" valign="top"><p class="table">Converts binary value to integer.</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">nonempty</p></td> +<td align="left" valign="top"><p class="table">Ensures the binary value is non-empty.</p></td> +</tr> +</tbody> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_custom_constraints">Custom constraints</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Custom constraints are specified as a fun. This fun takes +two arguments. The first argument indicates the operation +to be performed, and the second is the value. What the +value is and what must be returned depends on the operation.</p></div> +<div class="paragraph"><p>Cowboy currently defines three operations. The operation +used for validating and converting user input is the <code>forward</code> +operation.</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">int</span></span>(<span style="color: #FF6600">forward</span>, <span style="color: #009900">Value</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #0000FF">try</span></span> + {<span style="color: #FF6600">ok</span>, <span style="font-weight: bold"><span style="color: #000000">binary_to_integer</span></span>(<span style="color: #009900">Value</span>)} + <span style="font-weight: bold"><span style="color: #0000FF">catch</span></span> <span style="color: #990000">_:_</span> <span style="color: #990000">-></span> + {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">not_an_integer</span>} + <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>;</tt></pre></div></div> +<div class="paragraph"><p>The value must be returned even if it is not converted +by the constraint.</p></div> +<div class="paragraph"><p>The <code>reverse</code> operation does the opposite: it +takes a converted value and changes it back to what the +user input would have been.</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">int</span></span>(<span style="color: #FF6600">reverse</span>, <span style="color: #009900">Value</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #0000FF">try</span></span> + {<span style="color: #FF6600">ok</span>, <span style="font-weight: bold"><span style="color: #000000">integer_to_binary</span></span>(<span style="color: #009900">Value</span>)} + <span style="font-weight: bold"><span style="color: #0000FF">catch</span></span> <span style="color: #990000">_:_</span> <span style="color: #990000">-></span> + {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">not_an_integer</span>} + <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>;</tt></pre></div></div> +<div class="paragraph"><p>Finally, the <code>format_error</code> operation takes an error +returned by any other operation and returns a formatted +human-readable error message.</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">int</span></span>(<span style="color: #FF6600">format_error</span>, {<span style="color: #FF6600">not_an_integer</span>, <span style="color: #009900">Value</span>}) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">io_lib:format</span></span>(<span style="color: #FF0000">"The value ~p is not an integer."</span>, [<span style="color: #009900">Value</span>])<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Notice that for this case you get both the error and +the value that was given to the constraint that produced +this error.</p></div> +<div class="paragraph"><p>Cowboy will not catch exceptions coming from constraint +functions. They should be written to not emit any exceptions.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/cookies/index.html b/docs/en/cowboy/2.0/guide/cookies/index.html index c81cc17c..fe40ca87 100644 --- a/docs/en/cowboy/2.0/guide/cookies/index.html +++ b/docs/en/cowboy/2.0/guide/cookies/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Using cookies</title> @@ -67,150 +67,153 @@ <h1 class="lined-header"><span>Using cookies</span></h1> -<div class="paragraph"><p>Cookies are a mechanism allowing applications to maintain
-state on top of the stateless HTTP protocol.</p></div>
-<div class="paragraph"><p>Cookies are a name/value store where the names and values are
-stored in plain text. They expire either after a delay
-or when the browser closes. They can be configured on a
-specific domain name or path, and restricted to secure
-resources (sent or downloaded over HTTPS), or restricted
-to the server (disallowing access from client-side scripts).</p></div>
-<div class="paragraph"><p>Cookie names are de facto case sensitive.</p></div>
-<div class="paragraph"><p>Cookies are stored client-side and sent with every subsequent
-request that matches the domain and path for which they were
-stored, until they expire. This can create a non-negligible
-cost.</p></div>
-<div class="paragraph"><p>Cookies should not be considered secure. They are stored on
-the user’s computer in plain text, and can be read by any
-program. They can also be read by proxies when using clear
-connections. Always validate the value before using it,
-and never store any sensitive information inside it.</p></div>
-<div class="paragraph"><p>Cookies set by the server are only available in requests
-following the client reception of the response containing
-them.</p></div>
-<div class="paragraph"><p>Cookies may be sent repeatedly. This is often useful to
-update the expiration time and avoid losing a cookie.</p></div>
-<div class="sect1">
-<h2 id="_setting_cookies">Setting cookies</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>By default cookies are defined for the duration of the session:</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">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>They can also be set for a duration in 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: #009900">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>,
- #{<span style="color: #0000FF">max_age</span> <span style="color: #990000">=></span> <span style="color: #993399">3600</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>To delete cookies, set <code>max_age</code> to 0:</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">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>,
- #{<span style="color: #0000FF">max_age</span> <span style="color: #990000">=></span> <span style="color: #993399">0</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>To restrict cookies to a specific domain and path, the options
-of the same name can be used:</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"inaccount"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"1"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>,
- #{<span style="color: #0000FF">domain</span> <span style="color: #990000">=></span> <span style="color: #FF0000">"my.example.org"</span>, <span style="color: #0000FF">path</span> <span style="color: #990000">=></span> <span style="color: #FF0000">"/account"</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Cookies will be sent with requests to this domain and all
-its subdomains, and to resources on this path or deeper
-in the path hierarchy.</p></div>
-<div class="paragraph"><p>To restrict cookies to secure channels (typically resources
-available over HTTPS):</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">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>,
- #{<span style="color: #0000FF">secure</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>To prevent client-side scripts from accessing a cookie:</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">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>,
- #{<span style="color: #0000FF">http_only</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Cookies may also be set client-side, for example using
-Javascript.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_reading_cookies">Reading cookies</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The client only ever sends back the cookie name and value.
-All other options that can be set are never sent back.</p></div>
-<div class="paragraph"><p>Cowboy provides two functions for reading cookies. Both
-involve parsing the cookie header(s) and so should not
-be called repeatedly.</p></div>
-<div class="paragraph"><p>You can get all cookies as a key/value list:</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">Cookies</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_cookies</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">Cookies</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Or you can perform a match against cookies and retrieve
-only the ones you need, while at the same time doing
-any required post processing using <a href="../constraints">constraints</a>.
-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: #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_cookies</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> cookie is
-not an integer number or if the <code>lang</code> cookie is empty. Additionally
-the <code>id</code> cookie value 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">CookiesMap</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_cookies</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 if two cookies share the same name, then the map value
-will be a list of the two cookie values.</p></div>
-<div class="paragraph"><p>A default value can be provided. The default will be used
-if the <code>lang</code> cookie is not found. It will not be used if
-the cookie 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_cookies</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, an
-exception is thrown.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Cookies are a mechanism allowing applications to maintain +state on top of the stateless HTTP protocol.</p></div> +<div class="paragraph"><p>Cookies are a name/value store where the names and values are +stored in plain text. They expire either after a delay +or when the browser closes. They can be configured on a +specific domain name or path, and restricted to secure +resources (sent or downloaded over HTTPS), or restricted +to the server (disallowing access from client-side scripts).</p></div> +<div class="paragraph"><p>Cookie names are de facto case sensitive.</p></div> +<div class="paragraph"><p>Cookies are stored client-side and sent with every subsequent +request that matches the domain and path for which they were +stored, until they expire. This can create a non-negligible +cost.</p></div> +<div class="paragraph"><p>Cookies should not be considered secure. They are stored on +the user’s computer in plain text, and can be read by any +program. They can also be read by proxies when using clear +connections. Always validate the value before using it, +and never store any sensitive information inside it.</p></div> +<div class="paragraph"><p>Cookies set by the server are only available in requests +following the client reception of the response containing +them.</p></div> +<div class="paragraph"><p>Cookies may be sent repeatedly. This is often useful to +update the expiration time and avoid losing a cookie.</p></div> +<div class="sect1"> +<h2 id="_setting_cookies">Setting cookies</h2> +<div class="sectionbody"> +<div class="paragraph"><p>By default cookies are defined for the duration of the session:</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">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(), +<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>They can also be set for a duration in 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: #009900">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(), +<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>, + #{<span style="color: #0000FF">max_age</span> <span style="color: #990000">=></span> <span style="color: #993399">3600</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>To delete cookies, set <code>max_age</code> to 0:</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">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(), +<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>, + #{<span style="color: #0000FF">max_age</span> <span style="color: #990000">=></span> <span style="color: #993399">0</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>To restrict cookies to a specific domain and path, the options +of the same name can be used:</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"inaccount"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"1"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>, + #{<span style="color: #0000FF">domain</span> <span style="color: #990000">=></span> <span style="color: #FF0000">"my.example.org"</span>, <span style="color: #0000FF">path</span> <span style="color: #990000">=></span> <span style="color: #FF0000">"/account"</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Cookies will be sent with requests to this domain and all +its subdomains, and to resources on this path or deeper +in the path hierarchy.</p></div> +<div class="paragraph"><p>To restrict cookies to secure channels (typically resources +available over HTTPS):</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">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(), +<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>, + #{<span style="color: #0000FF">secure</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>To prevent client-side scripts from accessing a cookie:</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">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(), +<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>, + #{<span style="color: #0000FF">http_only</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Cookies may also be set client-side, for example using +Javascript.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_reading_cookies">Reading cookies</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The client only ever sends back the cookie name and value. +All other options that can be set are never sent back.</p></div> +<div class="paragraph"><p>Cowboy provides two functions for reading cookies. Both +involve parsing the cookie header(s) and so should not +be called repeatedly.</p></div> +<div class="paragraph"><p>You can get all cookies as a key/value list:</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">Cookies</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_cookies</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">Cookies</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Or you can perform a match against cookies and retrieve +only the ones you need, while at the same time doing +any required post processing using <a href="../constraints">constraints</a>. +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: #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_cookies</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> cookie is +not an integer number or if the <code>lang</code> cookie is empty. Additionally +the <code>id</code> cookie value 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">CookiesMap</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_cookies</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 if two cookies share the same name, then the map value +will be a list of the two cookie values.</p></div> +<div class="paragraph"><p>A default value can be provided. The default will be used +if the <code>lang</code> cookie is not found. It will not be used if +the cookie 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_cookies</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, an +exception is thrown.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> 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 c7e88684..accea26d 100644 --- a/docs/en/cowboy/2.0/guide/erlang_web/index.html +++ b/docs/en/cowboy/2.0/guide/erlang_web/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Erlang and the Web</title> @@ -67,200 +67,203 @@ <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">
-<div class="paragraph"><p>When you access a website there is little concurrency
-involved. A few connections are opened and requests
-are sent through these connections. Then the web page
-is displayed on your screen. Your browser will only
-open up to 4 or 8 connections to the server, depending
-on your settings. This isn’t much.</p></div>
-<div class="paragraph"><p>But think about it. You are not the only one accessing
-the server at the same time. There can be hundreds, if
-not thousands, if not millions of connections to the
-same server at the same time.</p></div>
-<div class="paragraph"><p>Even today a lot of systems used in production haven’t
-solved the C10K problem (ten thousand concurrent connections).
-And the ones who did are trying hard to get to the next
-step, C100K, and are pretty far from it.</p></div>
-<div class="paragraph"><p>Erlang meanwhile has no problem handling millions of
-connections. At the time of writing there are application
-servers written in Erlang that can handle more than two
-million connections on a single server in a real production
-application, with spare memory and CPU!</p></div>
-<div class="paragraph"><p>The Web is concurrent, and Erlang is a language designed
-for concurrency, so it is a perfect match.</p></div>
-<div class="paragraph"><p>Of course, various platforms need to scale beyond a few
-million connections. This is where Erlang’s built-in
-distribution mechanisms come in. If one server isn’t
-enough, add more! Erlang allows you to use the same code
-for talking to local processes or to processes in other
-parts of your cluster, which means you can scale very
-quickly if the need arises.</p></div>
-<div class="paragraph"><p>The Web has large userbases, and the Erlang platform was
-designed to work in a distributed setting, so it is a
-perfect match.</p></div>
-<div class="paragraph"><p>Or is it? Surely you can find solutions to handle that many
-concurrent connections with your favorite language… But all
-these solutions will break down in the next few years. Why?
-Firstly because servers don’t get any more powerful, they
-instead get a lot more cores and memory. This is only useful
-if your application can use them properly, and Erlang is
-light-years away from anything else in that area. Secondly,
-today your computer and your phone are online, tomorrow your
-watch, goggles, bike, car, fridge and tons of other devices
-will also connect to various applications on the Internet.</p></div>
-<div class="paragraph"><p>Only Erlang is prepared to deal with what’s coming.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_the_web_is_soft_real_time">The Web is soft real time</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>What does soft real time mean, you ask? It means we want the
-operations done as quickly as possible, and in the case of
-web applications, it means we want the data propagated fast.</p></div>
-<div class="paragraph"><p>In comparison, hard real time has a similar meaning, but also
-has a hard time constraint, for example an operation needs to
-be done in under N milliseconds otherwise the system fails
-entirely.</p></div>
-<div class="paragraph"><p>Users aren’t that needy yet, they just want to get access
-to their content in a reasonable delay, and they want the
-actions they make to register at most a few seconds after
-they submitted them, otherwise they’ll start worrying about
-whether it successfully went through.</p></div>
-<div class="paragraph"><p>The Web is soft real time because taking longer to perform an
-operation would be seen as bad quality of service.</p></div>
-<div class="paragraph"><p>Erlang is a soft real time system. It will always run
-processes fairly, a little at a time, switching to another
-process after a while and preventing a single process to
-steal resources from all others. This means that Erlang
-can guarantee stable low latency of operations.</p></div>
-<div class="paragraph"><p>Erlang provides the guarantees that the soft real time Web
-requires.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_the_web_is_asynchronous">The Web is asynchronous</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Long ago, the Web was synchronous because HTTP was synchronous.
-You fired a request, and then waited for a response. Not anymore.
-It all began when XmlHttpRequest started being used. It allowed
-the client to perform asynchronous calls to the server.</p></div>
-<div class="paragraph"><p>Then Websocket appeared and allowed both the server and the client
-to send data to the other endpoint completely asynchronously. The
-data is contained within frames and no response is necessary.</p></div>
-<div class="paragraph"><p>Erlang processes work the same. They send each other data contained
-within messages and then continue running without needing a response.
-They tend to spend most of their time inactive, waiting for a new
-message, and the Erlang VM happily activate them when one is received.</p></div>
-<div class="paragraph"><p>It is therefore quite easy to imagine Erlang being good at receiving
-Websocket frames, which may come in at unpredictable times, pass the
-data to the responsible processes which are always ready waiting for
-new messages, and perform the operations required by only activating
-the required parts of the system.</p></div>
-<div class="paragraph"><p>The more recent Web technologies, like Websocket of course, but also
-HTTP/2.0, are all fully asynchronous protocols. The concept
-of requests and responses is retained of course, but anything could
-be sent in between, by both the client or the browser, and the
-responses could also be received in a completely different order.</p></div>
-<div class="paragraph"><p>Erlang is by nature asynchronous and really good at it thanks to the
-great engineering that has been done in the VM over the years. It’s
-only natural that it’s so good at dealing with the asynchronous Web.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_the_web_is_omnipresent">The Web is omnipresent</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The Web has taken a very important part of our lives. We’re
-connected at all times, when we’re on our phone, using our computer,
-passing time using a tablet while in the bathroom… And this
-isn’t going to slow down, every single device at home or on us
-will be connected.</p></div>
-<div class="paragraph"><p>All these devices are always connected. And with the number of
-alternatives to give you access to the content you seek, users
-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 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
-of reality in a long time, and are drifting further away as
-time goes on.</p></div>
-<div class="paragraph"><p>What developers should really ask themselves is "Can I service
-all my users with no interruption?" and they’d find that they have
-two choices. They can either hope for the best, or they can use
-Erlang.</p></div>
-<div class="paragraph"><p>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 happens,
-the Erlang process crashes and is then restarted by a special
-process called a supervisor.</p></div>
-<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 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>
-<div class="paragraph"><p>The second piece is Erlang’s built-in distribution. Distribution
-is a key part of building a fault tolerant system, because it
-allows you to handle bigger failures, like a whole server going
-down, or even a data center entirely.</p></div>
-<div class="paragraph"><p>Fault tolerance and distribution are important today, and will be
-vital in the future of the Web. Erlang is ready.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_learn_erlang">Learn Erlang</h2>
-<div class="sectionbody">
-<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>
+<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"> +<div class="paragraph"><p>When you access a website there is little concurrency +involved. A few connections are opened and requests +are sent through these connections. Then the web page +is displayed on your screen. Your browser will only +open up to 4 or 8 connections to the server, depending +on your settings. This isn’t much.</p></div> +<div class="paragraph"><p>But think about it. You are not the only one accessing +the server at the same time. There can be hundreds, if +not thousands, if not millions of connections to the +same server at the same time.</p></div> +<div class="paragraph"><p>Even today a lot of systems used in production haven’t +solved the C10K problem (ten thousand concurrent connections). +And the ones who did are trying hard to get to the next +step, C100K, and are pretty far from it.</p></div> +<div class="paragraph"><p>Erlang meanwhile has no problem handling millions of +connections. At the time of writing there are application +servers written in Erlang that can handle more than two +million connections on a single server in a real production +application, with spare memory and CPU!</p></div> +<div class="paragraph"><p>The Web is concurrent, and Erlang is a language designed +for concurrency, so it is a perfect match.</p></div> +<div class="paragraph"><p>Of course, various platforms need to scale beyond a few +million connections. This is where Erlang’s built-in +distribution mechanisms come in. If one server isn’t +enough, add more! Erlang allows you to use the same code +for talking to local processes or to processes in other +parts of your cluster, which means you can scale very +quickly if the need arises.</p></div> +<div class="paragraph"><p>The Web has large userbases, and the Erlang platform was +designed to work in a distributed setting, so it is a +perfect match.</p></div> +<div class="paragraph"><p>Or is it? Surely you can find solutions to handle that many +concurrent connections with your favorite language… But all +these solutions will break down in the next few years. Why? +Firstly because servers don’t get any more powerful, they +instead get a lot more cores and memory. This is only useful +if your application can use them properly, and Erlang is +light-years away from anything else in that area. Secondly, +today your computer and your phone are online, tomorrow your +watch, goggles, bike, car, fridge and tons of other devices +will also connect to various applications on the Internet.</p></div> +<div class="paragraph"><p>Only Erlang is prepared to deal with what’s coming.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_the_web_is_soft_real_time">The Web is soft real time</h2> +<div class="sectionbody"> +<div class="paragraph"><p>What does soft real time mean, you ask? It means we want the +operations done as quickly as possible, and in the case of +web applications, it means we want the data propagated fast.</p></div> +<div class="paragraph"><p>In comparison, hard real time has a similar meaning, but also +has a hard time constraint, for example an operation needs to +be done in under N milliseconds otherwise the system fails +entirely.</p></div> +<div class="paragraph"><p>Users aren’t that needy yet, they just want to get access +to their content in a reasonable delay, and they want the +actions they make to register at most a few seconds after +they submitted them, otherwise they’ll start worrying about +whether it successfully went through.</p></div> +<div class="paragraph"><p>The Web is soft real time because taking longer to perform an +operation would be seen as bad quality of service.</p></div> +<div class="paragraph"><p>Erlang is a soft real time system. It will always run +processes fairly, a little at a time, switching to another +process after a while and preventing a single process to +steal resources from all others. This means that Erlang +can guarantee stable low latency of operations.</p></div> +<div class="paragraph"><p>Erlang provides the guarantees that the soft real time Web +requires.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_the_web_is_asynchronous">The Web is asynchronous</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Long ago, the Web was synchronous because HTTP was synchronous. +You fired a request, and then waited for a response. Not anymore. +It all began when XmlHttpRequest started being used. It allowed +the client to perform asynchronous calls to the server.</p></div> +<div class="paragraph"><p>Then Websocket appeared and allowed both the server and the client +to send data to the other endpoint completely asynchronously. The +data is contained within frames and no response is necessary.</p></div> +<div class="paragraph"><p>Erlang processes work the same. They send each other data contained +within messages and then continue running without needing a response. +They tend to spend most of their time inactive, waiting for a new +message, and the Erlang VM happily activate them when one is received.</p></div> +<div class="paragraph"><p>It is therefore quite easy to imagine Erlang being good at receiving +Websocket frames, which may come in at unpredictable times, pass the +data to the responsible processes which are always ready waiting for +new messages, and perform the operations required by only activating +the required parts of the system.</p></div> +<div class="paragraph"><p>The more recent Web technologies, like Websocket of course, but also +HTTP/2.0, are all fully asynchronous protocols. The concept +of requests and responses is retained of course, but anything could +be sent in between, by both the client or the browser, and the +responses could also be received in a completely different order.</p></div> +<div class="paragraph"><p>Erlang is by nature asynchronous and really good at it thanks to the +great engineering that has been done in the VM over the years. It’s +only natural that it’s so good at dealing with the asynchronous Web.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_the_web_is_omnipresent">The Web is omnipresent</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The Web has taken a very important part of our lives. We’re +connected at all times, when we’re on our phone, using our computer, +passing time using a tablet while in the bathroom… And this +isn’t going to slow down, every single device at home or on us +will be connected.</p></div> +<div class="paragraph"><p>All these devices are always connected. And with the number of +alternatives to give you access to the content you seek, users +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 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 +of reality in a long time, and are drifting further away as +time goes on.</p></div> +<div class="paragraph"><p>What developers should really ask themselves is "Can I service +all my users with no interruption?" and they’d find that they have +two choices. They can either hope for the best, or they can use +Erlang.</p></div> +<div class="paragraph"><p>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 happens, +the Erlang process crashes and is then restarted by a special +process called a supervisor.</p></div> +<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 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> +<div class="paragraph"><p>The second piece is Erlang’s built-in distribution. Distribution +is a key part of building a fault tolerant system, because it +allows you to handle bigger failures, like a whole server going +down, or even a data center entirely.</p></div> +<div class="paragraph"><p>Fault tolerance and distribution are important today, and will be +vital in the future of the Web. Erlang is ready.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_learn_erlang">Learn Erlang</h2> +<div class="sectionbody"> +<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> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/flow_diagram/index.html b/docs/en/cowboy/2.0/guide/flow_diagram/index.html index 72e78d28..679ee0b1 100644 --- a/docs/en/cowboy/2.0/guide/flow_diagram/index.html +++ b/docs/en/cowboy/2.0/guide/flow_diagram/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Flow diagram</title> @@ -67,119 +67,122 @@ <h1 class="lined-header"><span>Flow diagram</span></h1> -<div class="paragraph"><p>Cowboy is a lightweight HTTP server with support for HTTP/1.1,
-HTTP/2 and Websocket.</p></div>
-<div class="paragraph"><p>It is built on top of Ranch. Please see the Ranch guide for more
-information about how the network connections are handled.</p></div>
-<div class="sect1">
-<h2 id="_overview">Overview</h2>
-<div class="sectionbody">
-<div class="imageblock">
-<div class="content">
-<img src="../http_req_resp.png" alt="HTTP request/response flowchart" />
-</div>
-</div>
-<div class="paragraph"><p>As you can see on the diagram, the client
-begins by connecting to the server. This step is handled
-by a Ranch acceptor, which is a process dedicated to
-accepting new connections.</p></div>
-<div class="paragraph"><p>After Ranch accepts a new connection, whether it is an
-HTTP/1.1 or HTTP/2 connection, Cowboy starts receiving
-requests and handling them.</p></div>
-<div class="paragraph"><p>In HTTP/1.1 all requests come sequentially. In HTTP/2
-the requests may arrive and be processed concurrently.</p></div>
-<div class="paragraph"><p>When a request comes in, Cowboy creates a stream, which
-is a set of request/response and all the events associated
-with them. The protocol code in Cowboy defers the handling
-of these streams to stream handler modules. When you
-configure Cowboy you may define one or more module that
-will receive all events associated with a stream, including
-the request, response, bodies, Erlang messages and more.</p></div>
-<div class="paragraph"><p>By default Cowboy comes configured with a stream handler
-called <code>cowboy_stream_h</code>. This stream handler will create
-a new process for every request coming in, and then
-communicate with this process to read the body or send
-a response back. The request process executes middlewares
-which, by default, including the router and then the
-execution of handlers. Like stream handlers, middlewares
-may also be customized.</p></div>
-<div class="paragraph"><p>A response may be sent at almost any point in this
-diagram. If the response must be sent before the stream
-is initialized (because an error occurred early, for
-example) then stream handlers receive a special event
-indicating this error.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_protocol_specific_headers">Protocol-specific headers</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy takes care of protocol-specific headers and prevents
-you from sending them manually. For HTTP/1.1 this includes
-the <code>transfer-encoding</code> and <code>connection</code> headers. For HTTP/2
-this includes the colon headers like <code>:status</code>.</p></div>
-<div class="paragraph"><p>Cowboy will also remove protocol-specific headers from
-requests before passing them to stream handlers. Cowboy
-tries to hide the implementation details of all protocols
-as well as possible.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_number_of_processes_per_connection">Number of processes per connection</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>By default, Cowboy will use one process per connection,
-plus one process per set of request/response (called a
-stream, internally).</p></div>
-<div class="paragraph"><p>The reason it creates a new process for every request is due
-to the requirements of HTTP/2 where requests are executed
-concurrently and independently from the connection. The
-frames from the different requests end up interleaved on
-the single TCP connection.</p></div>
-<div class="paragraph"><p>The request processes are never reused. There is therefore
-no need to perform any cleanup after the response has been
-sent. The process will terminate and Erlang/OTP will reclaim
-all memory at once.</p></div>
-<div class="paragraph"><p>Cowboy ultimately does not require more than one process
-per connection. It is possible to interact with the connection
-directly from a stream handler, a low level interface to Cowboy.
-They are executed from within the connection process, and can
-handle the incoming requests and send responses. This is however
-not recommended in normal circumstances, as a stream handler
-taking too long to execute could have a negative impact on
-concurrent requests or the state of the connection itself.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_date_header">Date header</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Because querying for the current date and time can be expensive,
-Cowboy generates one <em>Date</em> header value every second, shares it
-to all other processes, which then simply copy it in the response.
-This allows compliance with HTTP/1.1 with no actual performance loss.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_binaries">Binaries</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy makes extensive use of binaries.</p></div>
-<div class="paragraph"><p>Binaries are more efficient than lists for representing
-strings because they take less memory space. Processing
-performance can vary depending on the operation. Binaries
-are known for generally getting a great boost if the code
-is compiled natively. Please see the HiPE documentation
-for more details.</p></div>
-<div class="paragraph"><p>Binaries may end up being shared between processes. This
-can lead to some large memory usage when one process keeps
-the binary data around forever without freeing it. If you
-see some weird memory usage in your application, this might
-be the cause.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Cowboy is a lightweight HTTP server with support for HTTP/1.1, +HTTP/2 and Websocket.</p></div> +<div class="paragraph"><p>It is built on top of Ranch. Please see the Ranch guide for more +information about how the network connections are handled.</p></div> +<div class="sect1"> +<h2 id="_overview">Overview</h2> +<div class="sectionbody"> +<div class="imageblock"> +<div class="content"> +<img src="../http_req_resp.png" alt="HTTP request/response flowchart" /> +</div> +</div> +<div class="paragraph"><p>As you can see on the diagram, the client +begins by connecting to the server. This step is handled +by a Ranch acceptor, which is a process dedicated to +accepting new connections.</p></div> +<div class="paragraph"><p>After Ranch accepts a new connection, whether it is an +HTTP/1.1 or HTTP/2 connection, Cowboy starts receiving +requests and handling them.</p></div> +<div class="paragraph"><p>In HTTP/1.1 all requests come sequentially. In HTTP/2 +the requests may arrive and be processed concurrently.</p></div> +<div class="paragraph"><p>When a request comes in, Cowboy creates a stream, which +is a set of request/response and all the events associated +with them. The protocol code in Cowboy defers the handling +of these streams to stream handler modules. When you +configure Cowboy you may define one or more module that +will receive all events associated with a stream, including +the request, response, bodies, Erlang messages and more.</p></div> +<div class="paragraph"><p>By default Cowboy comes configured with a stream handler +called <code>cowboy_stream_h</code>. This stream handler will create +a new process for every request coming in, and then +communicate with this process to read the body or send +a response back. The request process executes middlewares +which, by default, including the router and then the +execution of handlers. Like stream handlers, middlewares +may also be customized.</p></div> +<div class="paragraph"><p>A response may be sent at almost any point in this +diagram. If the response must be sent before the stream +is initialized (because an error occurred early, for +example) then stream handlers receive a special event +indicating this error.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_protocol_specific_headers">Protocol-specific headers</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy takes care of protocol-specific headers and prevents +you from sending them manually. For HTTP/1.1 this includes +the <code>transfer-encoding</code> and <code>connection</code> headers. For HTTP/2 +this includes the colon headers like <code>:status</code>.</p></div> +<div class="paragraph"><p>Cowboy will also remove protocol-specific headers from +requests before passing them to stream handlers. Cowboy +tries to hide the implementation details of all protocols +as well as possible.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_number_of_processes_per_connection">Number of processes per connection</h2> +<div class="sectionbody"> +<div class="paragraph"><p>By default, Cowboy will use one process per connection, +plus one process per set of request/response (called a +stream, internally).</p></div> +<div class="paragraph"><p>The reason it creates a new process for every request is due +to the requirements of HTTP/2 where requests are executed +concurrently and independently from the connection. The +frames from the different requests end up interleaved on +the single TCP connection.</p></div> +<div class="paragraph"><p>The request processes are never reused. There is therefore +no need to perform any cleanup after the response has been +sent. The process will terminate and Erlang/OTP will reclaim +all memory at once.</p></div> +<div class="paragraph"><p>Cowboy ultimately does not require more than one process +per connection. It is possible to interact with the connection +directly from a stream handler, a low level interface to Cowboy. +They are executed from within the connection process, and can +handle the incoming requests and send responses. This is however +not recommended in normal circumstances, as a stream handler +taking too long to execute could have a negative impact on +concurrent requests or the state of the connection itself.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_date_header">Date header</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Because querying for the current date and time can be expensive, +Cowboy generates one <em>Date</em> header value every second, shares it +to all other processes, which then simply copy it in the response. +This allows compliance with HTTP/1.1 with no actual performance loss.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_binaries">Binaries</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy makes extensive use of binaries.</p></div> +<div class="paragraph"><p>Binaries are more efficient than lists for representing +strings because they take less memory space. Processing +performance can vary depending on the operation. Binaries +are known for generally getting a great boost if the code +is compiled natively. Please see the HiPE documentation +for more details.</p></div> +<div class="paragraph"><p>Binaries may end up being shared between processes. This +can lead to some large memory usage when one process keeps +the binary data around forever without freeing it. If you +see some weird memory usage in your application, this might +be the cause.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> 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 24cd3c71..9ec1da90 100644 --- a/docs/en/cowboy/2.0/guide/getting_started/index.html +++ b/docs/en/cowboy/2.0/guide/getting_started/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Getting started</title> @@ -67,167 +67,170 @@ <h1 class="lined-header"><span>Getting started</span></h1> -<div class="paragraph"><p>Erlang is more than a language, it is also an operating system
-for your applications. Erlang developers rarely write standalone
-modules, they write libraries or applications, and then bundle
-those into what is called a release. A release contains the
-Erlang VM plus all applications required to run the node, so
-it can be pushed to production directly.</p></div>
-<div class="paragraph"><p>This chapter walks you through all the steps of setting up
-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="_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. 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
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt>$ mkdir hello_erlang
-$ cd hello_erlang</tt></pre></div></div>
-<div class="paragraph"><p>Then we need to download Erlang.mk. Either use the following
-command or download it manually.</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>$ 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">
-<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 -f erlang<span style="color: #990000">.</span>mk bootstrap bootstrap-rel</tt></pre></div></div>
-<div class="paragraph"><p>This creates a Makefile, a base application, and the release files
-necessary for creating the release. We can already build and start
-this 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>$ make run
-<span style="color: #990000">...</span>
-<span style="color: #990000">(</span>hello_erlang@<span style="color: #993399">127.0</span><span style="color: #990000">.</span><span style="color: #993399">0.1</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>Entering the command <code>i().</code> will show the running processes, including
-one called <code>hello_erlang_sup</code>. This is the supervisor for our
-application.</p></div>
-<div class="paragraph"><p>The release currently does nothing. In the rest of this chapter we
-will add Cowboy as a dependency and write a simple "Hello world!"
-handler.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_cowboy_setup">Cowboy setup</h2>
-<div class="sectionbody">
-<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
-
-<span style="color: #009900">DEP_PLUGINS =</span> cowboy
-
-include erlang.mk</tt></pre></div></div>
-<div class="paragraph"><p>We also tell the build system to load the plugins Cowboy provides.
-These include predefined templates that we will use soon.</p></div>
-<div class="paragraph"><p>If you do <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
-listen for connections.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_listening_for_connections">Listening for connections</h2>
-<div class="sectionbody">
-<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">
-<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">start</span></span>(<span style="color: #009900">_Type</span>, <span style="color: #009900">_Args</span>) <span style="color: #990000">-></span>
- <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_clear</span></span>(<span style="color: #FF6600">my_http_listener</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>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>
-</div>
-<div class="sect1">
-<h2 id="_handling_requests">Handling requests</h2>
-<div class="sectionbody">
-<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>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<span style="color: #990000">.</span>http <span style="color: #009900">n</span><span style="color: #990000">=</span>hello_handler</tt></pre></div></div>
-<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">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">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 200 OK reply, with the
-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>
-</div>
-</div>
+<div class="paragraph"><p>Erlang is more than a language, it is also an operating system +for your applications. Erlang developers rarely write standalone +modules, they write libraries or applications, and then bundle +those into what is called a release. A release contains the +Erlang VM plus all applications required to run the node, so +it can be pushed to production directly.</p></div> +<div class="paragraph"><p>This chapter walks you through all the steps of setting up +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="_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. 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 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt>$ mkdir hello_erlang +$ cd hello_erlang</tt></pre></div></div> +<div class="paragraph"><p>Then we need to download Erlang.mk. Either use the following +command or download it manually.</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>$ 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"> +<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 -f erlang<span style="color: #990000">.</span>mk bootstrap bootstrap-rel</tt></pre></div></div> +<div class="paragraph"><p>This creates a Makefile, a base application, and the release files +necessary for creating the release. We can already build and start +this 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>$ make run +<span style="color: #990000">...</span> +<span style="color: #990000">(</span>hello_erlang@<span style="color: #993399">127.0</span><span style="color: #990000">.</span><span style="color: #993399">0.1</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>Entering the command <code>i().</code> will show the running processes, including +one called <code>hello_erlang_sup</code>. This is the supervisor for our +application.</p></div> +<div class="paragraph"><p>The release currently does nothing. In the rest of this chapter we +will add Cowboy as a dependency and write a simple "Hello world!" +handler.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_cowboy_setup">Cowboy setup</h2> +<div class="sectionbody"> +<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 + +<span style="color: #009900">DEP_PLUGINS =</span> cowboy + +include erlang.mk</tt></pre></div></div> +<div class="paragraph"><p>We also tell the build system to load the plugins Cowboy provides. +These include predefined templates that we will use soon.</p></div> +<div class="paragraph"><p>If you do <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 +listen for connections.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_listening_for_connections">Listening for connections</h2> +<div class="sectionbody"> +<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"> +<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">start</span></span>(<span style="color: #009900">_Type</span>, <span style="color: #009900">_Args</span>) <span style="color: #990000">-></span> + <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_clear</span></span>(<span style="color: #FF6600">my_http_listener</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>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> +</div> +<div class="sect1"> +<h2 id="_handling_requests">Handling requests</h2> +<div class="sectionbody"> +<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>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<span style="color: #990000">.</span>http <span style="color: #009900">n</span><span style="color: #990000">=</span>hello_handler</tt></pre></div></div> +<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">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">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 200 OK reply, with the +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> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/handlers/index.html b/docs/en/cowboy/2.0/guide/handlers/index.html index dbb50c85..33cd53e2 100644 --- a/docs/en/cowboy/2.0/guide/handlers/index.html +++ b/docs/en/cowboy/2.0/guide/handlers/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Handlers</title> @@ -67,97 +67,100 @@ <h1 class="lined-header"><span>Handlers</span></h1> -<div class="paragraph"><p>Handlers are Erlang modules that handle HTTP requests.</p></div>
-<div class="sect1">
-<h2 id="_plain_http_handlers">Plain HTTP handlers</h2>
-<div class="sectionbody">
-<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 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">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 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">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 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
-and rarely used <code>terminate/3</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_other_handlers">Other handlers</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>init/2</code> callback can also be used to inform Cowboy
-that this is a different kind of handler and that Cowboy
-should switch to it. To do this you simply need to return
-the module name of the handler type you want to switch to.</p></div>
-<div class="paragraph"><p>Cowboy comes with three handler types you can switch to:
-<a href="../rest_handlers">cowboy_rest</a>, <a href="#ws_handlers">cowboy_websocket</a>
-and <a href="../loop_handlers">cowboy_loop</a>. In addition to those you
-can define your own handler types.</p></div>
-<div class="paragraph"><p>Switching is simple. Instead of returning <code>ok</code>, you simply
-return the name of the handler type you want to use. The
-following snippet switches to a Websocket handler:</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">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>
-</div>
-<div class="sect1">
-<h2 id="_cleaning_up">Cleaning up</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>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>
- <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>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>
+<div class="paragraph"><p>Handlers are Erlang modules that handle HTTP requests.</p></div> +<div class="sect1"> +<h2 id="_plain_http_handlers">Plain HTTP handlers</h2> +<div class="sectionbody"> +<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 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">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 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">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 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 +and rarely used <code>terminate/3</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_other_handlers">Other handlers</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>init/2</code> callback can also be used to inform Cowboy +that this is a different kind of handler and that Cowboy +should switch to it. To do this you simply need to return +the module name of the handler type you want to switch to.</p></div> +<div class="paragraph"><p>Cowboy comes with three handler types you can switch to: +<a href="../rest_handlers">cowboy_rest</a>, <a href="#ws_handlers">cowboy_websocket</a> +and <a href="../loop_handlers">cowboy_loop</a>. In addition to those you +can define your own handler types.</p></div> +<div class="paragraph"><p>Switching is simple. Instead of returning <code>ok</code>, you simply +return the name of the handler type you want to use. The +following snippet switches to a Websocket handler:</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">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> +</div> +<div class="sect1"> +<h2 id="_cleaning_up">Cleaning up</h2> +<div class="sectionbody"> +<div class="paragraph"><p>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> + <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>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> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/index.html b/docs/en/cowboy/2.0/guide/index.html index 4932891e..533d8db1 100644 --- a/docs/en/cowboy/2.0/guide/index.html +++ b/docs/en/cowboy/2.0/guide/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Cowboy User Guide</title> @@ -67,201 +67,199 @@ <h1 class="lined-header"><span>Cowboy User Guide</span></h1> -<div class="sect1">
-<h2 id="_rationale">Rationale</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="modern_web/">The modern Web</a>
-</p>
-</li>
-<li>
-<p>
-<a href="erlang_web/">Erlang and the Web</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_introduction">Introduction</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="introduction/">Introduction</a>
-</p>
-</li>
-<li>
-<p>
-<a href="getting_started/">Getting started</a>
-</p>
-</li>
-<li>
-<p>
-<a href="flow_diagram/">Flow diagram</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_configuration">Configuration</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="listeners/">Listeners</a>
-</p>
-</li>
-<li>
-<p>
-<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="_handlers">Handlers</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="handlers/">Handlers</a>
-</p>
-</li>
-<li>
-<p>
-<a href="loop_handlers/">Loop handlers</a>
-</p>
-</li>
-<li>
-<p>
-<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>
-<p>
-<a href="req_body/">Reading the request body</a>
-</p>
-</li>
-<li>
-<p>
-<a href="resp/">Sending a response</a>
-</p>
-</li>
-<li>
-<p>
-<a href="cookies/">Using cookies</a>
-</p>
-</li>
-<li>
-<p>
-<a href="multipart/">Multipart</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_rest">REST</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="rest_principles/">REST principles</a>
-</p>
-</li>
-<li>
-<p>
-<a href="rest_handlers/">Handling REST requests</a>
-</p>
-</li>
-<li>
-<p>
-<a href="rest_flowcharts/">REST flowcharts</a>
-</p>
-</li>
-<li>
-<p>
-<a href="resource_design/">Designing a resource handler</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_websocket">Websocket</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="ws_protocol/">The Websocket protocol</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ws_handlers/">Websocket handlers</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_advanced">Advanced</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="streams/">Streams</a>
-</p>
-</li>
-<li>
-<p>
-<a href="middlewares/">Middlewares</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_additional_information">Additional information</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="migrating_from_1.0/">Migrating from Cowboy 1.0 to 2.0</a>
-</p>
-</li>
-</ul></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="specs/">HTTP and other specifications</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_rationale">Rationale</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="modern_web/">The modern Web</a> +</p> +</li> +<li> +<p> +<a href="erlang_web/">Erlang and the Web</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_introduction">Introduction</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="introduction/">Introduction</a> +</p> +</li> +<li> +<p> +<a href="getting_started/">Getting started</a> +</p> +</li> +<li> +<p> +<a href="flow_diagram/">Flow diagram</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="listeners/">Listeners</a> +</p> +</li> +<li> +<p> +<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="_handlers">Handlers</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="handlers/">Handlers</a> +</p> +</li> +<li> +<p> +<a href="loop_handlers/">Loop handlers</a> +</p> +</li> +<li> +<p> +<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> +<p> +<a href="req_body/">Reading the request body</a> +</p> +</li> +<li> +<p> +<a href="resp/">Sending a response</a> +</p> +</li> +<li> +<p> +<a href="cookies/">Using cookies</a> +</p> +</li> +<li> +<p> +<a href="multipart/">Multipart</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_rest">REST</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="rest_principles/">REST principles</a> +</p> +</li> +<li> +<p> +<a href="rest_handlers/">Handling REST requests</a> +</p> +</li> +<li> +<p> +<a href="rest_flowcharts/">REST flowcharts</a> +</p> +</li> +<li> +<p> +<a href="resource_design/">Designing a resource handler</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_websocket">Websocket</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="ws_protocol/">The Websocket protocol</a> +</p> +</li> +<li> +<p> +<a href="ws_handlers/">Websocket handlers</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_advanced">Advanced</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="streams/">Streams</a> +</p> +</li> +<li> +<p> +<a href="middlewares/">Middlewares</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_additional_information">Additional information</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="migrating_from_1.0/">Migrating from Cowboy 1.0 to 2.0</a> +</p> +</li> +<li> +<p> +<a href="specs/">HTTP and other specifications</a> +</p> +</li> +</ul></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/guide/introduction/index.html b/docs/en/cowboy/2.0/guide/introduction/index.html index 8c0c25f8..63b07c4e 100644 --- a/docs/en/cowboy/2.0/guide/introduction/index.html +++ b/docs/en/cowboy/2.0/guide/introduction/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Introduction</title> @@ -67,85 +67,88 @@ <h1 class="lined-header"><span>Introduction</span></h1> -<div class="paragraph"><p>Cowboy is a small, fast and modern HTTP server for Erlang/OTP.</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 a Function Reference, a User Guide and numerous Tutorials.</p></div>
-<div class="sect1">
-<h2 id="_prerequisites">Prerequisites</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Beginner Erlang knowledge is recommended for reading this guide.</p></div>
-<div class="paragraph"><p>Knowledge of the HTTP protocol is recommended but not required, as it
-will be detailed throughout the guide.</p></div>
-</div>
-</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, 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 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-2017, 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">
-<h2 id="_versioning">Versioning</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy uses <a href="http://semver.org/">Semantic Versioning 2.0.0</a>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_conventions">Conventions</h2>
-<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. 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>
+<div class="paragraph"><p>Cowboy is a small, fast and modern HTTP server for Erlang/OTP.</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 a Function Reference, a User Guide and numerous Tutorials.</p></div> +<div class="sect1"> +<h2 id="_prerequisites">Prerequisites</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Beginner Erlang knowledge is recommended for reading this guide.</p></div> +<div class="paragraph"><p>Knowledge of the HTTP protocol is recommended but not required, as it +will be detailed throughout the guide.</p></div> +</div> +</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, 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 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-2017, 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"> +<h2 id="_versioning">Versioning</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy uses <a href="http://semver.org/">Semantic Versioning 2.0.0</a>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_conventions">Conventions</h2> +<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. 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> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/listeners/index.html b/docs/en/cowboy/2.0/guide/listeners/index.html index 49d841c6..a5fbb60e 100644 --- a/docs/en/cowboy/2.0/guide/listeners/index.html +++ b/docs/en/cowboy/2.0/guide/listeners/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Listeners</title> @@ -67,115 +67,118 @@ <h1 class="lined-header"><span>Listeners</span></h1> -<div class="paragraph"><p>A listener is a set of processes that listens on a port for
-new connections. Incoming connections get handled by Cowboy.
-Depending on the connection handshake, one or another protocol
-may be used.</p></div>
-<div class="paragraph"><p>This chapter is specific to Cowboy. Please refer to the
-<a href="http://ninenines.eu/docs/en/ranch/1.3/guide/listeners/">Ranch User Guide</a>
-for more information about listeners.</p></div>
-<div class="paragraph"><p>Cowboy provides two types of listeners: one listening for
-clear TCP connections, and one listening for secure TLS
-connections. Both of them support the HTTP/1.1 and HTTP/2
-protocols.</p></div>
-<div class="sect1">
-<h2 id="_clear_tcp_listener">Clear TCP listener</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The clear TCP listener will accept connections on the
-given port. A typical HTTP server would listen on port 80.
-Port 80 requires special permissions on most platforms
-however so a common alternative is port 8080.</p></div>
-<div class="paragraph"><p>The following snippet starts listening for connections
-on port 8080:</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">start</span></span>(<span style="color: #009900">_Type</span>, <span style="color: #009900">_Args</span>) <span style="color: #990000">-></span>
- <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_clear</span></span>(<span style="color: #FF6600">my_http_listener</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 <a href="../getting_started">Getting Started</a> chapter uses a
-clear TCP listener.</p></div>
-<div class="paragraph"><p>Clients connecting to Cowboy on the clear listener port are
-expected to use either HTTP/1.1 or HTTP/2.</p></div>
-<div class="paragraph"><p>Cowboy supports both methods of initiating a clear
-HTTP/2 connection: through the Upgrade mechanism
-(<a href="https://tools.ietf.org/html/rfc7540#section-3.2">RFC 7540 3.2</a>)
-or by sending the preface directly
-(<a href="https://tools.ietf.org/html/rfc7540#section-3.4">RFC 7540 3.4</a>).</p></div>
-<div class="paragraph"><p>Compatibility with HTTP/1.0 is provided by Cowboy’s HTTP/1.1
-implementation.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_secure_tls_listener">Secure TLS listener</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The secure TLS listener will accept connections on the
-given port. A typical HTTPS server would listen on port 443.
-Port 443 requires special permissions on most platforms
-however so a common alternative is port 8443.</p></div>
-<div class="paragraph"><p>The function provided by Cowboy will ensure that the TLS
-options given are following the HTTP/2 RFC with regards
-to security. For example some TLS extensions or ciphers
-may be disabled. This also applies to HTTP/1.1 connections
-on this listener. If this is not desirable, Ranch can be
-used directly to setup a custom listener.</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">start</span></span>(<span style="color: #009900">_Type</span>, <span style="color: #009900">_Args</span>) <span style="color: #990000">-></span>
- <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_tls</span></span>(<span style="color: #FF6600">my_http_listener</span>,
- [
- {<span style="color: #FF6600">port</span>, <span style="color: #993399">8443</span>},
- {<span style="color: #FF6600">certfile</span>, <span style="color: #FF0000">"/path/to/certfile"</span>},
- {<span style="color: #FF6600">keyfile</span>, <span style="color: #FF0000">"/path/to/keyfile"</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>Clients connecting to Cowboy on the secure listener are
-expected to use the ALPN TLS extension to indicate what
-protocols they understand. Cowboy always prefers HTTP/2
-over HTTP/1.1 when both are supported. When neither are
-supported by the client, or when the ALPN extension was
-missing, Cowboy expects HTTP/1.1 to be used.</p></div>
-<div class="paragraph"><p>Cowboy also advertises HTTP/2 support through the older
-NPN TLS extension for compatibility. Note however that
-this support will likely not be enabled by default when
-Cowboy 2.0 gets released.</p></div>
-<div class="paragraph"><p>Compatibility with HTTP/1.0 is provided by Cowboy’s HTTP/1.1
-implementation.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_protocol_configuration">Protocol configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The HTTP/1.1 and HTTP/2 protocols share the same semantics;
-only their framing differs. The first is a text protocol and
-the second a binary protocol.</p></div>
-<div class="paragraph"><p>Cowboy doesn’t separate the configuration for HTTP/1.1 and
-HTTP/2. Everything goes into the same map. Many options are
-shared.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>A listener is a set of processes that listens on a port for +new connections. Incoming connections get handled by Cowboy. +Depending on the connection handshake, one or another protocol +may be used.</p></div> +<div class="paragraph"><p>This chapter is specific to Cowboy. Please refer to the +<a href="http://ninenines.eu/docs/en/ranch/1.3/guide/listeners/">Ranch User Guide</a> +for more information about listeners.</p></div> +<div class="paragraph"><p>Cowboy provides two types of listeners: one listening for +clear TCP connections, and one listening for secure TLS +connections. Both of them support the HTTP/1.1 and HTTP/2 +protocols.</p></div> +<div class="sect1"> +<h2 id="_clear_tcp_listener">Clear TCP listener</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The clear TCP listener will accept connections on the +given port. A typical HTTP server would listen on port 80. +Port 80 requires special permissions on most platforms +however so a common alternative is port 8080.</p></div> +<div class="paragraph"><p>The following snippet starts listening for connections +on port 8080:</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">start</span></span>(<span style="color: #009900">_Type</span>, <span style="color: #009900">_Args</span>) <span style="color: #990000">-></span> + <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_clear</span></span>(<span style="color: #FF6600">my_http_listener</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 <a href="../getting_started">Getting Started</a> chapter uses a +clear TCP listener.</p></div> +<div class="paragraph"><p>Clients connecting to Cowboy on the clear listener port are +expected to use either HTTP/1.1 or HTTP/2.</p></div> +<div class="paragraph"><p>Cowboy supports both methods of initiating a clear +HTTP/2 connection: through the Upgrade mechanism +(<a href="https://tools.ietf.org/html/rfc7540#section-3.2">RFC 7540 3.2</a>) +or by sending the preface directly +(<a href="https://tools.ietf.org/html/rfc7540#section-3.4">RFC 7540 3.4</a>).</p></div> +<div class="paragraph"><p>Compatibility with HTTP/1.0 is provided by Cowboy’s HTTP/1.1 +implementation.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_secure_tls_listener">Secure TLS listener</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The secure TLS listener will accept connections on the +given port. A typical HTTPS server would listen on port 443. +Port 443 requires special permissions on most platforms +however so a common alternative is port 8443.</p></div> +<div class="paragraph"><p>The function provided by Cowboy will ensure that the TLS +options given are following the HTTP/2 RFC with regards +to security. For example some TLS extensions or ciphers +may be disabled. This also applies to HTTP/1.1 connections +on this listener. If this is not desirable, Ranch can be +used directly to setup a custom listener.</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">start</span></span>(<span style="color: #009900">_Type</span>, <span style="color: #009900">_Args</span>) <span style="color: #990000">-></span> + <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_tls</span></span>(<span style="color: #FF6600">my_http_listener</span>, + [ + {<span style="color: #FF6600">port</span>, <span style="color: #993399">8443</span>}, + {<span style="color: #FF6600">certfile</span>, <span style="color: #FF0000">"/path/to/certfile"</span>}, + {<span style="color: #FF6600">keyfile</span>, <span style="color: #FF0000">"/path/to/keyfile"</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>Clients connecting to Cowboy on the secure listener are +expected to use the ALPN TLS extension to indicate what +protocols they understand. Cowboy always prefers HTTP/2 +over HTTP/1.1 when both are supported. When neither are +supported by the client, or when the ALPN extension was +missing, Cowboy expects HTTP/1.1 to be used.</p></div> +<div class="paragraph"><p>Cowboy also advertises HTTP/2 support through the older +NPN TLS extension for compatibility. Note however that +this support will likely not be enabled by default when +Cowboy 2.0 gets released.</p></div> +<div class="paragraph"><p>Compatibility with HTTP/1.0 is provided by Cowboy’s HTTP/1.1 +implementation.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_protocol_configuration">Protocol configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The HTTP/1.1 and HTTP/2 protocols share the same semantics; +only their framing differs. The first is a text protocol and +the second a binary protocol.</p></div> +<div class="paragraph"><p>Cowboy doesn’t separate the configuration for HTTP/1.1 and +HTTP/2. Everything goes into the same map. Many options are +shared.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/loop_handlers.asciidoc b/docs/en/cowboy/2.0/guide/loop_handlers.asciidoc index 80bc484d..21bf8424 100644 --- a/docs/en/cowboy/2.0/guide/loop_handlers.asciidoc +++ b/docs/en/cowboy/2.0/guide/loop_handlers.asciidoc @@ -1,8 +1,6 @@ [[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 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 442bc7e0..0b0b50b5 100644 --- a/docs/en/cowboy/2.0/guide/loop_handlers/index.html +++ b/docs/en/cowboy/2.0/guide/loop_handlers/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Loop handlers</title> @@ -67,137 +67,140 @@ <h1 class="lined-header"><span>Loop handlers</span></h1> -<div class="paragraph"><p>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
-a response.</p></div>
-<div class="paragraph"><p>Loop handlers are used for requests where a response might not
-be immediately available, but where you would like to keep the
-connection open for a while in case the response arrives. The
-most known example of such practice is known as long polling.</p></div>
-<div class="paragraph"><p>Loop handlers can also be used for requests where a response is
-partially available and you need to stream the response body
-while the connection is open. The most known example of such
-practice is server-sent events.</p></div>
-<div class="paragraph"><p>While the same can be accomplished using plain HTTP handlers,
-it is recommended to use loop handlers because they are well-tested
-and allow using built-in features like hibernation and timeouts.</p></div>
-<div class="paragraph"><p>Loop handlers essentially wait for one or more Erlang messages
-and feed these messages to the <code>info/3</code> callback. It also features
-the <code>init/2</code> and <code>terminate/3</code> callbacks which work the same as
-for plain HTTP handlers.</p></div>
-<div class="sect1">
-<h2 id="_initialization">Initialization</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>init/2</code> function must return a <code>cowboy_loop</code> tuple to enable
-loop handler behavior. This tuple may optionally contain
-a timeout value and/or the atom <code>hibernate</code> to make the
-process enter hibernation until a message is received.</p></div>
-<div class="paragraph"><p>This snippet enables the loop handler:</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">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>This also makes the process hibernate:</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">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: #FF6600">hibernate</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_receive_loop">Receive loop</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Once initialized, Cowboy will wait for messages to arrive
-in the process' mailbox. When a message arrives, Cowboy
-calls the <code>info/3</code> function with the message, the Req object
-and the handler’s state.</p></div>
-<div class="paragraph"><p>The following snippet sends a reply when it receives a
-<code>reply</code> message from another process, or waits for another
-message 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">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="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
-and is simply an example.</p></div>
-<div class="paragraph"><p>This callback may perform any necessary operation including
-sending all or parts of a reply, and will subsequently
-return a tuple indicating if more messages are to be expected.</p></div>
-<div class="paragraph"><p>The callback may also choose to do nothing at all and just
-skip the message received.</p></div>
-<div class="paragraph"><p>If a reply is sent, then the <code>stop</code> tuple should be returned.
-This will instruct Cowboy to end the request.</p></div>
-<div class="paragraph"><p>Otherwise an <code>ok</code> tuple should be returned.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_streaming_loop">Streaming loop</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Another common case well suited for loop handlers is
-streaming data received in the form of Erlang messages.
-This can be done by initiating a chunked reply in the
-<code>init/2</code> callback and then using <code>cowboy_req:chunk/2</code>
-every time a message is received.</p></div>
-<div class="paragraph"><p>The following snippet does exactly that. As you can see
-a chunk is sent every time an <code>event</code> message is received,
-and the loop is stopped by sending an <code>eof</code> message.</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">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:stream_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: #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>};
-<span style="font-weight: bold"><span style="color: #000000">info</span></span>({<span style="color: #FF6600">event</span>, <span style="color: #009900">Data</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">cowboy_req:stream_body</span></span>(<span style="color: #009900">Data</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Req</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">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: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_cleaning_up">Cleaning up</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>It is recommended that you set the connection header to
-<code>close</code> when replying, as this process may be reused for
-a subsequent request.</p></div>
-<div class="paragraph"><p>Please refer to the <a href="../handlers">Handlers chapter</a>
-for general instructions about cleaning up.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_hibernate">Hibernate</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To save memory, you may hibernate the process in between
-messages received. This is done by returning the atom
-<code>hibernate</code> as part of the <code>loop</code> tuple callbacks normally
-return. Just add the atom at the end and Cowboy will hibernate
-accordingly.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>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 +a response.</p></div> +<div class="paragraph"><p>Loop handlers are used for requests where a response might not +be immediately available, but where you would like to keep the +connection open for a while in case the response arrives. The +most known example of such practice is known as long polling.</p></div> +<div class="paragraph"><p>Loop handlers can also be used for requests where a response is +partially available and you need to stream the response body +while the connection is open. The most known example of such +practice is server-sent events.</p></div> +<div class="paragraph"><p>While the same can be accomplished using plain HTTP handlers, +it is recommended to use loop handlers because they are well-tested +and allow using built-in features like hibernation and timeouts.</p></div> +<div class="paragraph"><p>Loop handlers essentially wait for one or more Erlang messages +and feed these messages to the <code>info/3</code> callback. It also features +the <code>init/2</code> and <code>terminate/3</code> callbacks which work the same as +for plain HTTP handlers.</p></div> +<div class="sect1"> +<h2 id="_initialization">Initialization</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>init/2</code> function must return a <code>cowboy_loop</code> tuple to enable +loop handler behavior. This tuple may optionally contain +a timeout value and/or the atom <code>hibernate</code> to make the +process enter hibernation until a message is received.</p></div> +<div class="paragraph"><p>This snippet enables the loop handler:</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">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>This also makes the process hibernate:</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">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: #FF6600">hibernate</span>}<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_receive_loop">Receive loop</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Once initialized, Cowboy will wait for messages to arrive +in the process' mailbox. When a message arrives, Cowboy +calls the <code>info/3</code> function with the message, the Req object +and the handler’s state.</p></div> +<div class="paragraph"><p>The following snippet sends a reply when it receives a +<code>reply</code> message from another process, or waits for another +message 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">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="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 +and is simply an example.</p></div> +<div class="paragraph"><p>This callback may perform any necessary operation including +sending all or parts of a reply, and will subsequently +return a tuple indicating if more messages are to be expected.</p></div> +<div class="paragraph"><p>The callback may also choose to do nothing at all and just +skip the message received.</p></div> +<div class="paragraph"><p>If a reply is sent, then the <code>stop</code> tuple should be returned. +This will instruct Cowboy to end the request.</p></div> +<div class="paragraph"><p>Otherwise an <code>ok</code> tuple should be returned.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_streaming_loop">Streaming loop</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Another common case well suited for loop handlers is +streaming data received in the form of Erlang messages. +This can be done by initiating a chunked reply in the +<code>init/2</code> callback and then using <code>cowboy_req:chunk/2</code> +every time a message is received.</p></div> +<div class="paragraph"><p>The following snippet does exactly that. As you can see +a chunk is sent every time an <code>event</code> message is received, +and the loop is stopped by sending an <code>eof</code> message.</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">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:stream_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: #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>}; +<span style="font-weight: bold"><span style="color: #000000">info</span></span>({<span style="color: #FF6600">event</span>, <span style="color: #009900">Data</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">cowboy_req:stream_body</span></span>(<span style="color: #009900">Data</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Req</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">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: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_cleaning_up">Cleaning up</h2> +<div class="sectionbody"> +<div class="paragraph"><p>It is recommended that you set the connection header to +<code>close</code> when replying, as this process may be reused for +a subsequent request.</p></div> +<div class="paragraph"><p>Please refer to the <a href="../handlers">Handlers chapter</a> +for general instructions about cleaning up.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_hibernate">Hibernate</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To save memory, you may hibernate the process in between +messages received. This is done by returning the atom +<code>hibernate</code> as part of the <code>loop</code> tuple callbacks normally +return. Just add the atom at the end and Cowboy will hibernate +accordingly.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/middlewares/index.html b/docs/en/cowboy/2.0/guide/middlewares/index.html index bb0a2a0c..5569e6f5 100644 --- a/docs/en/cowboy/2.0/guide/middlewares/index.html +++ b/docs/en/cowboy/2.0/guide/middlewares/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Middlewares</title> @@ -67,98 +67,101 @@ <h1 class="lined-header"><span>Middlewares</span></h1> -<div class="paragraph"><p>Cowboy delegates the request processing to middleware components.
-By default, two middlewares are defined, for the routing and handling
-of the request, as is detailed in most of this guide.</p></div>
-<div class="paragraph"><p>Middlewares give you complete control over how requests are to be
-processed. You can add your own middlewares to the mix or completely
-change the chain of middlewares as needed.</p></div>
-<div class="paragraph"><p>Cowboy will execute all middlewares in the given order, unless one
-of them decides to stop processing.</p></div>
-<div class="sect1">
-<h2 id="_usage">Usage</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Middlewares only need to implement a single callback: <code>execute/2</code>.
-It is defined in the <code>cowboy_middleware</code> behavior.</p></div>
-<div class="paragraph"><p>This callback has two arguments. The first is the <code>Req</code> object.
-The second is the environment.</p></div>
-<div class="paragraph"><p>Middlewares can return one of three different values:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<code>{ok, Req, Env}</code> to continue the request processing
-</p>
-</li>
-<li>
-<p>
-<code>{suspend, Module, Function, Args}</code> to hibernate
-</p>
-</li>
-<li>
-<p>
-<code>{stop, Req}</code> to stop processing and move on to the next request
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Of note is that when hibernating, processing will resume on the given
-MFA, discarding all previous stacktrace. Make sure you keep the <code>Req</code>
-and <code>Env</code> in the arguments of this MFA for later use.</p></div>
-<div class="paragraph"><p>If an error happens during middleware processing, Cowboy will not try
-to send an error back to the socket, the process will just crash. It
-is up to the middleware to make sure that a reply is sent if something
-goes wrong.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_configuration">Configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The middleware environment is defined as the <code>env</code> protocol option.
-In the previous chapters we saw it briefly when we needed to pass
-the routing information. It is a list of tuples with the first
-element being an atom and the second any Erlang term.</p></div>
-<div class="paragraph"><p>Two values in the environment are reserved:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<code>listener</code> contains the name of the listener
-</p>
-</li>
-<li>
-<p>
-<code>result</code> contains the result of the processing
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>The <code>listener</code> value is always defined. The <code>result</code> value can be
-set by any middleware. If set to anything other than <code>ok</code>, Cowboy
-will not process any subsequent requests on this connection.</p></div>
-<div class="paragraph"><p>The middlewares that come with Cowboy may define or require other
-environment values to perform.</p></div>
-<div class="paragraph"><p>You can update the environment by calling the <code>cowboy:set_env/3</code>
-convenience function, adding or replacing a value in the environment.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_routing_middleware">Routing middleware</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The routing middleware requires the <code>dispatch</code> value. If routing
-succeeds, it will put the handler name and options in the <code>handler</code>
-and <code>handler_opts</code> values of the environment, respectively.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_handler_middleware">Handler middleware</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The handler middleware requires the <code>handler</code> and <code>handler_opts</code>
-values. It puts the result of the request handling into <code>result</code>.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Cowboy delegates the request processing to middleware components. +By default, two middlewares are defined, for the routing and handling +of the request, as is detailed in most of this guide.</p></div> +<div class="paragraph"><p>Middlewares give you complete control over how requests are to be +processed. You can add your own middlewares to the mix or completely +change the chain of middlewares as needed.</p></div> +<div class="paragraph"><p>Cowboy will execute all middlewares in the given order, unless one +of them decides to stop processing.</p></div> +<div class="sect1"> +<h2 id="_usage">Usage</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Middlewares only need to implement a single callback: <code>execute/2</code>. +It is defined in the <code>cowboy_middleware</code> behavior.</p></div> +<div class="paragraph"><p>This callback has two arguments. The first is the <code>Req</code> object. +The second is the environment.</p></div> +<div class="paragraph"><p>Middlewares can return one of three different values:</p></div> +<div class="ulist"><ul> +<li> +<p> +<code>{ok, Req, Env}</code> to continue the request processing +</p> +</li> +<li> +<p> +<code>{suspend, Module, Function, Args}</code> to hibernate +</p> +</li> +<li> +<p> +<code>{stop, Req}</code> to stop processing and move on to the next request +</p> +</li> +</ul></div> +<div class="paragraph"><p>Of note is that when hibernating, processing will resume on the given +MFA, discarding all previous stacktrace. Make sure you keep the <code>Req</code> +and <code>Env</code> in the arguments of this MFA for later use.</p></div> +<div class="paragraph"><p>If an error happens during middleware processing, Cowboy will not try +to send an error back to the socket, the process will just crash. It +is up to the middleware to make sure that a reply is sent if something +goes wrong.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The middleware environment is defined as the <code>env</code> protocol option. +In the previous chapters we saw it briefly when we needed to pass +the routing information. It is a list of tuples with the first +element being an atom and the second any Erlang term.</p></div> +<div class="paragraph"><p>Two values in the environment are reserved:</p></div> +<div class="ulist"><ul> +<li> +<p> +<code>listener</code> contains the name of the listener +</p> +</li> +<li> +<p> +<code>result</code> contains the result of the processing +</p> +</li> +</ul></div> +<div class="paragraph"><p>The <code>listener</code> value is always defined. The <code>result</code> value can be +set by any middleware. If set to anything other than <code>ok</code>, Cowboy +will not process any subsequent requests on this connection.</p></div> +<div class="paragraph"><p>The middlewares that come with Cowboy may define or require other +environment values to perform.</p></div> +<div class="paragraph"><p>You can update the environment by calling the <code>cowboy:set_env/3</code> +convenience function, adding or replacing a value in the environment.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_routing_middleware">Routing middleware</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The routing middleware requires the <code>dispatch</code> value. If routing +succeeds, it will put the handler name and options in the <code>handler</code> +and <code>handler_opts</code> values of the environment, respectively.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_handler_middleware">Handler middleware</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The handler middleware requires the <code>handler</code> and <code>handler_opts</code> +values. It puts the result of the request handling into <code>result</code>.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/migrating_from_1.0/index.html b/docs/en/cowboy/2.0/guide/migrating_from_1.0/index.html index c10169c4..f7f9492b 100644 --- a/docs/en/cowboy/2.0/guide/migrating_from_1.0/index.html +++ b/docs/en/cowboy/2.0/guide/migrating_from_1.0/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Migrating from Cowboy 1.0 to 2.0</title> @@ -67,384 +67,387 @@ <h1 class="lined-header"><span>Migrating from Cowboy 1.0 to 2.0</span></h1> -<div class="paragraph"><p>A lot has changed between Cowboy 1.0 and 2.0. The <code>cowboy_req</code>
-interface in particular has seen a massive revamp. Hooks are
-gone, their functionality can now be achieved via stream
-handlers.</p></div>
-<div class="paragraph"><p>The documentation has seen great work, in particular the
-manual. Each module and each function now has its own dedicated
-manual page with full details and examples.</p></div>
-<div class="sect1">
-<h2 id="_compatibility">Compatibility</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Compatibility with Erlang/OTP R16, 17 and 18 has been dropped.
-Erlang/OTP 19.0 or above is required. It is non-trivial to
-make Cowboy 2.0 work with older Erlang/OTP versions.</p></div>
-<div class="paragraph"><p>Cowboy 2.0 is not compatible with Cowlib versions older than
-2.0. It should be compatible with Ranch 1.0 or above, however
-it has not been tested with Ranch versions older than 1.4.</p></div>
-<div class="paragraph"><p>Cowboy 2.0 is tested on Arch Linux, Ubuntu, FreeBSD, Windows
-and OSX. It is tested with every point release (latest patch
-release) and also with HiPE on the most recent release.</p></div>
-<div class="paragraph"><p>Cowboy 2.0 now comes with Erlang.mk templates.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_features_added">Features added</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-The HTTP/2 protocol is now supported.
-</p>
-</li>
-<li>
-<p>
-Cowboy no longer uses only one process per connection.
- It now uses one process per connection plus one process
- per request by default. This is necessary for HTTP/2.
- There might be a slight drop in performance for HTTP/1.1
- connections due to this change.
-</p>
-</li>
-<li>
-<p>
-Cowboy internals have largely been reworked in order to
- support HTTP/2. This opened the way to stream handlers,
- which are a chain of modules that are called whenever
- something happens relating to a request/response.
-</p>
-</li>
-<li>
-<p>
-The <code>cowboy_stream_h</code> stream handler has been added.
- It provides most of Cowboy’s default behavior.
-</p>
-</li>
-<li>
-<p>
-The <code>cowboy_compress_h</code> stream handler has been added.
- It compresses responses when possible. It’s worth noting
- that it compresses in more cases than Cowboy 1.0 ever did.
-</p>
-</li>
-<li>
-<p>
-Because of the many changes in the internals of Cowboy,
- many options have been added or modified. Of note is that
- the Websocket options are now given per handler rather
- than for the entire listener.
-</p>
-</li>
-<li>
-<p>
-Websocket permessage-deflate compression is now supported
- via the <code>compress</code> option.
-</p>
-</li>
-<li>
-<p>
-Static file handlers will now correctly find files found
- in <em>.ez</em> archives.
-</p>
-</li>
-<li>
-<p>
-Constraints have been generalized and are now used not only
- in the router but also in some <code>cowboy_req</code> functions. Their
- interface has also been modified to allow for reverse
- operations and formatting of errors.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_features_removed">Features removed</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-SPDY support has been removed. Use HTTP/2 instead.
-</p>
-</li>
-<li>
-<p>
-Hooks have been removed. Use <a href="../streams">stream handlers</a> instead.
-</p>
-</li>
-<li>
-<p>
-The undocumented <code>waiting_stream</code> hack has been removed.
- It allowed disabling chunked transfer-encoding for HTTP/1.1.
- It has no equivalent in Cowboy 2.0. Open a ticket if necessary.
-</p>
-</li>
-<li>
-<p>
-Sub protocols still exist, but their interface has largely changed
- and they are no longer documented for the time being.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changed_behaviors">Changed behaviors</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-The handler behaviors have been renamed and are now <code>cowboy_handler</code>,
- <code>cowboy_loop</code>, <code>cowboy_rest</code> and <code>cowboy_websocket</code>.
-</p>
-</li>
-<li>
-<p>
-Plain HTTP, loop, REST and Websocket handlers have had their
- init and terminate callbacks unified. They now all use the
- <code>init/2</code> and <code>terminate/3</code> callbacks. The latter is now optional.
- The terminate reason has now been documented for all handlers.
-</p>
-</li>
-<li>
-<p>
-The tuple returned to switch to a different handler type has
- changed. It now takes the form <code>{Module, Req, State}</code> or
- <code>{Module, Req, State, Opts}</code>, where <code>Opts</code> is a map of options
- to configure the handler. The timeout and hibernate options
- must now be specified using this map, where applicable.
-</p>
-</li>
-<li>
-<p>
-All behaviors that used to accept <code>halt</code> or <code>shutdown</code> tuples
- as a return value no longer do so. The return value is now
- a <code>stop</code> tuple, consistent across Cowboy.
-</p>
-</li>
-<li>
-<p>
-Middlewares can no longer return an <code>error</code> tuple. They have
- to send the response and return a <code>stop</code> tuple instead.
-</p>
-</li>
-<li>
-<p>
-The <code>known_content_type</code> REST handler callback has been removed
- as it was found unnecessary.
-</p>
-</li>
-<li>
-<p>
-Websocket handlers have both the normal <code>init/2</code> and
- an optional <code>websocket_init/1</code> function. The reason for
- that exception is that the <code>websocket_*</code> callbacks execute
- in a separate process from the <code>init/2</code> callback, and it
- was therefore not obvious how timers or monitors should
- be setup properly. They are effectively initializing the
- handler before and after the HTTP/1.1 upgrade.
-</p>
-</li>
-<li>
-<p>
-Websocket handlers can now send frames directly from
- <code>websocket_init/1</code>. The frames will be sent immediately
- after the handshake.
-</p>
-</li>
-<li>
-<p>
-Websocket handler callbacks no longer receive the Req
- argument. The <code>init/2</code> callback still receives it and
- can be used to extract relevant information. The <code>terminate/3</code>
- callback, if implemented, may still receive the Req
- (see next bullet point).
-</p>
-</li>
-<li>
-<p>
-Websocket handlers have a new <code>req_filter</code> option that
- can be used to customize how much information should be
- discarded from the Req object after the handshake. Note
- that the Req object is only available in <code>terminate/3</code>
- past that point.
-</p>
-</li>
-<li>
-<p>
-Websocket handlers have their timeout default changed
- from infinity to 60 seconds.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_new_functions">New functions</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-The <code>cowboy_req:scheme/1</code> function has been added.
-</p>
-</li>
-<li>
-<p>
-The <code>cowboy_req:uri/1,2</code> function has been added, replacing the
- less powerful functions <code>cowboy_req:url/1</code> and <code>cowboy_req:host_url/1</code>.
-</p>
-</li>
-<li>
-<p>
-The functions <code>cowboy_req:match_qs/2</code> and <code>cowboy_req:match_cookies/2</code>
- allow matching query string and cookies against constraints.
-</p>
-</li>
-<li>
-<p>
-The function <code>cowboy_req:set_resp_cookie/3</code> has been added to
- complement <code>cowboy_req:set_resp_cookie/4</code>.
-</p>
-</li>
-<li>
-<p>
-The functions <code>cowboy_req:resp_header/2,3</code> and <code>cowboy_req:resp_headers/1</code>
- have been added. They can be used to retrieve response headers
- that were previously set.
-</p>
-</li>
-<li>
-<p>
-The function <code>cowboy_req:set_resp_headers/2</code> has been added. It
- allows setting many response headers at once.
-</p>
-</li>
-<li>
-<p>
-The functions <code>cowboy_req:push/3,4</code> can be used to push resources
- for protocols that support it (by default only HTTP/2).
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changed_functions">Changed functions</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-The <code>cowboy:start_http/4</code> function was renamed to <code>cowboy:start_clear/3</code>.
-</p>
-</li>
-<li>
-<p>
-The <code>cowboy:start_https/4</code> function was renamed to <code>cowboy:start_tls/3</code>.
-</p>
-</li>
-<li>
-<p>
-Most, if not all, functions in the <code>cowboy_req</code> module have been modified.
- Please consult the changelog of each individual functions. The changes
- are mainly about simplifying and clarifying the interface. The Req is no
- longer returned when not necessary, maps are used wherever possible,
- and some functions have been renamed.
-</p>
-</li>
-<li>
-<p>
-The position of the <code>Opts</code> argument for <code>cowboy_req:set_resp_cookie/4</code>
- has changed to improve consistency. It is now the last argument.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_removed_functions">Removed functions</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-The functions <code>cowboy_req:url/1</code> and <code>cowboy_req:host_url/1</code> have been
- removed in favor of the new function <code>cowboy_req:uri/1,2</code>.
-</p>
-</li>
-<li>
-<p>
-The functions <code>cowboy_req:meta/2,3</code> and <code>cowboy_req:set_meta/3</code> have
- been removed. The Req object is now a public map, therefore they became
- unnecessary.
-</p>
-</li>
-<li>
-<p>
-The functions <code>cowboy_req:set_resp_body_fun/2,3</code> have been removed.
- For sending files, the function <code>cowboy_req:set_resp_body/2</code> can now
- take a sendfile tuple.
-</p>
-</li>
-<li>
-<p>
-Remove many undocumented functions from <code>cowboy_req</code>, including the
- functions <code>cowboy_req:get/2</code> and <code>cowboy_req:set/3</code>.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_other_changes">Other changes</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-The correct percent-decoding algorithm is now used for path elements
- during routing. It will no longer decode <code>+</code> characters.
-</p>
-</li>
-<li>
-<p>
-The router will now properly handle path segments <code>.</code> and <code>..</code>.
-</p>
-</li>
-<li>
-<p>
-Routing behavior has changed for URIs containing latin1 characters.
- They are no longer allowed. URIs are expected to be in UTF-8 once
- they are percent-decoded.
-</p>
-</li>
-<li>
-<p>
-Etag comparison in REST handlers has been fixed. Some requests may
- now fail when they succeeded in the past.
-</p>
-</li>
-<li>
-<p>
-The <code>If-*-Since</code> headers are now ignored in REST handlers if
- the corresponding <code>If*-Match</code> header exist. The former is
- largely a backward compatible header and this shouldn’t create
- any issue. The new behavior follows the current RFCs more closely.
-</p>
-</li>
-<li>
-<p>
-The static file handler has been improved to handle more special
- characters on systems that accept them.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
+<div class="paragraph"><p>A lot has changed between Cowboy 1.0 and 2.0. The <code>cowboy_req</code> +interface in particular has seen a massive revamp. Hooks are +gone, their functionality can now be achieved via stream +handlers.</p></div> +<div class="paragraph"><p>The documentation has seen great work, in particular the +manual. Each module and each function now has its own dedicated +manual page with full details and examples.</p></div> +<div class="sect1"> +<h2 id="_compatibility">Compatibility</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Compatibility with Erlang/OTP R16, 17 and 18 has been dropped. +Erlang/OTP 19.0 or above is required. It is non-trivial to +make Cowboy 2.0 work with older Erlang/OTP versions.</p></div> +<div class="paragraph"><p>Cowboy 2.0 is not compatible with Cowlib versions older than +2.0. It should be compatible with Ranch 1.0 or above, however +it has not been tested with Ranch versions older than 1.4.</p></div> +<div class="paragraph"><p>Cowboy 2.0 is tested on Arch Linux, Ubuntu, FreeBSD, Windows +and OSX. It is tested with every point release (latest patch +release) and also with HiPE on the most recent release.</p></div> +<div class="paragraph"><p>Cowboy 2.0 now comes with Erlang.mk templates.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_features_added">Features added</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +The HTTP/2 protocol is now supported. +</p> +</li> +<li> +<p> +Cowboy no longer uses only one process per connection. + It now uses one process per connection plus one process + per request by default. This is necessary for HTTP/2. + There might be a slight drop in performance for HTTP/1.1 + connections due to this change. +</p> +</li> +<li> +<p> +Cowboy internals have largely been reworked in order to + support HTTP/2. This opened the way to stream handlers, + which are a chain of modules that are called whenever + something happens relating to a request/response. +</p> +</li> +<li> +<p> +The <code>cowboy_stream_h</code> stream handler has been added. + It provides most of Cowboy’s default behavior. +</p> +</li> +<li> +<p> +The <code>cowboy_compress_h</code> stream handler has been added. + It compresses responses when possible. It’s worth noting + that it compresses in more cases than Cowboy 1.0 ever did. +</p> +</li> +<li> +<p> +Because of the many changes in the internals of Cowboy, + many options have been added or modified. Of note is that + the Websocket options are now given per handler rather + than for the entire listener. +</p> +</li> +<li> +<p> +Websocket permessage-deflate compression is now supported + via the <code>compress</code> option. +</p> +</li> +<li> +<p> +Static file handlers will now correctly find files found + in <em>.ez</em> archives. +</p> +</li> +<li> +<p> +Constraints have been generalized and are now used not only + in the router but also in some <code>cowboy_req</code> functions. Their + interface has also been modified to allow for reverse + operations and formatting of errors. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_features_removed">Features removed</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +SPDY support has been removed. Use HTTP/2 instead. +</p> +</li> +<li> +<p> +Hooks have been removed. Use <a href="../streams">stream handlers</a> instead. +</p> +</li> +<li> +<p> +The undocumented <code>waiting_stream</code> hack has been removed. + It allowed disabling chunked transfer-encoding for HTTP/1.1. + It has no equivalent in Cowboy 2.0. Open a ticket if necessary. +</p> +</li> +<li> +<p> +Sub protocols still exist, but their interface has largely changed + and they are no longer documented for the time being. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changed_behaviors">Changed behaviors</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +The handler behaviors have been renamed and are now <code>cowboy_handler</code>, + <code>cowboy_loop</code>, <code>cowboy_rest</code> and <code>cowboy_websocket</code>. +</p> +</li> +<li> +<p> +Plain HTTP, loop, REST and Websocket handlers have had their + init and terminate callbacks unified. They now all use the + <code>init/2</code> and <code>terminate/3</code> callbacks. The latter is now optional. + The terminate reason has now been documented for all handlers. +</p> +</li> +<li> +<p> +The tuple returned to switch to a different handler type has + changed. It now takes the form <code>{Module, Req, State}</code> or + <code>{Module, Req, State, Opts}</code>, where <code>Opts</code> is a map of options + to configure the handler. The timeout and hibernate options + must now be specified using this map, where applicable. +</p> +</li> +<li> +<p> +All behaviors that used to accept <code>halt</code> or <code>shutdown</code> tuples + as a return value no longer do so. The return value is now + a <code>stop</code> tuple, consistent across Cowboy. +</p> +</li> +<li> +<p> +Middlewares can no longer return an <code>error</code> tuple. They have + to send the response and return a <code>stop</code> tuple instead. +</p> +</li> +<li> +<p> +The <code>known_content_type</code> REST handler callback has been removed + as it was found unnecessary. +</p> +</li> +<li> +<p> +Websocket handlers have both the normal <code>init/2</code> and + an optional <code>websocket_init/1</code> function. The reason for + that exception is that the <code>websocket_*</code> callbacks execute + in a separate process from the <code>init/2</code> callback, and it + was therefore not obvious how timers or monitors should + be setup properly. They are effectively initializing the + handler before and after the HTTP/1.1 upgrade. +</p> +</li> +<li> +<p> +Websocket handlers can now send frames directly from + <code>websocket_init/1</code>. The frames will be sent immediately + after the handshake. +</p> +</li> +<li> +<p> +Websocket handler callbacks no longer receive the Req + argument. The <code>init/2</code> callback still receives it and + can be used to extract relevant information. The <code>terminate/3</code> + callback, if implemented, may still receive the Req + (see next bullet point). +</p> +</li> +<li> +<p> +Websocket handlers have a new <code>req_filter</code> option that + can be used to customize how much information should be + discarded from the Req object after the handshake. Note + that the Req object is only available in <code>terminate/3</code> + past that point. +</p> +</li> +<li> +<p> +Websocket handlers have their timeout default changed + from infinity to 60 seconds. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_new_functions">New functions</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +The <code>cowboy_req:scheme/1</code> function has been added. +</p> +</li> +<li> +<p> +The <code>cowboy_req:uri/1,2</code> function has been added, replacing the + less powerful functions <code>cowboy_req:url/1</code> and <code>cowboy_req:host_url/1</code>. +</p> +</li> +<li> +<p> +The functions <code>cowboy_req:match_qs/2</code> and <code>cowboy_req:match_cookies/2</code> + allow matching query string and cookies against constraints. +</p> +</li> +<li> +<p> +The function <code>cowboy_req:set_resp_cookie/3</code> has been added to + complement <code>cowboy_req:set_resp_cookie/4</code>. +</p> +</li> +<li> +<p> +The functions <code>cowboy_req:resp_header/2,3</code> and <code>cowboy_req:resp_headers/1</code> + have been added. They can be used to retrieve response headers + that were previously set. +</p> +</li> +<li> +<p> +The function <code>cowboy_req:set_resp_headers/2</code> has been added. It + allows setting many response headers at once. +</p> +</li> +<li> +<p> +The functions <code>cowboy_req:push/3,4</code> can be used to push resources + for protocols that support it (by default only HTTP/2). +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changed_functions">Changed functions</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +The <code>cowboy:start_http/4</code> function was renamed to <code>cowboy:start_clear/3</code>. +</p> +</li> +<li> +<p> +The <code>cowboy:start_https/4</code> function was renamed to <code>cowboy:start_tls/3</code>. +</p> +</li> +<li> +<p> +Most, if not all, functions in the <code>cowboy_req</code> module have been modified. + Please consult the changelog of each individual functions. The changes + are mainly about simplifying and clarifying the interface. The Req is no + longer returned when not necessary, maps are used wherever possible, + and some functions have been renamed. +</p> +</li> +<li> +<p> +The position of the <code>Opts</code> argument for <code>cowboy_req:set_resp_cookie/4</code> + has changed to improve consistency. It is now the last argument. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_removed_functions">Removed functions</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +The functions <code>cowboy_req:url/1</code> and <code>cowboy_req:host_url/1</code> have been + removed in favor of the new function <code>cowboy_req:uri/1,2</code>. +</p> +</li> +<li> +<p> +The functions <code>cowboy_req:meta/2,3</code> and <code>cowboy_req:set_meta/3</code> have + been removed. The Req object is now a public map, therefore they became + unnecessary. +</p> +</li> +<li> +<p> +The functions <code>cowboy_req:set_resp_body_fun/2,3</code> have been removed. + For sending files, the function <code>cowboy_req:set_resp_body/2</code> can now + take a sendfile tuple. +</p> +</li> +<li> +<p> +Remove many undocumented functions from <code>cowboy_req</code>, including the + functions <code>cowboy_req:get/2</code> and <code>cowboy_req:set/3</code>. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_other_changes">Other changes</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +The correct percent-decoding algorithm is now used for path elements + during routing. It will no longer decode <code>+</code> characters. +</p> +</li> +<li> +<p> +The router will now properly handle path segments <code>.</code> and <code>..</code>. +</p> +</li> +<li> +<p> +Routing behavior has changed for URIs containing latin1 characters. + They are no longer allowed. URIs are expected to be in UTF-8 once + they are percent-decoded. +</p> +</li> +<li> +<p> +Etag comparison in REST handlers has been fixed. Some requests may + now fail when they succeeded in the past. +</p> +</li> +<li> +<p> +The <code>If-*-Since</code> headers are now ignored in REST handlers if + the corresponding <code>If*-Match</code> header exist. The former is + largely a backward compatible header and this shouldn’t create + any issue. The new behavior follows the current RFCs more closely. +</p> +</li> +<li> +<p> +The static file handler has been improved to handle more special + characters on systems that accept them. +</p> +</li> +</ul></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/modern_web.asciidoc b/docs/en/cowboy/2.0/guide/modern_web.asciidoc index 6c43adb0..48525732 100644 --- a/docs/en/cowboy/2.0/guide/modern_web.asciidoc +++ b/docs/en/cowboy/2.0/guide/modern_web.asciidoc @@ -1,8 +1,6 @@ [[modern_web]] == The modern Web -// @todo Link to related xrefs. - Cowboy is a server for the modern Web. This chapter explains what it means and details all the standards involved. @@ -56,9 +54,9 @@ methods, status codes, headers or semantics. === Websocket -Websocket is a protocol built on top of HTTP/1.1 that provides -a two-ways communication channel between the client and the -server. Communication is asynchronous and can occur concurrently. +xref:ws_protocol[Websocket] is a protocol built on top of HTTP/1.1 +that provides a two-ways communication channel between the client and +the server. Communication is asynchronous and can occur concurrently. It consists of a Javascript object allowing setting up a Websocket connection to the server, and a binary based @@ -79,6 +77,9 @@ 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. +Cowboy provides an interface known as xref:ws_handlers[Websocket handlers] +that gives complete control over a Websocket connection. + The Websocket protocol is defined by RFC 6455. === Long-lived requests @@ -101,21 +102,21 @@ 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 +Cowboy provides an interface known as xref:loop_handlers[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. +xref:rest_principles[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. -Cowboy provides an interface known as REST handlers that -simplifies the implementation of a REST API on top of +Cowboy provides an interface known as xref:rest_handlers[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 62aef447..2bbf1072 100644 --- a/docs/en/cowboy/2.0/guide/modern_web/index.html +++ b/docs/en/cowboy/2.0/guide/modern_web/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: The modern Web</title> @@ -67,119 +67,124 @@ <h1 class="lined-header"><span>The modern Web</span></h1> -<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="_http_2">HTTP/2</h2>
-<div class="sectionbody">
-<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 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">
-<h2 id="_websocket">Websocket</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Websocket is a protocol built on top of HTTP/1.1 that provides
-a two-ways communication channel between the client and the
-server. Communication is asynchronous and can occur concurrently.</p></div>
-<div class="paragraph"><p>It consists of a Javascript object allowing setting up a
-Websocket connection to the server, and a binary based
-protocol for sending data to the server or the client.</p></div>
-<div class="paragraph"><p>Websocket connections can transfer either UTF-8 encoded text
-data or binary data. The protocol also includes support for
-implementing a ping/pong mechanism, allowing the server and
-the client to have more confidence that the connection is still
-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="_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>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>
+<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="_http_2">HTTP/2</h2> +<div class="sectionbody"> +<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 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"> +<h2 id="_websocket">Websocket</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../ws_protocol">Websocket</a> is a protocol built on top of HTTP/1.1 +that provides a two-ways communication channel between the client and +the server. Communication is asynchronous and can occur concurrently.</p></div> +<div class="paragraph"><p>It consists of a Javascript object allowing setting up a +Websocket connection to the server, and a binary based +protocol for sending data to the server or the client.</p></div> +<div class="paragraph"><p>Websocket connections can transfer either UTF-8 encoded text +data or binary data. The protocol also includes support for +implementing a ping/pong mechanism, allowing the server and +the client to have more confidence that the connection is still +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>Cowboy provides an interface known as <a href="../ws_handlers">Websocket handlers</a> +that gives complete control over a Websocket connection.</p></div> +<div class="paragraph"><p>The Websocket protocol is defined by RFC 6455.</p></div> +</div> +</div> +<div class="sect1"> +<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 <a href="../loop_handlers">loop handlers</a> +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><a href="../rest_principles">REST, or REpresentational State Transfer</a>, +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 <a href="../rest_handlers">REST handlers</a> +that simplifies the implementation of a REST API on top of +the HTTP protocol.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/multipart.asciidoc b/docs/en/cowboy/2.0/guide/multipart.asciidoc index 756d3b46..0825244c 100644 --- a/docs/en/cowboy/2.0/guide/multipart.asciidoc +++ b/docs/en/cowboy/2.0/guide/multipart.asciidoc @@ -112,9 +112,9 @@ multipart(Req0) -> stream_file(Req0) -> case cowboy_req:read_part_body(Req0) of - {ok, _Body, Req} -> + {ok, _LastBodyChunk, Req} -> Req; - {more, _Body, Req} -> + {more, _BodyChunk, Req} -> stream_file(Req) end. ---- diff --git a/docs/en/cowboy/2.0/guide/multipart/index.html b/docs/en/cowboy/2.0/guide/multipart/index.html index cc53b55d..4f173126 100644 --- a/docs/en/cowboy/2.0/guide/multipart/index.html +++ b/docs/en/cowboy/2.0/guide/multipart/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Multipart requests</title> @@ -67,175 +67,178 @@ <h1 class="lined-header"><span>Multipart requests</span></h1> -<div class="paragraph"><p>Multipart originates from MIME, an Internet standard that
-extends the format of emails.</p></div>
-<div class="paragraph"><p>A multipart message is a list of parts. A part contains
-headers and a body. The body of the parts may be
-of any media type, and contain text or binary data.
-It is possible for parts to contain a multipart media
-type.</p></div>
-<div class="paragraph"><p>In the context of HTTP, multipart is most often used
-with the <code>multipart/form-data</code> media type. It is what
-browsers use to upload files through HTML forms.</p></div>
-<div class="paragraph"><p>The <code>multipart/byteranges</code> is also common. It is the
-media type used to send arbitrary bytes from a resource,
-enabling clients to resume downloads.</p></div>
-<div class="sect1">
-<h2 id="_form_data">Form-data</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>In the normal case, when a form is submitted, the
-browser will use the <code>application/x-www-form-urlencoded</code>
-content-type. This type is just a list of keys and
-values and is therefore not fit for uploading files.</p></div>
-<div class="paragraph"><p>That’s where the <code>multipart/form-data</code> content-type
-comes in. When the form is configured to use this
-content-type, the browser will create a multipart
-message where each part corresponds to a field on
-the form. For files, it also adds some metadata in
-the part headers, like the file name.</p></div>
-<div class="paragraph"><p>A form with a text input, a file input and a select
-choice box will result in a multipart message with
-three parts, one for each field.</p></div>
-<div class="paragraph"><p>The browser does its best to determine the media type
-of the files it sends this way, but you should not
-rely on it for determining the contents of the file.
-Proper investigation of the contents is recommended.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_checking_for_multipart_messages">Checking for multipart messages</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The content-type header indicates the presence of
-a multipart message:</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: #FF0000">"multipart"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"form-data"</span><span style="color: #990000">>></span>, <span style="color: #990000">_</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>
-</div>
-<div class="sect1">
-<h2 id="_reading_a_multipart_message">Reading a multipart message</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy provides two sets of functions for reading
-request bodies as multipart messages.</p></div>
-<div class="paragraph"><p>The <code>cowboy_req:read_part/1,2</code> functions return the
-next part’s headers, if any.</p></div>
-<div class="paragraph"><p>The <code>cowboy_req:read_part_body/1,2</code> functions return
-the current part’s body. For large bodies you may
-need to call the function multiple times.</p></div>
-<div class="paragraph"><p>To read a multipart message you need to iterate over
-all its parts:</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">multipart</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_part</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">_Headers</span>, <span style="color: #009900">Req1</span>} <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">_Body</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_part_body</span></span>(<span style="color: #009900">Req1</span>),
- <span style="font-weight: bold"><span style="color: #000000">multipart</span></span>(<span style="color: #009900">Req</span>);
- {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></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>When part bodies are too large, Cowboy will return
-a <code>more</code> tuple, and allow you to loop until the part
-body has been fully read.</p></div>
-<div class="paragraph"><p>The function <code>cow_multipart:form_data/1</code> can be used
-to quickly obtain information about a part from a
-<code>multipart/form-data</code> message. The function returns
-a <code>data</code> or a <code>file</code> tuple depending on whether this
-is a normal field or a file being uploaded.</p></div>
-<div class="paragraph"><p>The following snippet will use this function and
-use different strategies depending on whether the
-part is a 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="font-weight: bold"><span style="color: #000000">multipart</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_part</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">Headers</span>, <span style="color: #009900">Req1</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: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">cow_multipart:form_data</span></span>(<span style="color: #009900">Headers</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- {<span style="color: #FF6600">data</span>, <span style="color: #009900">_FieldName</span>} <span style="color: #990000">-></span>
- {<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:read_part_body</span></span>(<span style="color: #009900">Req1</span>),
- <span style="color: #009900">Req2</span>;
- {<span style="color: #FF6600">file</span>, <span style="color: #009900">_FieldName</span>, <span style="color: #009900">_Filename</span>, <span style="color: #009900">_CType</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">stream_file</span></span>(<span style="color: #009900">Req1</span>)
- <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>,
- <span style="font-weight: bold"><span style="color: #000000">multipart</span></span>(<span style="color: #009900">Req</span>);
- {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span>
- <span style="color: #009900">Req</span>
- <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">stream_file</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_part_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">_Body</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span>
- <span style="color: #009900">Req</span>;
- {<span style="color: #FF6600">more</span>, <span style="color: #009900">_Body</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">stream_file</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>Both the part header and body reading functions can take
-options that will be given to the request body reading
-functions. By default, <code>cowboy_req:read_part/1</code> reads
-up to 64KB for up to 5 seconds. <code>cowboy_req:read_part_body/1</code>
-has the same defaults as <code>cowboy_req:read_body/1</code>.</p></div>
-<div class="paragraph"><p>To change the defaults for part headers:</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:read_part</span></span>(<span style="color: #009900">Req</span>, #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="color: #993399">128000</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>And for part bodies:</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:read_part_body</span></span>(<span style="color: #009900">Req</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">7000</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_skipping_unwanted_parts">Skipping unwanted parts</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Part bodies do not have to be read. Cowboy will automatically
-skip it when you request the next part’s body.</p></div>
-<div class="paragraph"><p>The following snippet reads all part headers and skips
-all bodies:</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">multipart</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_part</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">_Headers</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">multipart</span></span>(<span style="color: #009900">Req</span>);
- {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></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>Similarly, if you start reading the body and it ends up
-being too big, you can simply continue with the next part.
-Cowboy will automatically skip what remains.</p></div>
-<div class="paragraph"><p>While Cowboy can skip part bodies automatically, the read
-rate is not configurable. Depending on your application
-you may want to skip manually, in particular if you observe
-poor performance while skipping.</p></div>
-<div class="paragraph"><p>You do not have to read all parts either. You can stop
-reading as soon as you find the data you need.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Multipart originates from MIME, an Internet standard that +extends the format of emails.</p></div> +<div class="paragraph"><p>A multipart message is a list of parts. A part contains +headers and a body. The body of the parts may be +of any media type, and contain text or binary data. +It is possible for parts to contain a multipart media +type.</p></div> +<div class="paragraph"><p>In the context of HTTP, multipart is most often used +with the <code>multipart/form-data</code> media type. It is what +browsers use to upload files through HTML forms.</p></div> +<div class="paragraph"><p>The <code>multipart/byteranges</code> is also common. It is the +media type used to send arbitrary bytes from a resource, +enabling clients to resume downloads.</p></div> +<div class="sect1"> +<h2 id="_form_data">Form-data</h2> +<div class="sectionbody"> +<div class="paragraph"><p>In the normal case, when a form is submitted, the +browser will use the <code>application/x-www-form-urlencoded</code> +content-type. This type is just a list of keys and +values and is therefore not fit for uploading files.</p></div> +<div class="paragraph"><p>That’s where the <code>multipart/form-data</code> content-type +comes in. When the form is configured to use this +content-type, the browser will create a multipart +message where each part corresponds to a field on +the form. For files, it also adds some metadata in +the part headers, like the file name.</p></div> +<div class="paragraph"><p>A form with a text input, a file input and a select +choice box will result in a multipart message with +three parts, one for each field.</p></div> +<div class="paragraph"><p>The browser does its best to determine the media type +of the files it sends this way, but you should not +rely on it for determining the contents of the file. +Proper investigation of the contents is recommended.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_checking_for_multipart_messages">Checking for multipart messages</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The content-type header indicates the presence of +a multipart message:</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: #FF0000">"multipart"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"form-data"</span><span style="color: #990000">>></span>, <span style="color: #990000">_</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> +</div> +<div class="sect1"> +<h2 id="_reading_a_multipart_message">Reading a multipart message</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy provides two sets of functions for reading +request bodies as multipart messages.</p></div> +<div class="paragraph"><p>The <code>cowboy_req:read_part/1,2</code> functions return the +next part’s headers, if any.</p></div> +<div class="paragraph"><p>The <code>cowboy_req:read_part_body/1,2</code> functions return +the current part’s body. For large bodies you may +need to call the function multiple times.</p></div> +<div class="paragraph"><p>To read a multipart message you need to iterate over +all its parts:</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">multipart</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_part</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">_Headers</span>, <span style="color: #009900">Req1</span>} <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">_Body</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_part_body</span></span>(<span style="color: #009900">Req1</span>), + <span style="font-weight: bold"><span style="color: #000000">multipart</span></span>(<span style="color: #009900">Req</span>); + {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></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>When part bodies are too large, Cowboy will return +a <code>more</code> tuple, and allow you to loop until the part +body has been fully read.</p></div> +<div class="paragraph"><p>The function <code>cow_multipart:form_data/1</code> can be used +to quickly obtain information about a part from a +<code>multipart/form-data</code> message. The function returns +a <code>data</code> or a <code>file</code> tuple depending on whether this +is a normal field or a file being uploaded.</p></div> +<div class="paragraph"><p>The following snippet will use this function and +use different strategies depending on whether the +part is a 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="font-weight: bold"><span style="color: #000000">multipart</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_part</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">Headers</span>, <span style="color: #009900">Req1</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: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">cow_multipart:form_data</span></span>(<span style="color: #009900">Headers</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + {<span style="color: #FF6600">data</span>, <span style="color: #009900">_FieldName</span>} <span style="color: #990000">-></span> + {<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:read_part_body</span></span>(<span style="color: #009900">Req1</span>), + <span style="color: #009900">Req2</span>; + {<span style="color: #FF6600">file</span>, <span style="color: #009900">_FieldName</span>, <span style="color: #009900">_Filename</span>, <span style="color: #009900">_CType</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">stream_file</span></span>(<span style="color: #009900">Req1</span>) + <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>, + <span style="font-weight: bold"><span style="color: #000000">multipart</span></span>(<span style="color: #009900">Req</span>); + {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> + <span style="color: #009900">Req</span> + <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">stream_file</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_part_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">_LastBodyChunk</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> + <span style="color: #009900">Req</span>; + {<span style="color: #FF6600">more</span>, <span style="color: #009900">_BodyChunk</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">stream_file</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>Both the part header and body reading functions can take +options that will be given to the request body reading +functions. By default, <code>cowboy_req:read_part/1</code> reads +up to 64KB for up to 5 seconds. <code>cowboy_req:read_part_body/1</code> +has the same defaults as <code>cowboy_req:read_body/1</code>.</p></div> +<div class="paragraph"><p>To change the defaults for part headers:</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:read_part</span></span>(<span style="color: #009900">Req</span>, #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="color: #993399">128000</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>And for part bodies:</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:read_part_body</span></span>(<span style="color: #009900">Req</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">7000</span>})<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_skipping_unwanted_parts">Skipping unwanted parts</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Part bodies do not have to be read. Cowboy will automatically +skip it when you request the next part’s body.</p></div> +<div class="paragraph"><p>The following snippet reads all part headers and skips +all bodies:</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">multipart</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_part</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">_Headers</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">multipart</span></span>(<span style="color: #009900">Req</span>); + {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></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>Similarly, if you start reading the body and it ends up +being too big, you can simply continue with the next part. +Cowboy will automatically skip what remains.</p></div> +<div class="paragraph"><p>While Cowboy can skip part bodies automatically, the read +rate is not configurable. Depending on your application +you may want to skip manually, in particular if you observe +poor performance while skipping.</p></div> +<div class="paragraph"><p>You do not have to read all parts either. You can stop +reading as soon as you find the data you need.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/req/index.html b/docs/en/cowboy/2.0/guide/req/index.html index 6ff5b0a7..bdf6b6b9 100644 --- a/docs/en/cowboy/2.0/guide/req/index.html +++ b/docs/en/cowboy/2.0/guide/req/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: The Req object</title> @@ -67,413 +67,416 @@ <h1 class="lined-header"><span>The Req object</span></h1> -<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 class="sect1">
-<h2 id="_direct_access">Direct access</h2>
-<div class="sectionbody">
-<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="_introduction_to_the_cowboy_req_interface">Introduction to the cowboy_req interface</h2>
-<div class="sectionbody">
-<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 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: #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>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="_effective_request_uri">Effective request URI</h2>
-<div class="sectionbody">
-<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: #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">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 <code><<"http">></code> and <code><<"https">></code> schemes.
-They are chosen so that the scheme will only be <code><<"https">></code>
-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="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="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="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="_bindings">Bindings</h2>
-<div class="sectionbody">
-<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">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">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: #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 map, 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">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: #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="_query_parameters">Query parameters</h2>
-<div class="sectionbody">
-<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">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 <a href="../constraints">constraints</a>.
-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: #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>Header values can be retrieved either as a binary string
-or parsed into a more meaningful representation.</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>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>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>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>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
-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>
-</div>
-<div class="sect1">
-<h2 id="_peer">Peer</h2>
-<div class="sectionbody">
-<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: #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>
+<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 class="sect1"> +<h2 id="_direct_access">Direct access</h2> +<div class="sectionbody"> +<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="_introduction_to_the_cowboy_req_interface">Introduction to the cowboy_req interface</h2> +<div class="sectionbody"> +<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 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: #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>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="_effective_request_uri">Effective request URI</h2> +<div class="sectionbody"> +<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: #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">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 <code><<"http">></code> and <code><<"https">></code> schemes. +They are chosen so that the scheme will only be <code><<"https">></code> +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="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="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="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="_bindings">Bindings</h2> +<div class="sectionbody"> +<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">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">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: #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 map, 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">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: #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="_query_parameters">Query parameters</h2> +<div class="sectionbody"> +<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">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 <a href="../constraints">constraints</a>. +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: #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>Header values can be retrieved either as a binary string +or parsed into a more meaningful representation.</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>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>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>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>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 +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> +</div> +<div class="sect1"> +<h2 id="_peer">Peer</h2> +<div class="sectionbody"> +<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: #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> + + + <nav style="margin:1em 0"> 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 821b512c..4fce0fd5 100644 --- a/docs/en/cowboy/2.0/guide/req_body/index.html +++ b/docs/en/cowboy/2.0/guide/req_body/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Reading the request body</title> @@ -67,150 +67,153 @@ <h1 class="lined-header"><span>Reading the request body</span></h1> -<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 <a href="../multipart">multipart bodies</a>.
-The latter is covered in its own chapter.</p></div>
-<div class="sect1">
-<h2 id="_request_body_presence">Request body presence</h2>
-<div class="sectionbody">
-<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 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 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>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 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">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">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">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>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">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">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">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>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>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: #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">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>
+<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 <a href="../multipart">multipart bodies</a>. +The latter is covered in its own chapter.</p></div> +<div class="sect1"> +<h2 id="_request_body_presence">Request body presence</h2> +<div class="sectionbody"> +<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 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 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>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 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">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">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">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>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">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">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">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>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>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: #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">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> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/resource_design/index.html b/docs/en/cowboy/2.0/guide/resource_design/index.html index 1a288856..32c8a129 100644 --- a/docs/en/cowboy/2.0/guide/resource_design/index.html +++ b/docs/en/cowboy/2.0/guide/resource_design/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Designing a resource handler</title> @@ -67,219 +67,222 @@ <h1 class="lined-header"><span>Designing a resource handler</span></h1> -<div class="paragraph"><p>This chapter aims to provide you with a list of questions
-you must answer in order to write a good resource handler.
-It is meant to be usable as a step by step guide.</p></div>
-<div class="sect1">
-<h2 id="_the_service">The service</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Can the service become unavailable, and when it does, can
-we detect it? For example, database connectivity problems
-may be detected early. We may also have planned outages
-of all or parts of the system. Implement the
-<code>service_available</code> callback.</p></div>
-<div class="paragraph"><p>What HTTP methods does the service implement? Do we need
-more than the standard OPTIONS, HEAD, GET, PUT, POST,
-PATCH and DELETE? Are we not using one of those at all?
-Implement the <code>known_methods</code> callback.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_type_of_resource_handler">Type of resource handler</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Am I writing a handler for a collection of resources,
-or for a single resource?</p></div>
-<div class="paragraph"><p>The semantics for each of these are quite different.
-You should not mix collection and single resource in
-the same handler.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_collection_handler">Collection handler</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Skip this section if you are not doing a collection.</p></div>
-<div class="paragraph"><p>Is the collection hardcoded or dynamic? For example,
-if you use the route <code>/users</code> for the collection of
-users then the collection is hardcoded; if you use
-<code>/forums/:category</code> for the collection of threads
-then it isn’t. When the collection is hardcoded you
-can safely assume the resource always exists.</p></div>
-<div class="paragraph"><p>What methods should I implement?</p></div>
-<div class="paragraph"><p>OPTIONS is used to get some information about the
-collection. It is recommended to allow it even if you
-do not implement it, as Cowboy has a default
-implementation built-in.</p></div>
-<div class="paragraph"><p>HEAD and GET are used to retrieve the collection.
-If you allow GET, also allow HEAD as there’s no extra
-work required to make it work.</p></div>
-<div class="paragraph"><p>POST is used to create a new resource inside the
-collection. Creating a resource by using POST on
-the collection is useful when resources may be
-created before knowing their URI, usually because
-parts of it are generated dynamically. A common
-case is some kind of auto incremented integer
-identifier.</p></div>
-<div class="paragraph"><p>The next methods are more rarely allowed.</p></div>
-<div class="paragraph"><p>PUT is used to create a new collection (when
-the collection isn’t hardcoded), or replace
-the entire collection.</p></div>
-<div class="paragraph"><p>DELETE is used to delete the entire collection.</p></div>
-<div class="paragraph"><p>PATCH is used to modify the collection using
-instructions given in the request body. A PATCH
-operation is atomic. The PATCH operation may
-be used for such things as reordering; adding,
-modifying or deleting parts of the collection.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_single_resource_handler">Single resource handler</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Skip this section if you are doing a collection.</p></div>
-<div class="paragraph"><p>What methods should I implement?</p></div>
-<div class="paragraph"><p>OPTIONS is used to get some information about the
-resource. It is recommended to allow it even if you
-do not implement it, as Cowboy has a default
-implementation built-in.</p></div>
-<div class="paragraph"><p>HEAD and GET are used to retrieve the resource.
-If you allow GET, also allow HEAD as there’s no extra
-work required to make it work.</p></div>
-<div class="paragraph"><p>POST is used to update the resource.</p></div>
-<div class="paragraph"><p>PUT is used to create a new resource (when it doesn’t
-already exist) or replace the resource.</p></div>
-<div class="paragraph"><p>DELETE is used to delete the resource.</p></div>
-<div class="paragraph"><p>PATCH is used to modify the resource using
-instructions given in the request body. A PATCH
-operation is atomic. The PATCH operation may
-be used for adding, removing or modifying specific
-values in the resource.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_the_resource">The resource</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Following the above discussion, implement the
-<code>allowed_methods</code> callback.</p></div>
-<div class="paragraph"><p>Does the resource always exist? If it may not, implement
-the <code>resource_exists</code> callback.</p></div>
-<div class="paragraph"><p>Do I need to authenticate the client before they can
-access the resource? What authentication mechanisms
-should I provide? This may include form-based, token-based
-(in the URL or a cookie), HTTP basic, HTTP digest,
-SSL certificate or any other form of authentication.
-Implement the <code>is_authorized</code> callback.</p></div>
-<div class="paragraph"><p>Do I need fine-grained access control? How do I determine
-that they are authorized access? Handle that in your
-<code>is_authorized</code> callback.</p></div>
-<div class="paragraph"><p>Can access to a resource be forbidden regardless of access
-being authorized? A simple example of that is censorship
-of a resource. Implement the <code>forbidden</code> callback.</p></div>
-<div class="paragraph"><p>Are there any constraints on the length of the resource URI?
-For example, the URI may be used as a key in storage and may
-have a limit in length. Implement <code>uri_too_long</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_representations">Representations</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>What media types do I provide? If text based, what charsets
-are provided? What languages do I provide?</p></div>
-<div class="paragraph"><p>Implement the mandatory <code>content_types_provided</code>. Prefix
-the callbacks with <code>to_</code> for clarity. For example, <code>to_html</code>
-or <code>to_text</code>.</p></div>
-<div class="paragraph"><p>Implement the <code>languages_provided</code> or <code>charsets_provided</code>
-callbacks if applicable.</p></div>
-<div class="paragraph"><p>Is there any other header that may make the representation
-of the resource vary? Implement the <code>variances</code> callback.</p></div>
-<div class="paragraph"><p>Depending on your choices for caching content, you may
-want to implement one or more of the <code>generate_etag</code>,
-<code>last_modified</code> and <code>expires</code> callbacks.</p></div>
-<div class="paragraph"><p>Do I want the user or user agent to actively choose a
-representation available? Send a list of available
-representations in the response body and implement
-the <code>multiple_choices</code> callback.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_redirections">Redirections</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Do I need to keep track of what resources were deleted?
-For example, you may have a mechanism where moving a
-resource leaves a redirect link to its new location.
-Implement the <code>previously_existed</code> callback.</p></div>
-<div class="paragraph"><p>Was the resource moved, and is the move temporary? If
-it is explicitly temporary, for example due to maintenance,
-implement the <code>moved_temporarily</code> callback. Otherwise,
-implement the <code>moved_permanently</code> callback.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_the_request">The request</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Do you need to read the query string? Individual headers?
-Implement <code>malformed_request</code> and do all the parsing and
-validation in this function. Note that the body should not
-be read at this point.</p></div>
-<div class="paragraph"><p>May there be a request body? Will I know its size?
-What’s the maximum size of the request body I’m willing
-to accept? Implement <code>valid_entity_length</code>.</p></div>
-<div class="paragraph"><p>Finally, take a look at the sections corresponding to the
-methods you are implementing.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_options_method">OPTIONS method</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy by default will send back a list of allowed methods.
-Do I need to add more information to the response? Implement
-the <code>options</code> method.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_get_and_head_methods">GET and HEAD methods</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>If you implement the methods GET and/or HEAD, you must
-implement one <code>ProvideResource</code> callback for each
-content-type returned by the <code>content_types_provided</code>
-callback.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_put_post_and_patch_methods">PUT, POST and PATCH methods</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>If you implement the methods PUT, POST and/or PATCH,
-you must implement the <code>content_types_accepted</code> callback,
-and one <code>AcceptResource</code> callback for each content-type
-it returns. Prefix the <code>AcceptResource</code> callback names
-with <code>from_</code> for clarity. For example, <code>from_html</code> or
-<code>from_json</code>.</p></div>
-<div class="paragraph"><p>Do we want to allow the POST method to create individual
-resources directly through their URI (like PUT)? Implement
-the <code>allow_missing_post</code> callback. It is recommended to
-explicitly use PUT in these cases instead.</p></div>
-<div class="paragraph"><p>May there be conflicts when using PUT to create or replace
-a resource? Do we want to make sure that two updates around
-the same time are not cancelling one another? Implement the
-<code>is_conflict</code> callback.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_delete_methods">DELETE methods</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>If you implement the method DELETE, you must implement
-the <code>delete_resource</code> callback.</p></div>
-<div class="paragraph"><p>When <code>delete_resource</code> returns, is the resource completely
-removed from the server, including from any caching service?
-If not, and/or if the deletion is asynchronous and we have
-no way of knowing it has been completed yet, implement the
-<code>delete_completed</code> callback.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter aims to provide you with a list of questions +you must answer in order to write a good resource handler. +It is meant to be usable as a step by step guide.</p></div> +<div class="sect1"> +<h2 id="_the_service">The service</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Can the service become unavailable, and when it does, can +we detect it? For example, database connectivity problems +may be detected early. We may also have planned outages +of all or parts of the system. Implement the +<code>service_available</code> callback.</p></div> +<div class="paragraph"><p>What HTTP methods does the service implement? Do we need +more than the standard OPTIONS, HEAD, GET, PUT, POST, +PATCH and DELETE? Are we not using one of those at all? +Implement the <code>known_methods</code> callback.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_type_of_resource_handler">Type of resource handler</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Am I writing a handler for a collection of resources, +or for a single resource?</p></div> +<div class="paragraph"><p>The semantics for each of these are quite different. +You should not mix collection and single resource in +the same handler.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_collection_handler">Collection handler</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Skip this section if you are not doing a collection.</p></div> +<div class="paragraph"><p>Is the collection hardcoded or dynamic? For example, +if you use the route <code>/users</code> for the collection of +users then the collection is hardcoded; if you use +<code>/forums/:category</code> for the collection of threads +then it isn’t. When the collection is hardcoded you +can safely assume the resource always exists.</p></div> +<div class="paragraph"><p>What methods should I implement?</p></div> +<div class="paragraph"><p>OPTIONS is used to get some information about the +collection. It is recommended to allow it even if you +do not implement it, as Cowboy has a default +implementation built-in.</p></div> +<div class="paragraph"><p>HEAD and GET are used to retrieve the collection. +If you allow GET, also allow HEAD as there’s no extra +work required to make it work.</p></div> +<div class="paragraph"><p>POST is used to create a new resource inside the +collection. Creating a resource by using POST on +the collection is useful when resources may be +created before knowing their URI, usually because +parts of it are generated dynamically. A common +case is some kind of auto incremented integer +identifier.</p></div> +<div class="paragraph"><p>The next methods are more rarely allowed.</p></div> +<div class="paragraph"><p>PUT is used to create a new collection (when +the collection isn’t hardcoded), or replace +the entire collection.</p></div> +<div class="paragraph"><p>DELETE is used to delete the entire collection.</p></div> +<div class="paragraph"><p>PATCH is used to modify the collection using +instructions given in the request body. A PATCH +operation is atomic. The PATCH operation may +be used for such things as reordering; adding, +modifying or deleting parts of the collection.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_single_resource_handler">Single resource handler</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Skip this section if you are doing a collection.</p></div> +<div class="paragraph"><p>What methods should I implement?</p></div> +<div class="paragraph"><p>OPTIONS is used to get some information about the +resource. It is recommended to allow it even if you +do not implement it, as Cowboy has a default +implementation built-in.</p></div> +<div class="paragraph"><p>HEAD and GET are used to retrieve the resource. +If you allow GET, also allow HEAD as there’s no extra +work required to make it work.</p></div> +<div class="paragraph"><p>POST is used to update the resource.</p></div> +<div class="paragraph"><p>PUT is used to create a new resource (when it doesn’t +already exist) or replace the resource.</p></div> +<div class="paragraph"><p>DELETE is used to delete the resource.</p></div> +<div class="paragraph"><p>PATCH is used to modify the resource using +instructions given in the request body. A PATCH +operation is atomic. The PATCH operation may +be used for adding, removing or modifying specific +values in the resource.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_the_resource">The resource</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Following the above discussion, implement the +<code>allowed_methods</code> callback.</p></div> +<div class="paragraph"><p>Does the resource always exist? If it may not, implement +the <code>resource_exists</code> callback.</p></div> +<div class="paragraph"><p>Do I need to authenticate the client before they can +access the resource? What authentication mechanisms +should I provide? This may include form-based, token-based +(in the URL or a cookie), HTTP basic, HTTP digest, +SSL certificate or any other form of authentication. +Implement the <code>is_authorized</code> callback.</p></div> +<div class="paragraph"><p>Do I need fine-grained access control? How do I determine +that they are authorized access? Handle that in your +<code>is_authorized</code> callback.</p></div> +<div class="paragraph"><p>Can access to a resource be forbidden regardless of access +being authorized? A simple example of that is censorship +of a resource. Implement the <code>forbidden</code> callback.</p></div> +<div class="paragraph"><p>Are there any constraints on the length of the resource URI? +For example, the URI may be used as a key in storage and may +have a limit in length. Implement <code>uri_too_long</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_representations">Representations</h2> +<div class="sectionbody"> +<div class="paragraph"><p>What media types do I provide? If text based, what charsets +are provided? What languages do I provide?</p></div> +<div class="paragraph"><p>Implement the mandatory <code>content_types_provided</code>. Prefix +the callbacks with <code>to_</code> for clarity. For example, <code>to_html</code> +or <code>to_text</code>.</p></div> +<div class="paragraph"><p>Implement the <code>languages_provided</code> or <code>charsets_provided</code> +callbacks if applicable.</p></div> +<div class="paragraph"><p>Is there any other header that may make the representation +of the resource vary? Implement the <code>variances</code> callback.</p></div> +<div class="paragraph"><p>Depending on your choices for caching content, you may +want to implement one or more of the <code>generate_etag</code>, +<code>last_modified</code> and <code>expires</code> callbacks.</p></div> +<div class="paragraph"><p>Do I want the user or user agent to actively choose a +representation available? Send a list of available +representations in the response body and implement +the <code>multiple_choices</code> callback.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_redirections">Redirections</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Do I need to keep track of what resources were deleted? +For example, you may have a mechanism where moving a +resource leaves a redirect link to its new location. +Implement the <code>previously_existed</code> callback.</p></div> +<div class="paragraph"><p>Was the resource moved, and is the move temporary? If +it is explicitly temporary, for example due to maintenance, +implement the <code>moved_temporarily</code> callback. Otherwise, +implement the <code>moved_permanently</code> callback.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_the_request">The request</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Do you need to read the query string? Individual headers? +Implement <code>malformed_request</code> and do all the parsing and +validation in this function. Note that the body should not +be read at this point.</p></div> +<div class="paragraph"><p>May there be a request body? Will I know its size? +What’s the maximum size of the request body I’m willing +to accept? Implement <code>valid_entity_length</code>.</p></div> +<div class="paragraph"><p>Finally, take a look at the sections corresponding to the +methods you are implementing.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_options_method">OPTIONS method</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy by default will send back a list of allowed methods. +Do I need to add more information to the response? Implement +the <code>options</code> method.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_get_and_head_methods">GET and HEAD methods</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you implement the methods GET and/or HEAD, you must +implement one <code>ProvideResource</code> callback for each +content-type returned by the <code>content_types_provided</code> +callback.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_put_post_and_patch_methods">PUT, POST and PATCH methods</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you implement the methods PUT, POST and/or PATCH, +you must implement the <code>content_types_accepted</code> callback, +and one <code>AcceptResource</code> callback for each content-type +it returns. Prefix the <code>AcceptResource</code> callback names +with <code>from_</code> for clarity. For example, <code>from_html</code> or +<code>from_json</code>.</p></div> +<div class="paragraph"><p>Do we want to allow the POST method to create individual +resources directly through their URI (like PUT)? Implement +the <code>allow_missing_post</code> callback. It is recommended to +explicitly use PUT in these cases instead.</p></div> +<div class="paragraph"><p>May there be conflicts when using PUT to create or replace +a resource? Do we want to make sure that two updates around +the same time are not cancelling one another? Implement the +<code>is_conflict</code> callback.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_delete_methods">DELETE methods</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you implement the method DELETE, you must implement +the <code>delete_resource</code> callback.</p></div> +<div class="paragraph"><p>When <code>delete_resource</code> returns, is the resource completely +removed from the server, including from any caching service? +If not, and/or if the deletion is asynchronous and we have +no way of knowing it has been completed yet, implement the +<code>delete_completed</code> callback.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/resp/index.html b/docs/en/cowboy/2.0/guide/resp/index.html index 9e6a7c8a..60035278 100644 --- a/docs/en/cowboy/2.0/guide/resp/index.html +++ b/docs/en/cowboy/2.0/guide/resp/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Sending a response</title> @@ -67,328 +67,331 @@ <h1 class="lined-header"><span>Sending a response</span></h1> -<div class="paragraph"><p>The response must be sent using the Req object.</p></div>
-<div class="paragraph"><p>Cowboy provides two different ways of sending responses:
-either directly or by streaming the body. Response headers
-and body may be set in advance. The response is sent as
-soon as one of the reply or stream reply function is
-called.</p></div>
-<div class="paragraph"><p>Cowboy also provides a simplified interface for sending
-files. It can also send only specific parts of a file.</p></div>
-<div class="paragraph"><p>While only one response is allowed for every request,
-HTTP/2 introduced a mechanism that allows the server
-to push additional resources related to the response.
-This chapter also describes how this feature works in
-Cowboy.</p></div>
-<div class="sect1">
-<h2 id="_reply">Reply</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy provides three functions for sending the entire reply,
-depending on whether you need to set headers and body. In all
-cases, Cowboy will add any headers required by the protocol
-(for example the date header will always be sent).</p></div>
-<div class="paragraph"><p>When you need to set only the status code,
-use <code>cowboy_req:reply/2</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">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: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>When you need to set response headers at the same time,
-use <code>cowboy_req:reply/3</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">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">303</span>, #{
- <span style="color: #990000"><<</span><span style="color: #FF0000">"location"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"http://ninenines.eu"</span><span style="color: #990000">>></span>
-}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Note that the header name must always be a lowercase
-binary.</p></div>
-<div class="paragraph"><p>When you also need to set the response body,
-use <code>cowboy_req:reply/4</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">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: #FF0000">"Hello world!"</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You should always set the content-type header when the
-response has a body. There is however no need to set
-the content-length header; Cowboy does it automatically.</p></div>
-<div class="paragraph"><p>The response body and the header values must be either
-a binary or an iolist. An iolist is a list containing
-binaries, characters, strings or other iolists. This
-allows you to build a response from different parts
-without having to do any concatenation:</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">Title</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"Hello world!"</span>,
-<span style="color: #009900">Body</span> <span style="color: #990000">=</span> <span style="color: #990000"><<</span><span style="color: #FF0000">"Hats off!"</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/html"</span><span style="color: #990000">>></span>
-}, [<span style="color: #FF0000">"<html><head><title>"</span>, <span style="color: #009900">Title</span>, <span style="color: #FF0000">"</title></head>"</span>,
- <span style="color: #FF0000">"<body><p>"</span>, <span style="color: #009900">Body</span>, <span style="color: #FF0000">"</p></body></html>"</span>], <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>This method of building responses is more efficient than
-concatenating. Behind the scenes, each element of the list
-is simply a pointer, and those pointers are used directly
-when writing to the socket.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_stream_reply">Stream reply</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy provides two functions for initiating a response,
-and an additional function for streaming the response body.
-Cowboy will add any required headers to the response.</p></div>
-<div class="paragraph"><p>When you need to set only the status code,
-use <code>cowboy_req:stream_reply/2</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_reply</span></span>(<span style="color: #993399">200</span>, <span style="color: #009900">Req0</span>),
-
-<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #FF0000">"Hello..."</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Req</span>),
-<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #FF0000">"chunked..."</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Req</span>),
-<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #FF0000">"world!!"</span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The second argument to <code>cowboy_req:stream_body/3</code> indicates
-whether this data terminates the body. Use <code>fin</code> for the
-final flag, and <code>nofin</code> otherwise.</p></div>
-<div class="paragraph"><p>This snippet does not set a content-type header. This is
-not recommended. All responses with a body should have
-a content-type. The header can be set beforehand, or
-using the <code>cowboy_req:stream_reply/3</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_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/html"</span><span style="color: #990000">>></span>
-}, <span style="color: #009900">Req0</span>),
-
-<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #FF0000">"<html><head>Hello world!</head>"</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Req</span>),
-<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #FF0000">"<body><p>Hats off!</p></body></html>"</span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>HTTP provides a few different ways to stream response bodies.
-Cowboy will select the most appropriate one based on the HTTP
-version and the request and response headers.</p></div>
-<div class="paragraph"><p>While not required by any means, it is recommended that you
-set the content-length header in the response if you know it
-in advance. This will ensure that the best response method
-is selected and help clients understand when the response
-is fully received.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_preset_response_headers">Preset response headers</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy provides functions to set response headers without
-immediately sending them. They are stored in the Req object
-and sent as part of the response when a reply function is
-called.</p></div>
-<div class="paragraph"><p>To set response headers:</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">Req</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">"allow"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"GET"</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Header names must be a lowercase binary.</p></div>
-<div class="paragraph"><p>Do not use this function for setting cookies. Refer to
-the <a href="../cookies">Cookies</a> chapter for more information.</p></div>
-<div class="paragraph"><p>To check if a response header has already been set:</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_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"allow"</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>It returns <code>true</code> if the header was set, <code>false</code> otherwise.</p></div>
-<div class="paragraph"><p>To delete a response header that was set previously:</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:delete_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"allow"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_overriding_headers">Overriding headers</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>As Cowboy provides different ways of setting response
-headers and body, clashes may occur, so it’s important
-to understand what happens when a header is set twice.</p></div>
-<div class="paragraph"><p>Headers come from five different origins:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Protocol-specific headers (for example HTTP/1.1’s connection header)
-</p>
-</li>
-<li>
-<p>
-Other required headers (for example the date header)
-</p>
-</li>
-<li>
-<p>
-Preset headers
-</p>
-</li>
-<li>
-<p>
-Headers given to the reply function
-</p>
-</li>
-<li>
-<p>
-Set-cookie headers
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Cowboy does not allow overriding protocol-specific headers.</p></div>
-<div class="paragraph"><p>Set-cookie headers will always be appended at the end of
-the list of headers before sending the response.</p></div>
-<div class="paragraph"><p>Headers given to the reply function will always override
-preset headers and required headers. If a header is found
-in two or three of these, then the one in the reply function
-is picked and the others are dropped.</p></div>
-<div class="paragraph"><p>Similarly, preset headers will always override required
-headers.</p></div>
-<div class="paragraph"><p>To illustrate, look at the following snippet. Cowboy by
-default sends the server header with the value "Cowboy".
-We can 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">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">"server"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"yaws"</span><span style="color: #990000">>></span>
-}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_preset_response_body">Preset response body</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy provides functions to set the response body without
-immediately sending it. It is stored in the Req object and
-sent when the reply function is called.</p></div>
-<div class="paragraph"><p>To set the response 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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_body</span></span>(<span style="color: #FF0000">"Hello world!"</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>To check if a response body has already been set:</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_resp_body</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>It returns <code>true</code> if the body was set and is non-empty,
-<code>false</code> otherwise.</p></div>
-<div class="paragraph"><p>The preset response body is only sent if the reply function
-used is <code>cowboy_req:reply/2</code> or <code>cowboy_req:reply/3</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_sending_files">Sending files</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy provides a shortcut for sending files. When
-using <code>cowboy_req:reply/4</code>, or when presetting the
-response header, you can give a <code>sendfile</code> tuple to
-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: #FF6600">sendfile</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Length</span>, <span style="color: #009900">Filename</span>}</tt></pre></div></div>
-<div class="paragraph"><p>Depending on the values for <code>Offset</code> or <code>Length</code>, the
-entire file may be sent, or just a part of it.</p></div>
-<div class="paragraph"><p>The length is required even for sending the entire file.
-Cowboy sends it in the content-length header.</p></div>
-<div class="paragraph"><p>To send a file while replying:</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">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">"image/png"</span>
-}, {<span style="color: #FF6600">sendfile</span>, <span style="color: #993399">0</span>, <span style="color: #993399">12345</span>, <span style="color: #FF0000">"path/to/logo.png"</span>}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_push">Push</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The HTTP/2 protocol introduced the ability to push resources
-related to the one sent in the response. Cowboy provides two
-functions for that purpose: <code>cowboy_req:push/3,4</code>.</p></div>
-<div class="paragraph"><p>Push is only available for HTTP/2. Cowboy will automatically
-ignore push requests if the protocol doesn’t support it.</p></div>
-<div class="paragraph"><p>The push function must be called before any of the reply
-functions. Doing otherwise will result in a crash.</p></div>
-<div class="paragraph"><p>To push a resource, you need to provide the same information
-as a client performing a request would. This includes the
-HTTP method, the URI and any necessary request headers.</p></div>
-<div class="paragraph"><p>Cowboy by default only requires you to give the path to
-the resource and the request headers. The rest of the URI
-is taken from the current request (excluding the query
-string, set to empty) and the method is GET by default.</p></div>
-<div class="paragraph"><p>The following snippet pushes a CSS file that is linked to
-in the response:</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:push</span></span>(<span style="color: #FF0000">"/static/style.css"</span>, #{
- <span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/css"</span><span style="color: #990000">>></span>
-}, <span style="color: #009900">Req0</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/html"</span><span style="color: #990000">>></span>
-}, [<span style="color: #FF0000">"<html><head><title>My web page</title>"</span>,
- <span style="color: #FF0000">"<link rel='stylesheet' type='text/css' href='/static/style.css'>"</span>,
- <span style="color: #FF0000">"<body><p>Welcome to Erlang!</p></body></html>"</span>], <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>To override the method, scheme, host, port or query string,
-simply pass in a fourth argument. The following snippet
-uses a different 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="font-weight: bold"><span style="color: #000000">cowboy_req:push</span></span>(<span style="color: #FF0000">"/static/style.css"</span>, #{
- <span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/css"</span><span style="color: #990000">>></span>
-}, #{<span style="color: #0000FF">host</span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"cdn.example.org"</span><span style="color: #990000">>></span>}, <span style="color: #009900">Req</span>),</tt></pre></div></div>
-<div class="paragraph"><p>Pushed resources don’t have to be files. As long as the push
-request is cacheable, safe and does not include a body, the
-resource can be pushed.</p></div>
-<div class="paragraph"><p>Under the hood, Cowboy handles pushed requests the same as
-normal requests: a different process is created which will
-ultimately send a response to the client.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>The response must be sent using the Req object.</p></div> +<div class="paragraph"><p>Cowboy provides two different ways of sending responses: +either directly or by streaming the body. Response headers +and body may be set in advance. The response is sent as +soon as one of the reply or stream reply function is +called.</p></div> +<div class="paragraph"><p>Cowboy also provides a simplified interface for sending +files. It can also send only specific parts of a file.</p></div> +<div class="paragraph"><p>While only one response is allowed for every request, +HTTP/2 introduced a mechanism that allows the server +to push additional resources related to the response. +This chapter also describes how this feature works in +Cowboy.</p></div> +<div class="sect1"> +<h2 id="_reply">Reply</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy provides three functions for sending the entire reply, +depending on whether you need to set headers and body. In all +cases, Cowboy will add any headers required by the protocol +(for example the date header will always be sent).</p></div> +<div class="paragraph"><p>When you need to set only the status code, +use <code>cowboy_req:reply/2</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">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: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>When you need to set response headers at the same time, +use <code>cowboy_req:reply/3</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">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">303</span>, #{ + <span style="color: #990000"><<</span><span style="color: #FF0000">"location"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"http://ninenines.eu"</span><span style="color: #990000">>></span> +}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Note that the header name must always be a lowercase +binary.</p></div> +<div class="paragraph"><p>When you also need to set the response body, +use <code>cowboy_req:reply/4</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">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: #FF0000">"Hello world!"</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You should always set the content-type header when the +response has a body. There is however no need to set +the content-length header; Cowboy does it automatically.</p></div> +<div class="paragraph"><p>The response body and the header values must be either +a binary or an iolist. An iolist is a list containing +binaries, characters, strings or other iolists. This +allows you to build a response from different parts +without having to do any concatenation:</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">Title</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"Hello world!"</span>, +<span style="color: #009900">Body</span> <span style="color: #990000">=</span> <span style="color: #990000"><<</span><span style="color: #FF0000">"Hats off!"</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/html"</span><span style="color: #990000">>></span> +}, [<span style="color: #FF0000">"<html><head><title>"</span>, <span style="color: #009900">Title</span>, <span style="color: #FF0000">"</title></head>"</span>, + <span style="color: #FF0000">"<body><p>"</span>, <span style="color: #009900">Body</span>, <span style="color: #FF0000">"</p></body></html>"</span>], <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>This method of building responses is more efficient than +concatenating. Behind the scenes, each element of the list +is simply a pointer, and those pointers are used directly +when writing to the socket.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_stream_reply">Stream reply</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy provides two functions for initiating a response, +and an additional function for streaming the response body. +Cowboy will add any required headers to the response.</p></div> +<div class="paragraph"><p>When you need to set only the status code, +use <code>cowboy_req:stream_reply/2</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_reply</span></span>(<span style="color: #993399">200</span>, <span style="color: #009900">Req0</span>), + +<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #FF0000">"Hello..."</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Req</span>), +<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #FF0000">"chunked..."</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Req</span>), +<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #FF0000">"world!!"</span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The second argument to <code>cowboy_req:stream_body/3</code> indicates +whether this data terminates the body. Use <code>fin</code> for the +final flag, and <code>nofin</code> otherwise.</p></div> +<div class="paragraph"><p>This snippet does not set a content-type header. This is +not recommended. All responses with a body should have +a content-type. The header can be set beforehand, or +using the <code>cowboy_req:stream_reply/3</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_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/html"</span><span style="color: #990000">>></span> +}, <span style="color: #009900">Req0</span>), + +<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #FF0000">"<html><head>Hello world!</head>"</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Req</span>), +<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #FF0000">"<body><p>Hats off!</p></body></html>"</span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>HTTP provides a few different ways to stream response bodies. +Cowboy will select the most appropriate one based on the HTTP +version and the request and response headers.</p></div> +<div class="paragraph"><p>While not required by any means, it is recommended that you +set the content-length header in the response if you know it +in advance. This will ensure that the best response method +is selected and help clients understand when the response +is fully received.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_preset_response_headers">Preset response headers</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy provides functions to set response headers without +immediately sending them. They are stored in the Req object +and sent as part of the response when a reply function is +called.</p></div> +<div class="paragraph"><p>To set response headers:</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">Req</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">"allow"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"GET"</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Header names must be a lowercase binary.</p></div> +<div class="paragraph"><p>Do not use this function for setting cookies. Refer to +the <a href="../cookies">Cookies</a> chapter for more information.</p></div> +<div class="paragraph"><p>To check if a response header has already been set:</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_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"allow"</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>It returns <code>true</code> if the header was set, <code>false</code> otherwise.</p></div> +<div class="paragraph"><p>To delete a response header that was set previously:</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:delete_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"allow"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_overriding_headers">Overriding headers</h2> +<div class="sectionbody"> +<div class="paragraph"><p>As Cowboy provides different ways of setting response +headers and body, clashes may occur, so it’s important +to understand what happens when a header is set twice.</p></div> +<div class="paragraph"><p>Headers come from five different origins:</p></div> +<div class="ulist"><ul> +<li> +<p> +Protocol-specific headers (for example HTTP/1.1’s connection header) +</p> +</li> +<li> +<p> +Other required headers (for example the date header) +</p> +</li> +<li> +<p> +Preset headers +</p> +</li> +<li> +<p> +Headers given to the reply function +</p> +</li> +<li> +<p> +Set-cookie headers +</p> +</li> +</ul></div> +<div class="paragraph"><p>Cowboy does not allow overriding protocol-specific headers.</p></div> +<div class="paragraph"><p>Set-cookie headers will always be appended at the end of +the list of headers before sending the response.</p></div> +<div class="paragraph"><p>Headers given to the reply function will always override +preset headers and required headers. If a header is found +in two or three of these, then the one in the reply function +is picked and the others are dropped.</p></div> +<div class="paragraph"><p>Similarly, preset headers will always override required +headers.</p></div> +<div class="paragraph"><p>To illustrate, look at the following snippet. Cowboy by +default sends the server header with the value "Cowboy". +We can 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">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">"server"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"yaws"</span><span style="color: #990000">>></span> +}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_preset_response_body">Preset response body</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy provides functions to set the response body without +immediately sending it. It is stored in the Req object and +sent when the reply function is called.</p></div> +<div class="paragraph"><p>To set the response 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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_body</span></span>(<span style="color: #FF0000">"Hello world!"</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>To check if a response body has already been set:</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_resp_body</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>It returns <code>true</code> if the body was set and is non-empty, +<code>false</code> otherwise.</p></div> +<div class="paragraph"><p>The preset response body is only sent if the reply function +used is <code>cowboy_req:reply/2</code> or <code>cowboy_req:reply/3</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_sending_files">Sending files</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy provides a shortcut for sending files. When +using <code>cowboy_req:reply/4</code>, or when presetting the +response header, you can give a <code>sendfile</code> tuple to +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: #FF6600">sendfile</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Length</span>, <span style="color: #009900">Filename</span>}</tt></pre></div></div> +<div class="paragraph"><p>Depending on the values for <code>Offset</code> or <code>Length</code>, the +entire file may be sent, or just a part of it.</p></div> +<div class="paragraph"><p>The length is required even for sending the entire file. +Cowboy sends it in the content-length header.</p></div> +<div class="paragraph"><p>To send a file while replying:</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">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">"image/png"</span> +}, {<span style="color: #FF6600">sendfile</span>, <span style="color: #993399">0</span>, <span style="color: #993399">12345</span>, <span style="color: #FF0000">"path/to/logo.png"</span>}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_push">Push</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The HTTP/2 protocol introduced the ability to push resources +related to the one sent in the response. Cowboy provides two +functions for that purpose: <code>cowboy_req:push/3,4</code>.</p></div> +<div class="paragraph"><p>Push is only available for HTTP/2. Cowboy will automatically +ignore push requests if the protocol doesn’t support it.</p></div> +<div class="paragraph"><p>The push function must be called before any of the reply +functions. Doing otherwise will result in a crash.</p></div> +<div class="paragraph"><p>To push a resource, you need to provide the same information +as a client performing a request would. This includes the +HTTP method, the URI and any necessary request headers.</p></div> +<div class="paragraph"><p>Cowboy by default only requires you to give the path to +the resource and the request headers. The rest of the URI +is taken from the current request (excluding the query +string, set to empty) and the method is GET by default.</p></div> +<div class="paragraph"><p>The following snippet pushes a CSS file that is linked to +in the response:</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:push</span></span>(<span style="color: #FF0000">"/static/style.css"</span>, #{ + <span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/css"</span><span style="color: #990000">>></span> +}, <span style="color: #009900">Req0</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/html"</span><span style="color: #990000">>></span> +}, [<span style="color: #FF0000">"<html><head><title>My web page</title>"</span>, + <span style="color: #FF0000">"<link rel='stylesheet' type='text/css' href='/static/style.css'>"</span>, + <span style="color: #FF0000">"<body><p>Welcome to Erlang!</p></body></html>"</span>], <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>To override the method, scheme, host, port or query string, +simply pass in a fourth argument. The following snippet +uses a different 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="font-weight: bold"><span style="color: #000000">cowboy_req:push</span></span>(<span style="color: #FF0000">"/static/style.css"</span>, #{ + <span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/css"</span><span style="color: #990000">>></span> +}, #{<span style="color: #0000FF">host</span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"cdn.example.org"</span><span style="color: #990000">>></span>}, <span style="color: #009900">Req</span>),</tt></pre></div></div> +<div class="paragraph"><p>Pushed resources don’t have to be files. As long as the push +request is cacheable, safe and does not include a body, the +resource can be pushed.</p></div> +<div class="paragraph"><p>Under the hood, Cowboy handles pushed requests the same as +normal requests: a different process is created which will +ultimately send a response to the client.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/rest_flowcharts/index.html b/docs/en/cowboy/2.0/guide/rest_flowcharts/index.html index bc8427be..88241cbf 100644 --- a/docs/en/cowboy/2.0/guide/rest_flowcharts/index.html +++ b/docs/en/cowboy/2.0/guide/rest_flowcharts/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: REST flowcharts</title> @@ -67,250 +67,253 @@ <h1 class="lined-header"><span>REST flowcharts</span></h1> -<div class="paragraph"><p>This chapter will explain the REST handler state machine through
-a number of different diagrams.</p></div>
-<div class="paragraph"><p>There are four main paths that requests may follow. One for the
-method OPTIONS; one for the methods GET and HEAD; one for the
-methods PUT, POST and PATCH; and one for the method DELETE.</p></div>
-<div class="paragraph"><p>All paths start with the "Start" diagram, and all paths excluding
-the OPTIONS path go through the "Content negotiation" diagram
-and optionally the "Conditional requests" diagram if the resource
-exists.</p></div>
-<div class="paragraph"><p>The red squares refer to another diagram. The light green squares
-indicate a response. Other squares may be either a callback or a
-question answered by Cowboy itself. Green arrows tend to indicate
-the default behavior if the callback is undefined.</p></div>
-<div class="sect1">
-<h2 id="_start">Start</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>All requests start from here.</p></div>
-<div class="imageblock">
-<div class="content">
-<img src="../rest_start.png" alt="REST starting flowchart" />
-</div>
-</div>
-<div class="paragraph"><p>A series of callbacks are called in succession to perform
-a general checkup of the service, the request line and
-request headers.</p></div>
-<div class="paragraph"><p>The request body, if any, is not expected to have been
-received for any of these steps. It is only processed
-at the end of the "PUT, POST and PATCH methods" diagram,
-when all conditions have been met.</p></div>
-<div class="paragraph"><p>The <code>known_methods</code> and <code>allowed_methods</code> callbacks
-return a list of methods. Cowboy then checks if the request
-method is in the list, and stops otherwise.</p></div>
-<div class="paragraph"><p>The <code>is_authorized</code> callback may be used to check that
-access to the resource is authorized. Authentication
-may also be performed as needed. When authorization is
-denied, the return value from the callback must include
-a challenge applicable to the requested resource, which
-will be sent back to the client in the www-authenticate
-header.</p></div>
-<div class="paragraph"><p>This diagram is immediately followed by either the
-"OPTIONS method" diagram when the request method is
-OPTIONS, or the "Content negotiation" diagram otherwise.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_options_method">OPTIONS method</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This diagram only applies to OPTIONS requests.</p></div>
-<div class="imageblock">
-<div class="content">
-<img src="../rest_options.png" alt="REST OPTIONS method flowchart" />
-</div>
-</div>
-<div class="paragraph"><p>The <code>options</code> callback may be used to add information
-about the resource, such as media types or languages
-provided; allowed methods; any extra information. A
-response body may also be set, although clients should
-not be expected to read it.</p></div>
-<div class="paragraph"><p>If the <code>options</code> callback is not defined, Cowboy will
-send a response containing the list of allowed methods
-by default.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_content_negotiation">Content negotiation</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This diagram applies to all request methods other than
-OPTIONS. It is executed right after the "Start" diagram
-is completed.</p></div>
-<div class="imageblock">
-<div class="content">
-<img src="../rest_conneg.png" alt="REST content negotiation flowchart" />
-</div>
-</div>
-<div class="paragraph"><p>The purpose of these steps is to determine an appropriate
-representation to be sent back to the client.</p></div>
-<div class="paragraph"><p>The request may contain any of the accept header; the
-accept-language header; or the accept-charset header.
-When present, Cowboy will parse the headers and then
-call the corresponding callback to obtain the list
-of provided content-type, language or charset for this
-resource. It then automatically select the best match
-based on the request.</p></div>
-<div class="paragraph"><p>If a callback is not defined, Cowboy will select the
-content-type, language or charset that the client
-prefers.</p></div>
-<div class="paragraph"><p>The <code>content_types_provided</code> also returns the name of
-a callback for every content-type it accepts. This
-callback will only be called at the end of the
-"GET and HEAD methods" diagram, when all conditions
-have been met.</p></div>
-<div class="paragraph"><p>The selected content-type, language and charset are
-saved as meta values in the Req object. You <strong>should</strong>
-use the appropriate representation if you set a
-response body manually (alongside an error code,
-for example).</p></div>
-<div class="paragraph"><p>This diagram is immediately followed by
-the "GET and HEAD methods" diagram,
-the "PUT, POST and PATCH methods" diagram,
-or the "DELETE method" diagram, depending on the
-method.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_get_and_head_methods">GET and HEAD methods</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This diagram only applies to GET and HEAD requests.</p></div>
-<div class="paragraph"><p>For a description of the <code>cond</code> step, please see
-the "Conditional requests" diagram.</p></div>
-<div class="imageblock">
-<div class="content">
-<img src="../rest_get_head.png" alt="REST GET/HEAD methods flowchart" />
-</div>
-</div>
-<div class="paragraph"><p>When the resource exists, and the conditional steps
-succeed, the resource can be retrieved.</p></div>
-<div class="paragraph"><p>Cowboy prepares the response by first retrieving
-metadata about the representation, then by calling
-the <code>ProvideResource</code> callback. This is the callback
-you defined for each content-types you returned from
-<code>content_types_provided</code>. This callback returns the body
-that will be sent back to the client, or a fun if the
-body must be streamed.</p></div>
-<div class="paragraph"><p>When the resource does not exist, Cowboy will figure out
-whether the resource existed previously, and if so whether
-it was moved elsewhere in order to redirect the client to
-the new URI.</p></div>
-<div class="paragraph"><p>The <code>moved_permanently</code> and <code>moved_temporarily</code> callbacks
-must return the new location of the resource if it was in
-fact moved.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_put_post_and_patch_methods">PUT, POST and PATCH methods</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This diagram only applies to PUT, POST and PATCH requests.</p></div>
-<div class="paragraph"><p>For a description of the <code>cond</code> step, please see
-the "Conditional requests" diagram.</p></div>
-<div class="imageblock">
-<div class="content">
-<img src="../rest_put_post_patch.png" alt="REST PUT/POST/PATCH methods flowchart" />
-</div>
-</div>
-<div class="paragraph"><p>When the resource exists, first the conditional steps
-are executed. When that succeeds, and the method is PUT,
-Cowboy will call the <code>is_conflict</code> callback. This function
-can be used to prevent potential race conditions, by locking
-the resource for example.</p></div>
-<div class="paragraph"><p>Then all three methods reach the <code>content_types_accepted</code>
-step that we will describe in a few paragraphs.</p></div>
-<div class="paragraph"><p>When the resource does not exist, and the method is PUT,
-Cowboy will check for conflicts and then move on to the
-<code>content_types_accepted</code> step. For other methods, Cowboy
-will figure out whether the resource existed previously,
-and if so whether it was moved elsewhere. If the resource
-is truly non-existent, the method is POST and the call
-for <code>allow_missing_post</code> returns <code>true</code>, then Cowboy will
-move on to the <code>content_types_accepted</code> step. Otherwise
-the request processing ends there.</p></div>
-<div class="paragraph"><p>The <code>moved_permanently</code> and <code>moved_temporarily</code> callbacks
-must return the new location of the resource if it was in
-fact moved.</p></div>
-<div class="paragraph"><p>The <code>content_types_accepted</code> returns a list of
-content-types it accepts, but also the name of a callback
-for each of them. Cowboy will select the appropriate
-callback for processing the request body and call it.</p></div>
-<div class="paragraph"><p>This callback may return one of three different return
-values.</p></div>
-<div class="paragraph"><p>If an error occurred while processing the request body,
-it must return <code>false</code> and Cowboy will send an
-appropriate error response.</p></div>
-<div class="paragraph"><p>If the method is POST, then you may return <code>true</code> with
-an URI of where the resource has been created. This is
-especially useful for writing handlers for collections.</p></div>
-<div class="paragraph"><p>Otherwise, return <code>true</code> to indicate success. Cowboy
-will select the appropriate response to be sent depending
-on whether a resource has been created, rather than
-modified, and on the availability of a location header
-or a body in the response.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_delete_method">DELETE method</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This diagram only applies to DELETE requests.</p></div>
-<div class="paragraph"><p>For a description of the <code>cond</code> step, please see
-the "Conditional requests" diagram.</p></div>
-<div class="imageblock">
-<div class="content">
-<img src="../rest_delete.png" alt="REST DELETE method flowchart" />
-</div>
-</div>
-<div class="paragraph"><p>When the resource exists, and the conditional steps
-succeed, the resource can be deleted.</p></div>
-<div class="paragraph"><p>Deleting the resource is a two steps process. First
-the callback <code>delete_resource</code> is executed. Use this
-callback to delete the resource.</p></div>
-<div class="paragraph"><p>Because the resource may be cached, you must also
-delete all cached representations of this resource
-in the system. This operation may take a while though,
-so you may return before it finished.</p></div>
-<div class="paragraph"><p>Cowboy will then call the <code>delete_completed</code> callback.
-If you know that the resource has been completely
-deleted from your system, including from caches, then
-you can return <code>true</code>. If any doubts persist, return
-<code>false</code>. Cowboy will assume <code>true</code> by default.</p></div>
-<div class="paragraph"><p>To finish, Cowboy checks if you set a response body,
-and depending on that, sends the appropriate response.</p></div>
-<div class="paragraph"><p>When the resource does not exist, Cowboy will figure out
-whether the resource existed previously, and if so whether
-it was moved elsewhere in order to redirect the client to
-the new URI.</p></div>
-<div class="paragraph"><p>The <code>moved_permanently</code> and <code>moved_temporarily</code> callbacks
-must return the new location of the resource if it was in
-fact moved.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_conditional_requests">Conditional requests</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This diagram applies to all request methods other than
-OPTIONS. It is executed right after the <code>resource_exists</code>
-callback, when the resource exists.</p></div>
-<div class="imageblock">
-<div class="content">
-<img src="../rest_cond.png" alt="REST conditional requests flowchart" />
-</div>
-</div>
-<div class="paragraph"><p>A request becomes conditional when it includes either of
-the if-match header; the if-unmodified-since header; the
-if-none-match header; or the if-modified-since header.</p></div>
-<div class="paragraph"><p>If the condition fails, the request ends immediately
-without any retrieval or modification of the resource.</p></div>
-<div class="paragraph"><p>The <code>generate_etag</code> and <code>last_modified</code> are called as
-needed. Cowboy will only call them once and then cache
-the results for subsequent use.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter will explain the REST handler state machine through +a number of different diagrams.</p></div> +<div class="paragraph"><p>There are four main paths that requests may follow. One for the +method OPTIONS; one for the methods GET and HEAD; one for the +methods PUT, POST and PATCH; and one for the method DELETE.</p></div> +<div class="paragraph"><p>All paths start with the "Start" diagram, and all paths excluding +the OPTIONS path go through the "Content negotiation" diagram +and optionally the "Conditional requests" diagram if the resource +exists.</p></div> +<div class="paragraph"><p>The red squares refer to another diagram. The light green squares +indicate a response. Other squares may be either a callback or a +question answered by Cowboy itself. Green arrows tend to indicate +the default behavior if the callback is undefined.</p></div> +<div class="sect1"> +<h2 id="_start">Start</h2> +<div class="sectionbody"> +<div class="paragraph"><p>All requests start from here.</p></div> +<div class="imageblock"> +<div class="content"> +<img src="../rest_start.png" alt="REST starting flowchart" /> +</div> +</div> +<div class="paragraph"><p>A series of callbacks are called in succession to perform +a general checkup of the service, the request line and +request headers.</p></div> +<div class="paragraph"><p>The request body, if any, is not expected to have been +received for any of these steps. It is only processed +at the end of the "PUT, POST and PATCH methods" diagram, +when all conditions have been met.</p></div> +<div class="paragraph"><p>The <code>known_methods</code> and <code>allowed_methods</code> callbacks +return a list of methods. Cowboy then checks if the request +method is in the list, and stops otherwise.</p></div> +<div class="paragraph"><p>The <code>is_authorized</code> callback may be used to check that +access to the resource is authorized. Authentication +may also be performed as needed. When authorization is +denied, the return value from the callback must include +a challenge applicable to the requested resource, which +will be sent back to the client in the www-authenticate +header.</p></div> +<div class="paragraph"><p>This diagram is immediately followed by either the +"OPTIONS method" diagram when the request method is +OPTIONS, or the "Content negotiation" diagram otherwise.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_options_method">OPTIONS method</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This diagram only applies to OPTIONS requests.</p></div> +<div class="imageblock"> +<div class="content"> +<img src="../rest_options.png" alt="REST OPTIONS method flowchart" /> +</div> +</div> +<div class="paragraph"><p>The <code>options</code> callback may be used to add information +about the resource, such as media types or languages +provided; allowed methods; any extra information. A +response body may also be set, although clients should +not be expected to read it.</p></div> +<div class="paragraph"><p>If the <code>options</code> callback is not defined, Cowboy will +send a response containing the list of allowed methods +by default.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_content_negotiation">Content negotiation</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This diagram applies to all request methods other than +OPTIONS. It is executed right after the "Start" diagram +is completed.</p></div> +<div class="imageblock"> +<div class="content"> +<img src="../rest_conneg.png" alt="REST content negotiation flowchart" /> +</div> +</div> +<div class="paragraph"><p>The purpose of these steps is to determine an appropriate +representation to be sent back to the client.</p></div> +<div class="paragraph"><p>The request may contain any of the accept header; the +accept-language header; or the accept-charset header. +When present, Cowboy will parse the headers and then +call the corresponding callback to obtain the list +of provided content-type, language or charset for this +resource. It then automatically select the best match +based on the request.</p></div> +<div class="paragraph"><p>If a callback is not defined, Cowboy will select the +content-type, language or charset that the client +prefers.</p></div> +<div class="paragraph"><p>The <code>content_types_provided</code> also returns the name of +a callback for every content-type it accepts. This +callback will only be called at the end of the +"GET and HEAD methods" diagram, when all conditions +have been met.</p></div> +<div class="paragraph"><p>The selected content-type, language and charset are +saved as meta values in the Req object. You <strong>should</strong> +use the appropriate representation if you set a +response body manually (alongside an error code, +for example).</p></div> +<div class="paragraph"><p>This diagram is immediately followed by +the "GET and HEAD methods" diagram, +the "PUT, POST and PATCH methods" diagram, +or the "DELETE method" diagram, depending on the +method.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_get_and_head_methods">GET and HEAD methods</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This diagram only applies to GET and HEAD requests.</p></div> +<div class="paragraph"><p>For a description of the <code>cond</code> step, please see +the "Conditional requests" diagram.</p></div> +<div class="imageblock"> +<div class="content"> +<img src="../rest_get_head.png" alt="REST GET/HEAD methods flowchart" /> +</div> +</div> +<div class="paragraph"><p>When the resource exists, and the conditional steps +succeed, the resource can be retrieved.</p></div> +<div class="paragraph"><p>Cowboy prepares the response by first retrieving +metadata about the representation, then by calling +the <code>ProvideResource</code> callback. This is the callback +you defined for each content-types you returned from +<code>content_types_provided</code>. This callback returns the body +that will be sent back to the client, or a fun if the +body must be streamed.</p></div> +<div class="paragraph"><p>When the resource does not exist, Cowboy will figure out +whether the resource existed previously, and if so whether +it was moved elsewhere in order to redirect the client to +the new URI.</p></div> +<div class="paragraph"><p>The <code>moved_permanently</code> and <code>moved_temporarily</code> callbacks +must return the new location of the resource if it was in +fact moved.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_put_post_and_patch_methods">PUT, POST and PATCH methods</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This diagram only applies to PUT, POST and PATCH requests.</p></div> +<div class="paragraph"><p>For a description of the <code>cond</code> step, please see +the "Conditional requests" diagram.</p></div> +<div class="imageblock"> +<div class="content"> +<img src="../rest_put_post_patch.png" alt="REST PUT/POST/PATCH methods flowchart" /> +</div> +</div> +<div class="paragraph"><p>When the resource exists, first the conditional steps +are executed. When that succeeds, and the method is PUT, +Cowboy will call the <code>is_conflict</code> callback. This function +can be used to prevent potential race conditions, by locking +the resource for example.</p></div> +<div class="paragraph"><p>Then all three methods reach the <code>content_types_accepted</code> +step that we will describe in a few paragraphs.</p></div> +<div class="paragraph"><p>When the resource does not exist, and the method is PUT, +Cowboy will check for conflicts and then move on to the +<code>content_types_accepted</code> step. For other methods, Cowboy +will figure out whether the resource existed previously, +and if so whether it was moved elsewhere. If the resource +is truly non-existent, the method is POST and the call +for <code>allow_missing_post</code> returns <code>true</code>, then Cowboy will +move on to the <code>content_types_accepted</code> step. Otherwise +the request processing ends there.</p></div> +<div class="paragraph"><p>The <code>moved_permanently</code> and <code>moved_temporarily</code> callbacks +must return the new location of the resource if it was in +fact moved.</p></div> +<div class="paragraph"><p>The <code>content_types_accepted</code> returns a list of +content-types it accepts, but also the name of a callback +for each of them. Cowboy will select the appropriate +callback for processing the request body and call it.</p></div> +<div class="paragraph"><p>This callback may return one of three different return +values.</p></div> +<div class="paragraph"><p>If an error occurred while processing the request body, +it must return <code>false</code> and Cowboy will send an +appropriate error response.</p></div> +<div class="paragraph"><p>If the method is POST, then you may return <code>true</code> with +an URI of where the resource has been created. This is +especially useful for writing handlers for collections.</p></div> +<div class="paragraph"><p>Otherwise, return <code>true</code> to indicate success. Cowboy +will select the appropriate response to be sent depending +on whether a resource has been created, rather than +modified, and on the availability of a location header +or a body in the response.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_delete_method">DELETE method</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This diagram only applies to DELETE requests.</p></div> +<div class="paragraph"><p>For a description of the <code>cond</code> step, please see +the "Conditional requests" diagram.</p></div> +<div class="imageblock"> +<div class="content"> +<img src="../rest_delete.png" alt="REST DELETE method flowchart" /> +</div> +</div> +<div class="paragraph"><p>When the resource exists, and the conditional steps +succeed, the resource can be deleted.</p></div> +<div class="paragraph"><p>Deleting the resource is a two steps process. First +the callback <code>delete_resource</code> is executed. Use this +callback to delete the resource.</p></div> +<div class="paragraph"><p>Because the resource may be cached, you must also +delete all cached representations of this resource +in the system. This operation may take a while though, +so you may return before it finished.</p></div> +<div class="paragraph"><p>Cowboy will then call the <code>delete_completed</code> callback. +If you know that the resource has been completely +deleted from your system, including from caches, then +you can return <code>true</code>. If any doubts persist, return +<code>false</code>. Cowboy will assume <code>true</code> by default.</p></div> +<div class="paragraph"><p>To finish, Cowboy checks if you set a response body, +and depending on that, sends the appropriate response.</p></div> +<div class="paragraph"><p>When the resource does not exist, Cowboy will figure out +whether the resource existed previously, and if so whether +it was moved elsewhere in order to redirect the client to +the new URI.</p></div> +<div class="paragraph"><p>The <code>moved_permanently</code> and <code>moved_temporarily</code> callbacks +must return the new location of the resource if it was in +fact moved.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_conditional_requests">Conditional requests</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This diagram applies to all request methods other than +OPTIONS. It is executed right after the <code>resource_exists</code> +callback, when the resource exists.</p></div> +<div class="imageblock"> +<div class="content"> +<img src="../rest_cond.png" alt="REST conditional requests flowchart" /> +</div> +</div> +<div class="paragraph"><p>A request becomes conditional when it includes either of +the if-match header; the if-unmodified-since header; the +if-none-match header; or the if-modified-since header.</p></div> +<div class="paragraph"><p>If the condition fails, the request ends immediately +without any retrieval or modification of the resource.</p></div> +<div class="paragraph"><p>The <code>generate_etag</code> and <code>last_modified</code> are called as +needed. Cowboy will only call them once and then cache +the results for subsequent use.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/rest_get_head.png b/docs/en/cowboy/2.0/guide/rest_get_head.png Binary files differindex efee892a..211ab603 100644 --- a/docs/en/cowboy/2.0/guide/rest_get_head.png +++ b/docs/en/cowboy/2.0/guide/rest_get_head.png diff --git a/docs/en/cowboy/2.0/guide/rest_get_head.svg b/docs/en/cowboy/2.0/guide/rest_get_head.svg index c78e9399..92030cf3 100644 --- a/docs/en/cowboy/2.0/guide/rest_get_head.svg +++ b/docs/en/cowboy/2.0/guide/rest_get_head.svg @@ -15,7 +15,7 @@ height="1052.3622047" id="svg2" version="1.1" - inkscape:version="0.48.4 r9939" + inkscape:version="0.92.1 r" sodipodi:docname="rest_get_head.svg" inkscape:export-filename="/home/essen/Dropbox/Public/drawing.png" inkscape:export-xdpi="90" @@ -65,15 +65,15 @@ inkscape:pageopacity="1" inkscape:pageshadow="2" inkscape:zoom="1.4142136" - inkscape:cx="122.28875" - inkscape:cy="777.29526" + inkscape:cx="353.51266" + inkscape:cy="522.73683" inkscape:document-units="px" inkscape:current-layer="layer1" showgrid="false" - inkscape:window-width="2560" - inkscape:window-height="1402" + inkscape:window-width="1920" + inkscape:window-height="1043" inkscape:window-x="0" - inkscape:window-y="38" + inkscape:window-y="0" inkscape:window-maximized="1" inkscape:snap-global="true" showguides="true"> @@ -93,7 +93,7 @@ <dc:format>image/svg+xml</dc:format> <dc:type rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> - <dc:title></dc:title> + <dc:title /> </cc:Work> </rdf:RDF> </metadata> @@ -514,135 +514,135 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="-58.692513" y="114.39204" - id="text5371" - sodipodi:linespacing="125%"><tspan + id="text5371"><tspan sodipodi:role="line" id="tspan5373" x="-58.692513" - y="114.39204">some text</tspan></text> + y="114.39204" + style="font-size:16px;line-height:1.25;font-family:sans-serif">some text</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="-58.692513" y="53.112247" - id="text5371-2" - sodipodi:linespacing="125%"><tspan + id="text5371-2"><tspan sodipodi:role="line" id="tspan5373-6" x="-58.692513" - y="53.112247">some text</tspan></text> + y="53.112247" + style="font-size:16px;line-height:1.25;font-family:sans-serif">some text</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="213.07524" y="379.78381" id="text5371-2-3" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-7" x="213.07524" - y="379.78381">last_modified</tspan></text> + y="379.78381" + style="font-size:16px;line-height:1.25;font-family:sans-serif">last_modified</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="212.74321" y="546.59912" id="text5371-2-3-0" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-7-3" x="212.74321" - y="546.59912">ProvideResource</tspan></text> + y="546.59912" + style="font-size:16px;line-height:1.25;font-family:sans-serif">ProvideCallback</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="-58.692513" y="236.95154" - id="text5371-4" - sodipodi:linespacing="125%"><tspan + id="text5371-4"><tspan sodipodi:role="line" id="tspan5373-9" x="-58.692513" - y="236.95154">some text</tspan></text> + y="236.95154" + style="font-size:16px;line-height:1.25;font-family:sans-serif">some text</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="359.14185" y="50.482433" id="text5371-4-0" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" x="359.14185" y="50.482433" - id="tspan17171">conneg</tspan></text> + id="tspan17171" + style="font-size:16px;line-height:1.25;font-family:sans-serif">conneg</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="212.77055" y="627.34662" id="text5371-2-9" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-8" x="212.77055" - y="627.34662">multiple_choices</tspan></text> + y="627.34662" + style="font-size:16px;line-height:1.25;font-family:sans-serif">multiple_choices</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="358.52466" y="134.49161" id="text5371-2-95" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-80" x="358.52466" - y="134.49161">resource_exists</tspan></text> + y="134.49161" + style="font-size:16px;line-height:1.25;font-family:sans-serif">resource_exists</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="213.38774" y="296.80188" id="text5371-2-32" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-27" x="213.38774" - y="296.80188">generate_etag</tspan></text> + y="296.80188" + style="font-size:16px;line-height:1.25;font-family:sans-serif">generate_etag</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="213.05571" y="462.5274" id="text5371-2-74" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18" x="213.05571" - y="462.5274">expires</tspan></text> + y="462.5274" + style="font-size:16px;line-height:1.25;font-family:sans-serif">expires</tspan></text> <rect style="fill:#d1f2a5;fill-opacity:1;fill-rule:nonzero;stroke:#a9ca7d;stroke-width:3;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-1-2" @@ -653,32 +653,32 @@ rx="15" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="251.83722" y="175.92931" id="text5371-2-391" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-63" x="251.83722" - y="175.92931">true</tspan></text> + y="175.92931" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="161.54012" y="670.38055" id="text5371-2-8" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-3" x="161.54012" - y="670.38055">false</tspan></text> + y="670.38055" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <g transform="matrix(0,-1,1,0,-513.31414,353.05561)" id="g5650-2"> @@ -707,18 +707,18 @@ </g> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="447.26678" y="176.39024" id="text5371-4-6" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-0" x="447.26678" - y="176.39024">false</tspan></text> + y="176.39024" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <g transform="translate(563.72619,-141.76777)" id="g5650-2-2"> @@ -758,19 +758,19 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="-544.69421" y="-354.17184" id="text5371-2-3-0-7" - sodipodi:linespacing="125%" - transform="matrix(0,-1,1,0,0,0)" + transform="rotate(-90)" inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-7-3-9" x="-544.69421" - y="-354.17184">middlewares</tspan></text> + y="-354.17184" + style="font-size:16px;line-height:1.25;font-family:sans-serif">middlewares</tspan></text> <g transform="matrix(0,-1,1,0,-508.93096,565.23553)" id="g5650-2-0-4" @@ -804,32 +804,32 @@ </g> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="46.409981" y="711.18011" id="text5371-4-3-9" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-62-9" x="46.409981" - y="711.18011">true</tspan></text> + y="711.18011" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="545.12921" y="257.43518" id="text5371-4-4-9" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6" x="545.12921" - y="257.43518">true</tspan></text> + y="257.43518" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <g transform="matrix(0.70710678,0.70710678,-0.70710678,0.70710678,547.47379,-62.310424)" id="g5650-9-9" @@ -872,18 +872,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="213.38774" y="216.5154" id="text5371-4-0-8" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" x="213.38774" y="216.5154" - id="tspan17171-6">cond</tspan></text> + id="tspan17171-6" + style="font-size:16px;line-height:1.25;font-family:sans-serif">cond</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-1" @@ -897,18 +897,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="212.88774" y="792.61121" id="text5371-43-5" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-62" x="212.88774" - y="792.61121">300 multiple choices</tspan></text> + y="792.61121" + style="font-size:16px;line-height:1.25;font-family:sans-serif">300 multiple choices</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-8" @@ -922,18 +922,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="212.35258" y="711.50043" id="text5371-43-3" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-1" x="212.35258" - y="711.50043">200 OK</tspan></text> + y="711.50043" + style="font-size:16px;line-height:1.25;font-family:sans-serif">200 OK</tspan></text> <g transform="matrix(0,-1,-1,0,1028.2004,317.70407)" id="g5650-2-0-4-3-8" @@ -978,32 +978,32 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="505.77957" y="216.51541" id="text5371-2-32-6" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-27-8" x="505.77957" - y="216.51541">has if-match?</tspan></text> + y="216.51541" + style="font-size:16px;line-height:1.25;font-family:sans-serif">has if-match?</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="651.74426" y="299.27689" id="text5371-2-391-5" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-63-7" x="651.74426" - y="299.27689">false</tspan></text> + y="299.27689" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <g transform="translate(563.72619,22.800669)" id="g5650-0-6" @@ -1077,18 +1077,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="505.94363" y="379.78381" id="text5371-2-32-8" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-27-1" x="505.94363" - y="379.78381">previously_existed</tspan></text> + y="379.78381" + style="font-size:16px;line-height:1.25;font-family:sans-serif">previously_existed</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-5" @@ -1102,32 +1102,32 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="506.2796" y="463.83755" id="text5371-43-2" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-9" x="506.2796" - y="463.83755">404 not found</tspan></text> + y="463.83755" + style="font-size:16px;line-height:1.25;font-family:sans-serif">404 not found</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="528.75421" y="422.69736" id="text5371-2-8-9" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-3-4" x="528.75421" - y="422.69736">false</tspan></text> + y="422.69736" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <g transform="translate(563.72619,187.85116)" id="g5650-2-2-17"> @@ -1198,18 +1198,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="505.45535" y="544.82568" id="text5371-2-74-0" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2" x="505.45535" - y="544.82568">moved_permanently</tspan></text> + y="544.82568" + style="font-size:16px;line-height:1.25;font-family:sans-serif">moved_permanently</tspan></text> <g transform="matrix(0,-1,-1,0,347.00351,567.35686)" id="g5650-2-0-4-3-8-9" @@ -1254,60 +1254,60 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="506.2796" y="297.7261" id="text5371-43" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3" x="506.2796" - y="297.7261">412 precondition failed</tspan></text> + y="297.7261" + style="font-size:16px;line-height:1.25;font-family:sans-serif">412 precondition failed</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="668.11926" y="463.37662" id="text5371-4-3-9-8" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-62-9-9" x="668.11926" - y="463.37662">true</tspan></text> + y="463.37662" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="549.12921" y="587.59863" id="text5371-4-4-9-3" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-2" x="549.12921" - y="587.59863">true*</tspan></text> + y="587.59863" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true*</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="651.74426" y="628.87946" id="text5371-2-391-5-5-1" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-63-7-9-9" x="651.74426" - y="628.87946">false</tspan></text> + y="628.87946" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-5-9" @@ -1321,18 +1321,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="505.57257" y="627.32867" id="text5371-43-2-9" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-9-7" x="505.57257" - y="627.32867">301 moved permanently</tspan></text> + y="627.32867" + style="font-size:16px;line-height:1.25;font-family:sans-serif">301 moved permanently</tspan></text> <g transform="translate(563.72619,353.12604)" id="g5650-2-2-65"> @@ -1403,46 +1403,46 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="505.45535" y="709.62695" id="text5371-2-74-0-7" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2-8" x="505.45535" - y="709.62695">moved_temporarily</tspan></text> + y="709.62695" + style="font-size:16px;line-height:1.25;font-family:sans-serif">moved_temporarily</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="549.12921" y="752.64056" id="text5371-4-4-9-3-2" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-2-6" x="549.12921" - y="752.64056">true*</tspan></text> + y="752.64056" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true*</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="651.74426" y="794.16199" id="text5371-2-391-5-5-1-0" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-63-7-9-9-2" x="651.74426" - y="794.16199">false</tspan></text> + y="794.16199" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-5-9-2" @@ -1456,18 +1456,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="505.57257" y="792.61121" id="text5371-43-2-9-7" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-9-7-8" x="505.57257" - y="792.61121">307 moved temporarily</tspan></text> + y="792.61121" + style="font-size:16px;line-height:1.25;font-family:sans-serif">307 moved temporarily</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-5-9-2-4" @@ -1481,18 +1481,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="505.97882" y="874.99164" id="text5371-43-2-9-7-3" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-9-7-8-7" x="505.97882" - y="874.99164">410 gone</tspan></text> + y="874.99164" + style="font-size:16px;line-height:1.25;font-family:sans-serif">410 gone</tspan></text> <g transform="translate(31.619614,4.2328831)" id="g5650-2-2-6"> 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 f27c58fc..93a311d0 100644 --- a/docs/en/cowboy/2.0/guide/rest_handlers/index.html +++ b/docs/en/cowboy/2.0/guide/rest_handlers/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: REST handlers</title> @@ -67,289 +67,292 @@ <h1 class="lined-header"><span>REST handlers</span></h1> -<div class="paragraph"><p>REST is implemented in Cowboy as a sub protocol. The request
-is handled as a state machine with many optional callbacks
-describing the resource and modifying the machine’s behavior.</p></div>
-<div class="paragraph"><p>The REST handler is the recommended way to handle HTTP requests.</p></div>
-<div class="sect1">
-<h2 id="_initialization">Initialization</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>First, the <code>init/2</code> callback is called. This callback is common
-to all handlers. To use REST for the current request, this function
-must return a <code>cowboy_rest</code> tuple.</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">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
-will be called if it is defined.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_methods">Methods</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The REST component has code for handling the following HTTP methods:
-HEAD, GET, POST, PATCH, PUT, DELETE and OPTIONS.</p></div>
-<div class="paragraph"><p>Other methods can be accepted, however they have no specific callback
-defined for them at this time.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_callbacks">Callbacks</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>All callbacks are optional. Some may become mandatory depending
-on what other defined callbacks return. The various flowcharts
-in the next chapter should be a useful to determine which callbacks
-you need.</p></div>
-<div class="paragraph"><p>All callbacks take two arguments, the Req object and the State,
-and return a three-element tuple of the form <code>{Value, Req, State}</code>.</p></div>
-<div class="paragraph"><p>All callbacks can also return <code>{stop, Req, State}</code> to stop execution
-of the request.</p></div>
-<div class="paragraph"><p>The following table summarizes the callbacks and their default values.
-If the callback isn’t defined, then the default value will be used.
-Please look at the flowcharts to find out the result of each return
-value.</p></div>
-<div class="paragraph"><p>In the following table, "skip" means the callback is entirely skipped
-if it is undefined, moving directly to the next step. Similarly,
-"none" means there is no default value for this callback.</p></div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="border"
-cellspacing="0" cellpadding="4">
-<col width="50%" />
-<col width="50%" />
-<thead>
-<tr>
-<th align="left" valign="top"> Callback name </th>
-<th align="center" valign="top"> Default value</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table">allowed_methods</p></td>
-<td align="center" valign="top"><p class="table"><code>[<<"GET">>, <<"HEAD">>, <<"OPTIONS">>]</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">allow_missing_post</p></td>
-<td align="center" valign="top"><p class="table"><code>true</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">charsets_provided</p></td>
-<td align="center" valign="top"><p class="table">skip</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">content_types_accepted</p></td>
-<td align="center" valign="top"><p class="table">none</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">content_types_provided</p></td>
-<td align="center" valign="top"><p class="table"><code>[{{ <<"text">>, <<"html">>, '*'}, to_html}]</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">delete_completed</p></td>
-<td align="center" valign="top"><p class="table"><code>true</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">delete_resource</p></td>
-<td align="center" valign="top"><p class="table"><code>false</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">expires</p></td>
-<td align="center" valign="top"><p class="table"><code>undefined</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">forbidden</p></td>
-<td align="center" valign="top"><p class="table"><code>false</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">generate_etag</p></td>
-<td align="center" valign="top"><p class="table"><code>undefined</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">is_authorized</p></td>
-<td align="center" valign="top"><p class="table"><code>true</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">is_conflict</p></td>
-<td align="center" valign="top"><p class="table"><code>false</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">known_methods</p></td>
-<td align="center" valign="top"><p class="table"><code>[<<"GET">>, <<"HEAD">>, <<"POST">>, <<"PUT">>, <<"PATCH">>, <<"DELETE">>, <<"OPTIONS">>]</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">languages_provided</p></td>
-<td align="center" valign="top"><p class="table">skip</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">last_modified</p></td>
-<td align="center" valign="top"><p class="table"><code>undefined</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">malformed_request</p></td>
-<td align="center" valign="top"><p class="table"><code>false</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">moved_permanently</p></td>
-<td align="center" valign="top"><p class="table"><code>false</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">moved_temporarily</p></td>
-<td align="center" valign="top"><p class="table"><code>false</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">multiple_choices</p></td>
-<td align="center" valign="top"><p class="table"><code>false</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">options</p></td>
-<td align="center" valign="top"><p class="table"><code>ok</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">previously_existed</p></td>
-<td align="center" valign="top"><p class="table"><code>false</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">resource_exists</p></td>
-<td align="center" valign="top"><p class="table"><code>true</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">service_available</p></td>
-<td align="center" valign="top"><p class="table"><code>true</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">uri_too_long</p></td>
-<td align="center" valign="top"><p class="table"><code>false</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">valid_content_headers</p></td>
-<td align="center" valign="top"><p class="table"><code>true</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">valid_entity_length</p></td>
-<td align="center" valign="top"><p class="table"><code>true</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">variances</p></td>
-<td align="center" valign="top"><p class="table"><code>[]</code></p></td>
-</tr>
-</tbody>
-</table>
-</div>
-<div class="paragraph"><p>As you can see, Cowboy tries to move on with the request whenever
-possible by using well thought out default values.</p></div>
-<div class="paragraph"><p>In addition to these, there can be any number of user-defined
-callbacks that are specified through <code>content_types_accepted/2</code>
-and <code>content_types_provided/2</code>. They can take any name, however
-it is recommended to use a separate prefix for the callbacks of
-each function. For example, <code>from_html</code> and <code>to_html</code> indicate
-in the first case that we’re accepting a resource given as HTML,
-and in the second case that we send one as HTML.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_meta_data">Meta data</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy will set informative values to the Req object at various
-points of the execution. You can retrieve them by matching the
-Req object directly. The values are defined in the following table:</p></div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="border"
-cellspacing="0" cellpadding="4">
-<col width="50%" />
-<col width="50%" />
-<thead>
-<tr>
-<th align="left" valign="top"> Key </th>
-<th align="left" valign="top"> Details</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table">media_type</p></td>
-<td align="left" valign="top"><p class="table">The content-type negotiated for the response entity.</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">language</p></td>
-<td align="left" valign="top"><p class="table">The language negotiated for the response entity.</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">charset</p></td>
-<td align="left" valign="top"><p class="table">The charset negotiated for the response entity.</p></td>
-</tr>
-</tbody>
-</table>
-</div>
-<div class="paragraph"><p>They can be used to send a proper body with the response to a
-request that used a method other than HEAD or GET.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_response_headers">Response headers</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy will set response headers automatically over the execution
-of the REST code. They are listed in the following table.</p></div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="border"
-cellspacing="0" cellpadding="4">
-<col width="50%" />
-<col width="50%" />
-<thead>
-<tr>
-<th align="left" valign="top"> Header name </th>
-<th align="left" valign="top"> Details</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table">content-language</p></td>
-<td align="left" valign="top"><p class="table">Language used in the response body</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">content-type</p></td>
-<td align="left" valign="top"><p class="table">Media type and charset of the response body</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">etag</p></td>
-<td align="left" valign="top"><p class="table">Etag of the resource</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">expires</p></td>
-<td align="left" valign="top"><p class="table">Expiration date of the resource</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">last-modified</p></td>
-<td align="left" valign="top"><p class="table">Last modification date for the resource</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">location</p></td>
-<td align="left" valign="top"><p class="table">Relative or absolute URI to the requested resource</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">vary</p></td>
-<td align="left" valign="top"><p class="table">List of headers that may change the representation of the resource</p></td>
-</tr>
-</tbody>
-</table>
-</div>
-</div>
-</div>
+<div class="paragraph"><p>REST is implemented in Cowboy as a sub protocol. The request +is handled as a state machine with many optional callbacks +describing the resource and modifying the machine’s behavior.</p></div> +<div class="paragraph"><p>The REST handler is the recommended way to handle HTTP requests.</p></div> +<div class="sect1"> +<h2 id="_initialization">Initialization</h2> +<div class="sectionbody"> +<div class="paragraph"><p>First, the <code>init/2</code> callback is called. This callback is common +to all handlers. To use REST for the current request, this function +must return a <code>cowboy_rest</code> tuple.</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">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 +will be called if it is defined.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_methods">Methods</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The REST component has code for handling the following HTTP methods: +HEAD, GET, POST, PATCH, PUT, DELETE and OPTIONS.</p></div> +<div class="paragraph"><p>Other methods can be accepted, however they have no specific callback +defined for them at this time.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_callbacks">Callbacks</h2> +<div class="sectionbody"> +<div class="paragraph"><p>All callbacks are optional. Some may become mandatory depending +on what other defined callbacks return. The various flowcharts +in the next chapter should be a useful to determine which callbacks +you need.</p></div> +<div class="paragraph"><p>All callbacks take two arguments, the Req object and the State, +and return a three-element tuple of the form <code>{Value, Req, State}</code>.</p></div> +<div class="paragraph"><p>All callbacks can also return <code>{stop, Req, State}</code> to stop execution +of the request.</p></div> +<div class="paragraph"><p>The following table summarizes the callbacks and their default values. +If the callback isn’t defined, then the default value will be used. +Please look at the flowcharts to find out the result of each return +value.</p></div> +<div class="paragraph"><p>In the following table, "skip" means the callback is entirely skipped +if it is undefined, moving directly to the next step. Similarly, +"none" means there is no default value for this callback.</p></div> +<div class="tableblock"> +<table rules="all" +width="100%" +frame="border" +cellspacing="0" cellpadding="4"> +<col width="50%" /> +<col width="50%" /> +<thead> +<tr> +<th align="left" valign="top"> Callback name </th> +<th align="center" valign="top"> Default value</th> +</tr> +</thead> +<tbody> +<tr> +<td align="left" valign="top"><p class="table">allowed_methods</p></td> +<td align="center" valign="top"><p class="table"><code>[<<"GET">>, <<"HEAD">>, <<"OPTIONS">>]</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">allow_missing_post</p></td> +<td align="center" valign="top"><p class="table"><code>true</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">charsets_provided</p></td> +<td align="center" valign="top"><p class="table">skip</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">content_types_accepted</p></td> +<td align="center" valign="top"><p class="table">none</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">content_types_provided</p></td> +<td align="center" valign="top"><p class="table"><code>[{{ <<"text">>, <<"html">>, '*'}, to_html}]</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">delete_completed</p></td> +<td align="center" valign="top"><p class="table"><code>true</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">delete_resource</p></td> +<td align="center" valign="top"><p class="table"><code>false</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">expires</p></td> +<td align="center" valign="top"><p class="table"><code>undefined</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">forbidden</p></td> +<td align="center" valign="top"><p class="table"><code>false</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">generate_etag</p></td> +<td align="center" valign="top"><p class="table"><code>undefined</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">is_authorized</p></td> +<td align="center" valign="top"><p class="table"><code>true</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">is_conflict</p></td> +<td align="center" valign="top"><p class="table"><code>false</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">known_methods</p></td> +<td align="center" valign="top"><p class="table"><code>[<<"GET">>, <<"HEAD">>, <<"POST">>, <<"PUT">>, <<"PATCH">>, <<"DELETE">>, <<"OPTIONS">>]</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">languages_provided</p></td> +<td align="center" valign="top"><p class="table">skip</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">last_modified</p></td> +<td align="center" valign="top"><p class="table"><code>undefined</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">malformed_request</p></td> +<td align="center" valign="top"><p class="table"><code>false</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">moved_permanently</p></td> +<td align="center" valign="top"><p class="table"><code>false</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">moved_temporarily</p></td> +<td align="center" valign="top"><p class="table"><code>false</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">multiple_choices</p></td> +<td align="center" valign="top"><p class="table"><code>false</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">options</p></td> +<td align="center" valign="top"><p class="table"><code>ok</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">previously_existed</p></td> +<td align="center" valign="top"><p class="table"><code>false</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">resource_exists</p></td> +<td align="center" valign="top"><p class="table"><code>true</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">service_available</p></td> +<td align="center" valign="top"><p class="table"><code>true</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">uri_too_long</p></td> +<td align="center" valign="top"><p class="table"><code>false</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">valid_content_headers</p></td> +<td align="center" valign="top"><p class="table"><code>true</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">valid_entity_length</p></td> +<td align="center" valign="top"><p class="table"><code>true</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">variances</p></td> +<td align="center" valign="top"><p class="table"><code>[]</code></p></td> +</tr> +</tbody> +</table> +</div> +<div class="paragraph"><p>As you can see, Cowboy tries to move on with the request whenever +possible by using well thought out default values.</p></div> +<div class="paragraph"><p>In addition to these, there can be any number of user-defined +callbacks that are specified through <code>content_types_accepted/2</code> +and <code>content_types_provided/2</code>. They can take any name, however +it is recommended to use a separate prefix for the callbacks of +each function. For example, <code>from_html</code> and <code>to_html</code> indicate +in the first case that we’re accepting a resource given as HTML, +and in the second case that we send one as HTML.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_meta_data">Meta data</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy will set informative values to the Req object at various +points of the execution. You can retrieve them by matching the +Req object directly. The values are defined in the following table:</p></div> +<div class="tableblock"> +<table rules="all" +width="100%" +frame="border" +cellspacing="0" cellpadding="4"> +<col width="50%" /> +<col width="50%" /> +<thead> +<tr> +<th align="left" valign="top"> Key </th> +<th align="left" valign="top"> Details</th> +</tr> +</thead> +<tbody> +<tr> +<td align="left" valign="top"><p class="table">media_type</p></td> +<td align="left" valign="top"><p class="table">The content-type negotiated for the response entity.</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">language</p></td> +<td align="left" valign="top"><p class="table">The language negotiated for the response entity.</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">charset</p></td> +<td align="left" valign="top"><p class="table">The charset negotiated for the response entity.</p></td> +</tr> +</tbody> +</table> +</div> +<div class="paragraph"><p>They can be used to send a proper body with the response to a +request that used a method other than HEAD or GET.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_response_headers">Response headers</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy will set response headers automatically over the execution +of the REST code. They are listed in the following table.</p></div> +<div class="tableblock"> +<table rules="all" +width="100%" +frame="border" +cellspacing="0" cellpadding="4"> +<col width="50%" /> +<col width="50%" /> +<thead> +<tr> +<th align="left" valign="top"> Header name </th> +<th align="left" valign="top"> Details</th> +</tr> +</thead> +<tbody> +<tr> +<td align="left" valign="top"><p class="table">content-language</p></td> +<td align="left" valign="top"><p class="table">Language used in the response body</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">content-type</p></td> +<td align="left" valign="top"><p class="table">Media type and charset of the response body</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">etag</p></td> +<td align="left" valign="top"><p class="table">Etag of the resource</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">expires</p></td> +<td align="left" valign="top"><p class="table">Expiration date of the resource</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">last-modified</p></td> +<td align="left" valign="top"><p class="table">Last modification date for the resource</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">location</p></td> +<td align="left" valign="top"><p class="table">Relative or absolute URI to the requested resource</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">vary</p></td> +<td align="left" valign="top"><p class="table">List of headers that may change the representation of the resource</p></td> +</tr> +</tbody> +</table> +</div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/rest_principles/index.html b/docs/en/cowboy/2.0/guide/rest_principles/index.html index 94ec56f5..c221d123 100644 --- a/docs/en/cowboy/2.0/guide/rest_principles/index.html +++ b/docs/en/cowboy/2.0/guide/rest_principles/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: REST principles</title> @@ -67,159 +67,162 @@ <h1 class="lined-header"><span>REST principles</span></h1> -<div class="paragraph"><p>This chapter will attempt to define the concepts behind REST
-and explain what makes a service RESTful.</p></div>
-<div class="paragraph"><p>REST is often confused with performing a distinct operation
-depending on the HTTP method, while using more than the GET
-and POST methods. That’s highly misguided at best.</p></div>
-<div class="paragraph"><p>We will first attempt to define REST and will look at what
-it means in the context of HTTP and the Web.
-For a more in-depth explanation of REST, you can read
-<a href="http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm">Roy T. Fielding’s dissertation</a>
-as it does a great job explaining where it comes from and
-what it achieves.</p></div>
-<div class="sect1">
-<h2 id="_rest_architecture">REST architecture</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>REST is a <strong>client-server</strong> architecture. The client and the server
-both have a different set of concerns. The server stores and/or
-manipulates information and makes it available to the user in
-an efficient manner. The client takes that information and
-displays it to the user and/or uses it to perform subsequent
-requests for information. This separation of concerns allows both
-the client and the server to evolve independently as it only
-requires that the interface stays the same.</p></div>
-<div class="paragraph"><p>REST is <strong>stateless</strong>. That means the communication between the
-client and the server always contains all the information needed
-to perform the request. There is no session state in the server,
-it is kept entirely on the client’s side. If access to a resource
-requires authentication, then the client needs to authenticate
-itself with every request.</p></div>
-<div class="paragraph"><p>REST is <strong>cacheable</strong>. The client, the server and any intermediary
-components can all cache resources in order to improve performance.</p></div>
-<div class="paragraph"><p>REST provides a <strong>uniform interface</strong> between components. This
-simplifies the architecture, as all components follow the same
-rules to speak to one another. It also makes it easier to understand
-the interactions between the different components of the system.
-A number of constraints are required to achieve this. They are
-covered in the rest of the chapter.</p></div>
-<div class="paragraph"><p>REST is a <strong>layered system</strong>. Individual components cannot see
-beyond the immediate layer with which they are interacting. This
-means that a client connecting to an intermediate component, like
-a proxy, has no knowledge of what lies beyond. This allows
-components to be independent and thus easily replaceable or
-extendable.</p></div>
-<div class="paragraph"><p>REST optionally provides <strong>code on demand</strong>. Code may be downloaded
-to extend client functionality. This is optional however because
-the client may not be able to download or run this code, and so
-a REST component cannot rely on it being executed.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_resources_and_resource_identifiers">Resources and resource identifiers</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A resource is an abstract concept. In a REST system, any information
-that can be named may be a resource. This includes documents, images,
-a collection of resources and any other information. Any information
-that can be the target of an hypertext link can be a resource.</p></div>
-<div class="paragraph"><p>A resource is a conceptual mapping to a set of entities. The set of
-entities evolves over time; a resource doesn’t. For example, a resource
-can map to "users who have logged in this past month" and another
-to "all users". At some point in time they may map to the same set of
-entities, because all users logged in this past month. But they are
-still different resources. Similarly, if nobody logged in recently,
-then the first resource may map to the empty set. This resource exists
-regardless of the information it maps to.</p></div>
-<div class="paragraph"><p>Resources are identified by uniform resource identifiers, also known
-as URIs. Sometimes internationalized resource identifiers, or IRIs,
-may also be used, but these can be directly translated into a URI.</p></div>
-<div class="paragraph"><p>In practice we will identify two kinds of resources. Individual
-resources map to a set of one element, for example "user Joe".
-Collection of resources map to a set of 0 to N elements,
-for example "all users".</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_resource_representations">Resource representations</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The representation of a resource is a sequence of bytes associated
-with metadata.</p></div>
-<div class="paragraph"><p>The metadata comes as a list of key-value pairs, where the name
-corresponds to a standard that defines the value’s structure and
-semantics. With HTTP, the metadata comes in the form of request
-or response headers. The headers' structure and semantics are well
-defined in the HTTP standard. Metadata includes representation
-metadata, resource metadata and control data.</p></div>
-<div class="paragraph"><p>The representation metadata gives information about the
-representation, such as its media type, the date of last
-modification, or even a checksum.</p></div>
-<div class="paragraph"><p>Resource metadata could be link to related resources or
-information about additional representations of the resource.</p></div>
-<div class="paragraph"><p>Control data allows parameterizing the request or response.
-For example, we may only want the representation returned if
-it is more recent than the one we have in cache. Similarly,
-we may want to instruct the client about how it should cache
-the representation. This isn’t restricted to caching. We may,
-for example, want to store a new representation of a resource
-only if it wasn’t modified since we first retrieved it.</p></div>
-<div class="paragraph"><p>The data format of a representation is also known as the media
-type. Some media types are intended for direct rendering to the
-user, while others are intended for automated processing. The
-media type is a key component of the REST architecture.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_self_descriptive_messages">Self-descriptive messages</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Messages must be self-descriptive. That means that the data
-format of a representation must always come with its media
-type (and similarly requesting a resource involves choosing
-the media type of the representation returned). If you are
-sending HTML, then you must say it is HTML by sending the
-media type with the representation. In HTTP this is done
-using the content-type header.</p></div>
-<div class="paragraph"><p>The media type is often an IANA registered media type, like
-<code>text/html</code> or <code>image/png</code>, but does not need to be. Exactly
-two things are important for respecting this constraint: that
-the media type is well specified, and that the sender and
-recipient agree about what the media type refers to.</p></div>
-<div class="paragraph"><p>This means that you can create your own media types, like
-<code>application/x-mine</code>, and that as long as you write the
-specifications for it and that both endpoints agree about
-it then the constraint is respected.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_hypermedia_as_the_engine_of_application_state">Hypermedia as the engine of application state</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The last constraint is generally where services that claim
-to be RESTful fail. Interactions with a server must be
-entirely driven by hypermedia. The client does not need
-any prior knowledge of the service in order to use it,
-other than an entry point and of course basic understanding
-of the media type of the representations, at the very least
-enough to find and identify hyperlinks and link relations.</p></div>
-<div class="paragraph"><p>To give a simple example, if your service only works with
-the <code>application/json</code> media type then this constraint
-cannot be respected (as there are no concept of links in
-JSON) and thus your service isn’t RESTful. This is the case
-for the majority of self-proclaimed REST services.</p></div>
-<div class="paragraph"><p>On the other hand if you create a JSON based media type
-that has a concept of links and link relations, then
-your service might be RESTful.</p></div>
-<div class="paragraph"><p>Respecting this constraint means that the entirety of the
-service becomes self-discoverable, not only the resources
-in it, but also the operations you can perform on it. This
-makes clients very thin as there is no need to implement
-anything specific to the service to operate on it.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter will attempt to define the concepts behind REST +and explain what makes a service RESTful.</p></div> +<div class="paragraph"><p>REST is often confused with performing a distinct operation +depending on the HTTP method, while using more than the GET +and POST methods. That’s highly misguided at best.</p></div> +<div class="paragraph"><p>We will first attempt to define REST and will look at what +it means in the context of HTTP and the Web. +For a more in-depth explanation of REST, you can read +<a href="http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm">Roy T. Fielding’s dissertation</a> +as it does a great job explaining where it comes from and +what it achieves.</p></div> +<div class="sect1"> +<h2 id="_rest_architecture">REST architecture</h2> +<div class="sectionbody"> +<div class="paragraph"><p>REST is a <strong>client-server</strong> architecture. The client and the server +both have a different set of concerns. The server stores and/or +manipulates information and makes it available to the user in +an efficient manner. The client takes that information and +displays it to the user and/or uses it to perform subsequent +requests for information. This separation of concerns allows both +the client and the server to evolve independently as it only +requires that the interface stays the same.</p></div> +<div class="paragraph"><p>REST is <strong>stateless</strong>. That means the communication between the +client and the server always contains all the information needed +to perform the request. There is no session state in the server, +it is kept entirely on the client’s side. If access to a resource +requires authentication, then the client needs to authenticate +itself with every request.</p></div> +<div class="paragraph"><p>REST is <strong>cacheable</strong>. The client, the server and any intermediary +components can all cache resources in order to improve performance.</p></div> +<div class="paragraph"><p>REST provides a <strong>uniform interface</strong> between components. This +simplifies the architecture, as all components follow the same +rules to speak to one another. It also makes it easier to understand +the interactions between the different components of the system. +A number of constraints are required to achieve this. They are +covered in the rest of the chapter.</p></div> +<div class="paragraph"><p>REST is a <strong>layered system</strong>. Individual components cannot see +beyond the immediate layer with which they are interacting. This +means that a client connecting to an intermediate component, like +a proxy, has no knowledge of what lies beyond. This allows +components to be independent and thus easily replaceable or +extendable.</p></div> +<div class="paragraph"><p>REST optionally provides <strong>code on demand</strong>. Code may be downloaded +to extend client functionality. This is optional however because +the client may not be able to download or run this code, and so +a REST component cannot rely on it being executed.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_resources_and_resource_identifiers">Resources and resource identifiers</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A resource is an abstract concept. In a REST system, any information +that can be named may be a resource. This includes documents, images, +a collection of resources and any other information. Any information +that can be the target of an hypertext link can be a resource.</p></div> +<div class="paragraph"><p>A resource is a conceptual mapping to a set of entities. The set of +entities evolves over time; a resource doesn’t. For example, a resource +can map to "users who have logged in this past month" and another +to "all users". At some point in time they may map to the same set of +entities, because all users logged in this past month. But they are +still different resources. Similarly, if nobody logged in recently, +then the first resource may map to the empty set. This resource exists +regardless of the information it maps to.</p></div> +<div class="paragraph"><p>Resources are identified by uniform resource identifiers, also known +as URIs. Sometimes internationalized resource identifiers, or IRIs, +may also be used, but these can be directly translated into a URI.</p></div> +<div class="paragraph"><p>In practice we will identify two kinds of resources. Individual +resources map to a set of one element, for example "user Joe". +Collection of resources map to a set of 0 to N elements, +for example "all users".</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_resource_representations">Resource representations</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The representation of a resource is a sequence of bytes associated +with metadata.</p></div> +<div class="paragraph"><p>The metadata comes as a list of key-value pairs, where the name +corresponds to a standard that defines the value’s structure and +semantics. With HTTP, the metadata comes in the form of request +or response headers. The headers' structure and semantics are well +defined in the HTTP standard. Metadata includes representation +metadata, resource metadata and control data.</p></div> +<div class="paragraph"><p>The representation metadata gives information about the +representation, such as its media type, the date of last +modification, or even a checksum.</p></div> +<div class="paragraph"><p>Resource metadata could be link to related resources or +information about additional representations of the resource.</p></div> +<div class="paragraph"><p>Control data allows parameterizing the request or response. +For example, we may only want the representation returned if +it is more recent than the one we have in cache. Similarly, +we may want to instruct the client about how it should cache +the representation. This isn’t restricted to caching. We may, +for example, want to store a new representation of a resource +only if it wasn’t modified since we first retrieved it.</p></div> +<div class="paragraph"><p>The data format of a representation is also known as the media +type. Some media types are intended for direct rendering to the +user, while others are intended for automated processing. The +media type is a key component of the REST architecture.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_self_descriptive_messages">Self-descriptive messages</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Messages must be self-descriptive. That means that the data +format of a representation must always come with its media +type (and similarly requesting a resource involves choosing +the media type of the representation returned). If you are +sending HTML, then you must say it is HTML by sending the +media type with the representation. In HTTP this is done +using the content-type header.</p></div> +<div class="paragraph"><p>The media type is often an IANA registered media type, like +<code>text/html</code> or <code>image/png</code>, but does not need to be. Exactly +two things are important for respecting this constraint: that +the media type is well specified, and that the sender and +recipient agree about what the media type refers to.</p></div> +<div class="paragraph"><p>This means that you can create your own media types, like +<code>application/x-mine</code>, and that as long as you write the +specifications for it and that both endpoints agree about +it then the constraint is respected.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_hypermedia_as_the_engine_of_application_state">Hypermedia as the engine of application state</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The last constraint is generally where services that claim +to be RESTful fail. Interactions with a server must be +entirely driven by hypermedia. The client does not need +any prior knowledge of the service in order to use it, +other than an entry point and of course basic understanding +of the media type of the representations, at the very least +enough to find and identify hyperlinks and link relations.</p></div> +<div class="paragraph"><p>To give a simple example, if your service only works with +the <code>application/json</code> media type then this constraint +cannot be respected (as there are no concept of links in +JSON) and thus your service isn’t RESTful. This is the case +for the majority of self-proclaimed REST services.</p></div> +<div class="paragraph"><p>On the other hand if you create a JSON based media type +that has a concept of links and link relations, then +your service might be RESTful.</p></div> +<div class="paragraph"><p>Respecting this constraint means that the entirety of the +service becomes self-discoverable, not only the resources +in it, but also the operations you can perform on it. This +makes clients very thin as there is no need to implement +anything specific to the service to operate on it.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/rest_put_post_patch.png b/docs/en/cowboy/2.0/guide/rest_put_post_patch.png Binary files differindex 4afca9e9..176650e9 100644 --- a/docs/en/cowboy/2.0/guide/rest_put_post_patch.png +++ b/docs/en/cowboy/2.0/guide/rest_put_post_patch.png diff --git a/docs/en/cowboy/2.0/guide/rest_put_post_patch.svg b/docs/en/cowboy/2.0/guide/rest_put_post_patch.svg index 263cc942..06d55052 100644 --- a/docs/en/cowboy/2.0/guide/rest_put_post_patch.svg +++ b/docs/en/cowboy/2.0/guide/rest_put_post_patch.svg @@ -15,7 +15,7 @@ height="1052.3622" id="svg2" version="1.1" - inkscape:version="0.48.4 r9939" + inkscape:version="0.92.1 r" sodipodi:docname="rest_put_post_patch.svg" inkscape:export-filename="/home/essen/Dropbox/Public/drawing.png" inkscape:export-xdpi="90" @@ -64,16 +64,16 @@ borderopacity="1.0" inkscape:pageopacity="1" inkscape:pageshadow="2" - inkscape:zoom="2" - inkscape:cx="299.56028" - inkscape:cy="-395.99137" + inkscape:zoom="0.70710678" + inkscape:cx="201.51415" + inkscape:cy="-214.71801" inkscape:document-units="px" inkscape:current-layer="layer1" showgrid="false" - inkscape:window-width="2560" - inkscape:window-height="1402" + inkscape:window-width="1920" + inkscape:window-height="1043" inkscape:window-x="0" - inkscape:window-y="38" + inkscape:window-y="0" inkscape:window-maximized="1" inkscape:snap-global="true" showguides="true"> @@ -255,65 +255,65 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="-58.692513" y="114.39204" - id="text5371" - sodipodi:linespacing="125%"><tspan + id="text5371"><tspan sodipodi:role="line" id="tspan5373" x="-58.692513" - y="114.39204">some text</tspan></text> + y="114.39204" + style="font-size:16px;line-height:1.25;font-family:sans-serif">some text</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="-58.692513" y="53.112247" - id="text5371-2" - sodipodi:linespacing="125%"><tspan + id="text5371-2"><tspan sodipodi:role="line" id="tspan5373-6" x="-58.692513" - y="53.112247">some text</tspan></text> + y="53.112247" + style="font-size:16px;line-height:1.25;font-family:sans-serif">some text</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="-58.692513" y="236.95154" - id="text5371-4" - sodipodi:linespacing="125%"><tspan + id="text5371-4"><tspan sodipodi:role="line" id="tspan5373-9" x="-58.692513" - y="236.95154">some text</tspan></text> + y="236.95154" + style="font-size:16px;line-height:1.25;font-family:sans-serif">some text</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="313.14185" y="50.482433" id="text5371-4-0" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" x="313.14185" y="50.482433" - id="tspan17171">conneg</tspan></text> + id="tspan17171" + style="font-size:16px;line-height:1.25;font-family:sans-serif">conneg</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="312.52466" y="134.49161" id="text5371-2-95" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-80" x="312.52466" - y="134.49161">resource_exists</tspan></text> + y="134.49161" + style="font-size:16px;line-height:1.25;font-family:sans-serif">resource_exists</tspan></text> <rect style="fill:#d1f2a5;fill-opacity:1;fill-rule:nonzero;stroke:#a9ca7d;stroke-width:3;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-1-2" @@ -324,18 +324,18 @@ rx="15" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="205.83722" y="175.92931" id="text5371-2-391" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-63" x="205.83722" - y="175.92931">true</tspan></text> + y="175.92931" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <g transform="matrix(0,-1,1,0,-586.85324,629.53436)" id="g5650-2"> @@ -364,18 +364,18 @@ </g> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="401.26678" y="176.39024" id="text5371-4-6" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-0" x="401.26678" - y="176.39024">false</tspan></text> + y="176.39024" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <g transform="translate(517.41793,-144.94975)" id="g5650-2-2"> @@ -415,19 +415,19 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="-544.69421" y="-354.17184" id="text5371-2-3-0-7" - sodipodi:linespacing="125%" - transform="matrix(0,-1,1,0,0,0)" + transform="rotate(-90)" inkscape:export-filename="/home/essen/extend/cowboy/guide/http_req_resp.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-7-3-9" x="-544.69421" - y="-354.17184">middlewares</tspan></text> + y="-354.17184" + style="font-size:16px;line-height:1.25;font-family:sans-serif">middlewares</tspan></text> <g transform="matrix(0,-1,1,0,-508.93096,565.23553)" id="g5650-2-0-4" @@ -461,18 +461,18 @@ </g> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="496.12921" y="255.81152" id="text5371-4-4-9" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6" x="496.12921" - y="255.81152">true</tspan></text> + y="255.81152" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <g transform="matrix(0.70710678,0.70710678,-0.70710678,0.70710678,501.47379,-62.310424)" id="g5650-9-9" @@ -577,18 +577,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="171.92052" y="216.5154" id="text5371-4-0-8" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" x="171.92052" y="216.5154" - id="tspan17171-6">cond</tspan></text> + id="tspan17171-6" + style="font-size:16px;line-height:1.25;font-family:sans-serif">cond</tspan></text> <g transform="matrix(0,-1,-1,0,983.2611,313.28465)" id="g5650-2-0-4-3-8" @@ -633,32 +633,32 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="459.47131" y="216.51535" id="text5371-2-32-6" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-27-8" x="459.47131" - y="216.51535">has if-match?</tspan></text> + y="216.51535" + style="font-size:16px;line-height:1.25;font-family:sans-serif">has if-match?</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="609.12769" y="296.02957" id="text5371-2-391-5" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-63-7" x="609.12769" - y="296.02957">false</tspan></text> + y="296.02957" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <g transform="translate(517.41793,13.785058)" id="g5650-0-6" @@ -701,32 +701,32 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="459.47131" y="374.91498" id="text5371-2-32-8" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-27-1" x="459.47131" - y="374.91498">method is POST/PATCH?</tspan></text> + y="374.91498" + style="font-size:16px;line-height:1.25;font-family:sans-serif">method is POST/PATCH?</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="479.69171" y="414.84009" id="text5371-2-8-9" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-3-4" x="479.69171" - y="414.84009">true</tspan></text> + y="414.84009" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <g transform="translate(517.41793,490.80719)" id="g5650-0-6-0" @@ -862,18 +862,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="459.47131" y="852.62952" id="text5371-2-74-0" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2" x="459.47131" - y="852.62952">method is POST?</tspan></text> + y="852.62952" + style="font-size:16px;line-height:1.25;font-family:sans-serif">method is POST?</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1" @@ -887,18 +887,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="459.97131" y="294.47879" id="text5371-43" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3" x="459.97131" - y="294.47879">412 precondition failed</tspan></text> + y="294.47879" + style="font-size:16px;line-height:1.25;font-family:sans-serif">412 precondition failed</tspan></text> <g transform="translate(2.6196148,3.2328831)" id="g5650-2-2-6"> @@ -993,18 +993,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="459.63538" y="453.2847" id="text5371-2-32-8-5" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-27-1-2" x="459.63538" - y="453.2847">previously_existed</tspan></text> + y="453.2847" + style="font-size:16px;line-height:1.25;font-family:sans-serif">previously_existed</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-5-5" @@ -1044,32 +1044,32 @@ </g> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="171.97131" y="614.22986" id="text5371-43-2-8" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-9-74" x="171.97131" - y="614.22986">404 not found</tspan></text> + y="614.22986" + style="font-size:16px;line-height:1.25;font-family:sans-serif">404 not found</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="296.84631" y="433.29703" id="text5371-2-8-9-9" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-3-4-8" x="296.84631" - y="433.29703">false</tspan></text> + y="433.29703" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <g transform="translate(516.00372,173.10383)" id="g5650-2-2-17-8"> @@ -1129,32 +1129,32 @@ </g> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="500.12921" y="574.2605" id="text5371-4-4-9-3-4" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-2-8" x="500.12921" - y="574.2605">true*</tspan></text> + y="574.2605" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true*</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="607.7135" y="610.86951" id="text5371-2-391-5-5-1-3" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-63-7-9-9-5" x="607.7135" - y="610.86951">false</tspan></text> + y="610.86951" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-5-9-29" @@ -1168,18 +1168,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="459.26428" y="612.67908" id="text5371-43-2-9-4" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-9-7-5" x="459.26428" - y="612.67908">301 moved permanently</tspan></text> + y="612.67908" + style="font-size:16px;line-height:1.25;font-family:sans-serif">301 moved permanently</tspan></text> <g transform="translate(517.41793,332.05687)" id="g5650-2-2-65-2"> @@ -1250,46 +1250,46 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="459.14709" y="691.82751" id="text5371-2-74-0-7-4" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2-8-9" x="459.14709" - y="691.82751">moved_temporarily</tspan></text> + y="691.82751" + style="font-size:16px;line-height:1.25;font-family:sans-serif">moved_temporarily</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="500.12921" y="733.21747" id="text5371-4-4-9-3-2-0" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-2-6-6" x="500.12921" - y="733.21747">true*</tspan></text> + y="733.21747" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true*</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="607.7135" y="769.89801" id="text5371-2-391-5-5-1-0-7" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-63-7-9-9-2-8" x="607.7135" - y="769.89801">false</tspan></text> + y="769.89801" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-5-9-2-1" @@ -1303,18 +1303,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="459.26428" y="771.56445" id="text5371-43-2-9-7-1" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-9-7-8-9" x="459.26428" - y="771.56445">307 moved temporarily</tspan></text> + y="771.56445" + style="font-size:16px;line-height:1.25;font-family:sans-serif">307 moved temporarily</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-5-9-2-4-1" @@ -1328,18 +1328,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="604.32263" y="1242.303" id="text5371-43-2-9-7-3-8" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-9-7-8-7-5" x="604.32263" - y="1242.303">400 bad request</tspan></text> + y="1242.303" + style="font-size:16px;line-height:1.25;font-family:sans-serif">400 bad request</tspan></text> <g transform="matrix(-0.34202014,-0.93969262,0.93969262,-0.34202014,-311.11659,1246.6148)" id="g5650-2-0-4-0" @@ -1372,18 +1372,18 @@ </g> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="120.08566" y="891.92566" id="text5371-2-8-9-4" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-3-4-5" x="120.08566" - y="891.92566">true</tspan></text> + y="891.92566" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <g transform="matrix(0,-1,-1,0,699.22962,550.33236)" id="g5650-2-0-4-5" @@ -1428,18 +1428,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="167.39459" y="532.79895" id="text5371-2-74-0-7-1" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2-8-94" x="167.39459" - y="532.79895">allow_missing_post</tspan></text> + y="532.79895" + style="font-size:16px;line-height:1.25;font-family:sans-serif">allow_missing_post</tspan></text> <rect style="fill:#d1f2a5;fill-opacity:1;fill-rule:nonzero;stroke:#a9ca7d;stroke-width:3;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-1-8-9-5" @@ -1453,32 +1453,32 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="175.2144" y="455.37643" id="text5371-2-74-0-4" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2-6" x="175.2144" - y="455.37643">method is POST?</tspan></text> + y="455.37643" + style="font-size:16px;line-height:1.25;font-family:sans-serif">method is POST?</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="459.35022" y="930.3703" id="text5371-2-74-0-7-1-5" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2-8-94-5" x="459.35022" - y="930.3703">allow_missing_post</tspan></text> + y="930.3703" + style="font-size:16px;line-height:1.25;font-family:sans-serif">allow_missing_post</tspan></text> <g transform="translate(229.41793,490.95885)" id="g5650-0-6-9" @@ -1521,18 +1521,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="166.63885" y="852.62952" id="text5371-2-74-0-1" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2-7" x="166.63885" - y="852.62952">method is PUT?</tspan></text> + y="852.62952" + style="font-size:16px;line-height:1.25;font-family:sans-serif">method is PUT?</tspan></text> <g transform="translate(229.41793,571.07045)" id="g5650-2-2-65-9"> @@ -1602,32 +1602,32 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="166.24431" y="930.3703" id="text5371-2-74-0-7-15" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2-8-2" x="166.24431" - y="930.3703">is_conflict</tspan></text> + y="930.3703" + style="font-size:16px;line-height:1.25;font-family:sans-serif">is_conflict</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="136.52316" y="971.55994" id="text5371-4-4-9-3-2-08" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-2-6-0" x="136.52316" - y="971.55994">true</tspan></text> + y="971.55994" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-5-9-2-7" @@ -1641,18 +1641,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="171.44006" y="1011.8981" id="text5371-43-2-9-7-0" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-9-7-8-0" x="171.44006" - y="1011.8981">409 conflict</tspan></text> + y="1011.8981" + style="font-size:16px;line-height:1.25;font-family:sans-serif">409 conflict</tspan></text> <g transform="translate(370.63925,803.79161)" id="g5650-93-7" @@ -1695,18 +1695,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="313.14185" y="1164.0962" id="text5371-2-74-0-7-41" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2-8-3" x="313.14185" - y="1164.0962">content_types_accepted</tspan></text> + y="1164.0962" + style="font-size:16px;line-height:1.25;font-family:sans-serif">content_types_accepted</tspan></text> <rect style="fill:#d1f2a5;fill-opacity:1;fill-rule:nonzero;stroke:#a9ca7d;stroke-width:3;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-1-4-9" @@ -1720,18 +1720,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="313.21997" y="1242.2975" id="text5371-2-3-0-3" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-7-3-1" x="313.21997" - y="1242.2975">AcceptResource</tspan></text> + y="1242.2975" + style="font-size:16px;line-height:1.25;font-family:sans-serif">AcceptCallback</tspan></text> <g transform="translate(233.45629,961.91953)" id="g5650-6-4-8-7" @@ -1804,18 +1804,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="175.50966" y="1323.8022" id="text5371-2-74-0-1-3" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2-7-4" x="175.50966" - y="1323.8022">new resource?</tspan></text> + y="1323.8022" + style="font-size:16px;line-height:1.25;font-family:sans-serif">new resource?</tspan></text> <g transform="translate(517.41793,962.60627)" id="g5650-6-4-8" @@ -1889,18 +1889,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="459.47131" y="1323.8022" id="text5371-2-74-0-1-3-4" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2-7-4-8" x="459.47131" - y="1323.8022">new resource?</tspan></text> + y="1323.8022" + style="font-size:16px;line-height:1.25;font-family:sans-serif">new resource?</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-8-7" @@ -1914,18 +1914,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="459.776" y="1403.5779" id="text5371-43-3-2" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-1-9" x="459.776" - y="1403.5779">201 created</tspan></text> + y="1403.5779" + style="font-size:16px;line-height:1.25;font-family:sans-serif">201 created</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-8-7-4" @@ -1939,18 +1939,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="459.03381" y="1483.2128" id="text5371-43-3-2-6" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-1-9-2" x="459.03381" - y="1483.2128">303 see other</tspan></text> + y="1483.2128" + style="font-size:16px;line-height:1.25;font-family:sans-serif">303 see other</tspan></text> <g transform="matrix(0,1,1,0,-67.245042,1455.155)" id="g5650-2-2-6-6-7-9-1"> @@ -2019,18 +2019,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="175.50966" y="1401.7865" id="text5371-2-74-0-1-3-7" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2-7-4-9" x="175.50966" - y="1401.7865">has resp location?</tspan></text> + y="1401.7865" + style="font-size:16px;line-height:1.25;font-family:sans-serif">has resp location?</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-8-7-4-7" @@ -2110,18 +2110,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="175.50966" y="1561.2965" id="text5371-2-74-0-1-3-7-9" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2-7-4-9-5" x="175.50966" - y="1561.2965">has resp body?</tspan></text> + y="1561.2965" + style="font-size:16px;line-height:1.25;font-family:sans-serif">has resp body?</tspan></text> <g transform="translate(517.41793,1201.395)" id="g5650-6-4" @@ -2195,32 +2195,32 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="459.30334" y="1561.0739" id="text5371-2-9-6" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-8-6" x="459.30334" - y="1561.0739">multiple_choices</tspan></text> + y="1561.0739" + style="font-size:16px;line-height:1.25;font-family:sans-serif">multiple_choices</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="479.75421" y="1602.6646" id="text5371-2-8-4" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-3-7" x="479.75421" - y="1602.6646">false</tspan></text> + y="1602.6646" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-1-0" @@ -2234,18 +2234,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="459.42053" y="1720.566" id="text5371-43-5-7" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-62-9" x="459.42053" - y="1720.566">300 multiple choices</tspan></text> + y="1720.566" + style="font-size:16px;line-height:1.25;font-family:sans-serif">300 multiple choices</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-8-3" @@ -2259,46 +2259,46 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="458.88538" y="1642.3412" id="text5371-43-3-1" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-1-3" x="458.88538" - y="1642.3412">200 OK</tspan></text> + y="1642.3412" + style="font-size:16px;line-height:1.25;font-family:sans-serif">200 OK</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="171.24475" y="1642.3412" id="text5371-43-3-2-6-9" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-1-9-2-0" x="171.24475" - y="1642.3412">204 no content</tspan></text> + y="1642.3412" + style="font-size:16px;line-height:1.25;font-family:sans-serif">204 no content</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="479.69171" y="891.92566" id="text5371-2-8-9-1" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-3-4-1" x="479.69171" - y="891.92566">true</tspan></text> + y="891.92566" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <g id="g5650-4-8" transform="matrix(0.5,0.8660254,-0.8660254,0.5,204.7918,279.30499)"> @@ -2327,18 +2327,18 @@ </g> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="496.12921" y="494.3544" id="text5371-4-4-9-1" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-8" x="496.12921" - y="494.3544">true</tspan></text> + y="494.3544" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <rect style="fill:#d1f2a5;fill-opacity:1;fill-rule:nonzero;stroke:#a9ca7d;stroke-width:3;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-1-8-9-1-3-4-8" @@ -2352,18 +2352,18 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#6d8e41;fill-opacity:1;stroke:none" x="459.14709" y="532.79895" id="text5371-2-74-0-9" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-18-2-9" x="459.14709" - y="532.79895">moved_permanently</tspan></text> + y="532.79895" + style="font-size:16px;line-height:1.25;font-family:sans-serif">moved_permanently</tspan></text> <rect style="fill:#effab4;fill-opacity:1;fill-rule:nonzero;stroke:#c7d28c;stroke-width:2.73499846;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" id="rect5273-7-3-1-8-7-9" @@ -2377,102 +2377,102 @@ inkscape:export-ydpi="89.926643" /> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#77823c;fill-opacity:1;stroke:none" x="459.67053" y="1010.2067" id="text5371-43-3-2-1" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-3-1-9-5" x="459.67053" - y="1010.2067">410 gone</tspan></text> + y="1010.2067" + style="font-size:16px;line-height:1.25;font-family:sans-serif">410 gone</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="260.04547" y="494.97446" id="text5371-4-4-9-1-4" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-8-2" x="260.04547" - y="494.97446">false</tspan></text> + y="494.97446" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="120.08566" y="494.51349" id="text5371-2-8-9-0" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-3-4-55" x="120.08566" - y="494.51349">true</tspan></text> + y="494.51349" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="133.92941" y="574.40112" id="text5371-4-4-9-1-1" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-8-0" x="133.92941" - y="574.40112">false</tspan></text> + y="574.40112" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="315.87756" y="828.86047" id="text5371-4-4-9-1-1-9" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-8-0-1" x="315.87756" - y="828.86047">false</tspan></text> + y="828.86047" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="498.78546" y="972.02087" id="text5371-4-4-9-1-1-1" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-8-0-2" x="498.78546" - y="972.02087">false</tspan></text> + y="972.02087" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="458.9295" y="1217.7582" id="text5371-4-4-9-1-1-9-1" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-8-0-1-2" x="458.9295" - y="1217.7582">false</tspan></text> + y="1217.7582" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <g transform="matrix(0,1,1,0,77.85132,1295.6715)" id="g5650-2-2-6-6-7"> @@ -2501,18 +2501,18 @@ </g> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="207.75119" y="1283.5576" id="text5371-2-391-8" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-63-4" x="207.75119" - y="1283.5576">true</tspan></text> + y="1283.5576" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <g transform="matrix(0.70710678,0.70710678,-0.70710678,0.70710678,501.47379,1045.323)" id="g5650-9-9-1" @@ -2544,18 +2544,18 @@ </g> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:end;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:end;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:end;letter-spacing:0px;word-spacing:0px;text-anchor:end;fill:#6d8e41;fill-opacity:1;stroke:none" x="419.81369" y="1283.0615" id="text5371-2-391-9" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" x="419.81369" y="1283.0615" - id="tspan5794">true, URI*</tspan></text> + id="tspan5794" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true, URI*</tspan></text> <g transform="matrix(-0.70710678,0.70710678,0.70710678,0.70710678,124.04665,1045.323)" id="g5650-9-9-4" @@ -2587,158 +2587,158 @@ </g> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="479.69171" y="1363.2994" id="text5371-2-8-4-3" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-3-7-5" x="479.69171" - y="1363.2994">true</tspan></text> + y="1363.2994" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="626.74475" y="1403.5779" id="text5371-4-4-9-1-1-9-1-4" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-8-0-1-2-0" x="626.74475" - y="1403.5779">false</tspan></text> + y="1403.5779" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="624.0885" y="1642.0209" id="text5371-4-4-9-1-1-9-1-0" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-8-0-1-2-3" x="624.0885" - y="1642.0209">true</tspan></text> + y="1642.0209" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="317.91525" y="1538.8624" id="text5371-4-4-9-1-1-9-1-2" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-8-0-1-2-1" x="317.91525" - y="1538.8624">true</tspan></text> + y="1538.8624" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="190.83659" y="1602.2036" id="text5371-2-8-4-3-9" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-3-7-5-9" x="190.83659" - y="1602.2036">false</tspan></text> + y="1602.2036" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="190.83659" y="1363.1792" id="text5371-2-8-4-3-8" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-3-7-5-0" x="190.83659" - y="1363.1792">true</tspan></text> + y="1363.1792" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="7.9966321" y="1443.395" id="text5371-4-4-9-1-1-9-1-4-7" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-8-0-1-2-0-6" x="7.9966321" - y="1443.395">false</tspan></text> + y="1443.395" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="317.86548" y="1379.0562" id="text5371-4-4-9-1-1-9-1-2-2" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-8-0-1-2-1-5" x="317.86548" - y="1379.0562">true</tspan></text> + y="1379.0562" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="190.83659" y="1482.6313" id="text5371-2-8-4-3-8-7" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-3-7-5-0-8" x="190.83659" - y="1482.6313">false</tspan></text> + y="1482.6313" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="85.095001" y="891.92566" id="text5371-4-4-9-1-4-2" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-2-6-8-2-9" x="85.095001" - y="891.92566">false</tspan></text> + y="891.92566" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="232.21094" y="971.55994" id="text5371-2-391-5-5-1-0-7-1" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-63-7-9-9-2-8-8" x="232.21094" - y="971.55994">false</tspan></text> + y="971.55994" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <g transform="matrix(0,-1,1,0,-359.02432,626.75367)" id="g5650-2-0-4-3-8-9-4" @@ -2781,18 +2781,18 @@ </g> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="536.26642" y="972.02087" id="text5371-2-8-9-1-5" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-3-4-1-4" x="536.26642" - y="972.02087">true</tspan></text> + y="972.02087" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> <g transform="matrix(0,-1,-1,0,347.71062,566.6496)" id="g5650-2-0-4-3-8-9-2-8" @@ -2826,31 +2826,31 @@ </g> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#9b3b1c;fill-opacity:1;stroke:none" x="322.92551" y="375.54388" id="text5371-4-6-1" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-9-0-8" x="322.92551" - y="375.54388">false</tspan></text> + y="375.54388" + style="font-size:16px;line-height:1.25;font-family:sans-serif">false</tspan></text> <text xml:space="preserve" - style="font-size:16px;font-style:normal;font-weight:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:sans-serif;-inkscape-font-specification:Sans;text-align:start;letter-spacing:0px;word-spacing:0px;text-anchor:start;fill:#6d8e41;fill-opacity:1;stroke:none" x="66.001251" y="574.40112" id="text5371-2-8-9-0-3" - sodipodi:linespacing="125%" inkscape:export-filename="/home/essen/ninenines/cowboy/guide/rest_options.png" inkscape:export-xdpi="89.926643" inkscape:export-ydpi="89.926643"><tspan sodipodi:role="line" id="tspan5373-6-3-4-55-3" x="66.001251" - y="574.40112">true</tspan></text> + y="574.40112" + style="font-size:16px;line-height:1.25;font-family:sans-serif">true</tspan></text> </g> </svg> diff --git a/docs/en/cowboy/2.0/guide/routing/index.html b/docs/en/cowboy/2.0/guide/routing/index.html index f67532cd..24f5ca46 100644 --- a/docs/en/cowboy/2.0/guide/routing/index.html +++ b/docs/en/cowboy/2.0/guide/routing/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Routing</title> @@ -67,267 +67,270 @@ <h1 class="lined-header"><span>Routing</span></h1> -<div class="paragraph"><p>Cowboy does nothing by default.</p></div>
-<div class="paragraph"><p>To make Cowboy useful, you need to map URIs to Erlang modules that will
-handle the requests. This is called routing.</p></div>
-<div class="paragraph"><p>When Cowboy receives a request, it tries to match the requested host and
-path to the configured routes. When there’s a match, the route’s
-associated handler is executed.</p></div>
-<div class="paragraph"><p>Routes need to be compiled before they can be used by Cowboy.
-The result of the compilation is the dispatch rules.</p></div>
-<div class="sect1">
-<h2 id="_syntax">Syntax</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The general structure for the routes is defined as follow.</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">Routes</span> <span style="color: #990000">=</span> [<span style="color: #009900">Host1</span>, <span style="color: #009900">Host2</span>, <span style="color: #990000">...</span> <span style="color: #009900">HostN</span>]<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Each host contains matching rules for the host along with optional
-constraints, and a list of routes for the path component.</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">Host1</span> <span style="color: #990000">=</span> {<span style="color: #009900">HostMatch</span>, <span style="color: #009900">PathsList</span>}<span style="color: #990000">.</span>
-<span style="color: #009900">Host2</span> <span style="color: #990000">=</span> {<span style="color: #009900">HostMatch</span>, <span style="color: #009900">Constraints</span>, <span style="color: #009900">PathsList</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The list of routes for the path component is defined similar to the
-list of hosts.</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">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 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">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>
-</div>
-<div class="sect1">
-<h2 id="_match_syntax">Match syntax</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The match syntax is used to associate host names and paths with their
-respective handlers.</p></div>
-<div class="paragraph"><p>The match syntax is the same for host and path with a few subtleties.
-Indeed, the segments separator is different, and the host is matched
-starting from the last segment going to the first. All examples will
-feature both host and path match rules and explain the differences
-when encountered.</p></div>
-<div class="paragraph"><p>Excluding special values that we will explain at the end of this section,
-the simplest match value is a host or a path. It can be given as either
-a <code>string()</code> or a <code>binary()</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">PathMatch1</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/"</span><span style="color: #990000">.</span>
-<span style="color: #009900">PathMatch2</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/path/to/resource"</span><span style="color: #990000">.</span>
-
-<span style="color: #009900">HostMatch1</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"cowboy.example.org"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>As you can see, all paths defined this way must start with a slash
-character. Note that these two paths are identical as far as routing
-is concerned.</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">PathMatch2</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/path/to/resource"</span><span style="color: #990000">.</span>
-<span style="color: #009900">PathMatch3</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/path/to/resource/"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Hosts with and without a trailing dot are equivalent for routing.
-Similarly, hosts with and without a leading dot are also equivalent.</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">HostMatch1</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"cowboy.example.org"</span><span style="color: #990000">.</span>
-<span style="color: #009900">HostMatch2</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"cowboy.example.org."</span><span style="color: #990000">.</span>
-<span style="color: #009900">HostMatch3</span> <span style="color: #990000">=</span> <span style="color: #FF0000">".cowboy.example.org"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>It is possible to extract segments of the host and path and to store
-the values in the <code>Req</code> object for later use. We call these kind of
-values bindings.</p></div>
-<div class="paragraph"><p>The syntax for bindings is very simple. A segment that begins with
-the <code>:</code> character means that what follows until the end of the segment
-is the name of the binding in which the segment value will be stored.</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">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/:name/prices"</span><span style="color: #990000">.</span>
-<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">":subdomain.example.org"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>If these two end up matching when routing, you will end up with two
-bindings defined, <code>subdomain</code> and <code>name</code>, each containing the
-segment value where they were defined. For example, the URL
-<code>http://test.example.org/hats/wild_cowboy_legendary/prices</code> will
-result in having the value <code>test</code> bound to the name <code>subdomain</code>
-and the value <code>wild_cowboy_legendary</code> bound to the name <code>name</code>.
-They can later be retrieved using <code>cowboy_req:binding/{2,3}</code>. The
-binding name must be given as an atom.</p></div>
-<div class="paragraph"><p>There is a special binding name you can use to mimic the underscore
-variable in Erlang. Any match against the <code>_</code> binding will succeed
-but the data will be discarded. This is especially useful for
-matching against many domain names in one go.</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">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"ninenines.:_"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Similarly, it is possible to have optional segments. Anything
-between brackets is optional.</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">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/[page/:number]"</span><span style="color: #990000">.</span>
-<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"[www.]ninenines.eu"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can also have imbricated optional 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: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/[page/[:number]]"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can retrieve the rest of the host or path using <code>[...]</code>.
-In the case of hosts it will match anything before, in the case
-of paths anything after the previously matched segments. It is
-a special case of optional segments, in that it can have
-zero, one or many segments. You can then find the segments using
-<code>cowboy_req:host_info/1</code> and <code>cowboy_req:path_info/1</code> respectively.
-They will be represented as a list of 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: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/[...]"</span><span style="color: #990000">.</span>
-<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"[...]ninenines.eu"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>If a binding appears twice in the routing rules, then the match
-will succeed only if they share the same value. This copies the
-Erlang pattern matching behavior.</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">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/:name/:name"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>This is also true when an optional segment is present. In this
-case the two values must be identical only if the segment is
-available.</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">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/:name/[:name]"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>If a binding is defined in both the host and path, then they must
-also share the same 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">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/:user/[...]"</span><span style="color: #990000">.</span>
-<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">":user.github.com"</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Finally, there are two special match values that can be used. The
-first is the atom <code>'_'</code> which will match any host or path.</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">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF6600">'_'</span><span style="color: #990000">.</span>
-<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF6600">'_'</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The second is the special host match <code>"*"</code> which will match the
-wildcard path, generally used alongside the <code>OPTIONS</code> method.</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">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"*"</span><span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_constraints">Constraints</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>After the matching has completed, the resulting bindings can be tested
-against a set of constraints. Constraints are only tested when the
-binding is defined. They run in the order you defined them. The match
-will succeed only if they all succeed. If the match fails, then Cowboy
-tries the next route in the list.</p></div>
-<div class="paragraph"><p>The format used for constraints is the same as match functions in
-<code>cowboy_req</code>: they are provided as a list of fields which may have
-one or more constraints. While the router accepts the same format,
-it will skip fields with no constraints and will also ignore default
-values, if any.</p></div>
-<div class="paragraph"><p>Read more about <a href="../constraints">constraints</a>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_compilation">Compilation</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The routes must be compiled before Cowboy can use them. The compilation
-step normalizes the routes to simplify the code and speed up the
-execution, but the routes are still looked up one by one in the end.
-Faster compilation strategies could be to compile the routes directly
-to Erlang code, but would require heavier dependencies.</p></div>
-<div class="paragraph"><p>To compile routes, just call the appropriate 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">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, 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_clear</span></span>(<span style="color: #FF6600">my_http_listener</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="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_live_update">Live update</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can use the <code>cowboy:set_env/3</code> function for updating the dispatch
-list used by routing. This will apply to all new connections accepted
-by the listener:</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">Dispatch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:compile</span></span>(<span style="color: #009900">Routes</span>),
-<span style="font-weight: bold"><span style="color: #000000">cowboy:set_env</span></span>(<span style="color: #FF6600">my_http_listener</span>, <span style="color: #FF6600">dispatch</span>, <span style="color: #009900">Dispatch</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Note that you need to compile the routes again before updating.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Cowboy does nothing by default.</p></div> +<div class="paragraph"><p>To make Cowboy useful, you need to map URIs to Erlang modules that will +handle the requests. This is called routing.</p></div> +<div class="paragraph"><p>When Cowboy receives a request, it tries to match the requested host and +path to the configured routes. When there’s a match, the route’s +associated handler is executed.</p></div> +<div class="paragraph"><p>Routes need to be compiled before they can be used by Cowboy. +The result of the compilation is the dispatch rules.</p></div> +<div class="sect1"> +<h2 id="_syntax">Syntax</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The general structure for the routes is defined as follow.</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">Routes</span> <span style="color: #990000">=</span> [<span style="color: #009900">Host1</span>, <span style="color: #009900">Host2</span>, <span style="color: #990000">...</span> <span style="color: #009900">HostN</span>]<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Each host contains matching rules for the host along with optional +constraints, and a list of routes for the path component.</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">Host1</span> <span style="color: #990000">=</span> {<span style="color: #009900">HostMatch</span>, <span style="color: #009900">PathsList</span>}<span style="color: #990000">.</span> +<span style="color: #009900">Host2</span> <span style="color: #990000">=</span> {<span style="color: #009900">HostMatch</span>, <span style="color: #009900">Constraints</span>, <span style="color: #009900">PathsList</span>}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The list of routes for the path component is defined similar to the +list of hosts.</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">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 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">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> +</div> +<div class="sect1"> +<h2 id="_match_syntax">Match syntax</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The match syntax is used to associate host names and paths with their +respective handlers.</p></div> +<div class="paragraph"><p>The match syntax is the same for host and path with a few subtleties. +Indeed, the segments separator is different, and the host is matched +starting from the last segment going to the first. All examples will +feature both host and path match rules and explain the differences +when encountered.</p></div> +<div class="paragraph"><p>Excluding special values that we will explain at the end of this section, +the simplest match value is a host or a path. It can be given as either +a <code>string()</code> or a <code>binary()</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">PathMatch1</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/"</span><span style="color: #990000">.</span> +<span style="color: #009900">PathMatch2</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/path/to/resource"</span><span style="color: #990000">.</span> + +<span style="color: #009900">HostMatch1</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"cowboy.example.org"</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>As you can see, all paths defined this way must start with a slash +character. Note that these two paths are identical as far as routing +is concerned.</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">PathMatch2</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/path/to/resource"</span><span style="color: #990000">.</span> +<span style="color: #009900">PathMatch3</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/path/to/resource/"</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Hosts with and without a trailing dot are equivalent for routing. +Similarly, hosts with and without a leading dot are also equivalent.</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">HostMatch1</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"cowboy.example.org"</span><span style="color: #990000">.</span> +<span style="color: #009900">HostMatch2</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"cowboy.example.org."</span><span style="color: #990000">.</span> +<span style="color: #009900">HostMatch3</span> <span style="color: #990000">=</span> <span style="color: #FF0000">".cowboy.example.org"</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>It is possible to extract segments of the host and path and to store +the values in the <code>Req</code> object for later use. We call these kind of +values bindings.</p></div> +<div class="paragraph"><p>The syntax for bindings is very simple. A segment that begins with +the <code>:</code> character means that what follows until the end of the segment +is the name of the binding in which the segment value will be stored.</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">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/:name/prices"</span><span style="color: #990000">.</span> +<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">":subdomain.example.org"</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>If these two end up matching when routing, you will end up with two +bindings defined, <code>subdomain</code> and <code>name</code>, each containing the +segment value where they were defined. For example, the URL +<code>http://test.example.org/hats/wild_cowboy_legendary/prices</code> will +result in having the value <code>test</code> bound to the name <code>subdomain</code> +and the value <code>wild_cowboy_legendary</code> bound to the name <code>name</code>. +They can later be retrieved using <code>cowboy_req:binding/{2,3}</code>. The +binding name must be given as an atom.</p></div> +<div class="paragraph"><p>There is a special binding name you can use to mimic the underscore +variable in Erlang. Any match against the <code>_</code> binding will succeed +but the data will be discarded. This is especially useful for +matching against many domain names in one go.</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">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"ninenines.:_"</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Similarly, it is possible to have optional segments. Anything +between brackets is optional.</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">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/[page/:number]"</span><span style="color: #990000">.</span> +<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"[www.]ninenines.eu"</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You can also have imbricated optional 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: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/[page/[:number]]"</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You can retrieve the rest of the host or path using <code>[...]</code>. +In the case of hosts it will match anything before, in the case +of paths anything after the previously matched segments. It is +a special case of optional segments, in that it can have +zero, one or many segments. You can then find the segments using +<code>cowboy_req:host_info/1</code> and <code>cowboy_req:path_info/1</code> respectively. +They will be represented as a list of 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: #009900">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/[...]"</span><span style="color: #990000">.</span> +<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"[...]ninenines.eu"</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>If a binding appears twice in the routing rules, then the match +will succeed only if they share the same value. This copies the +Erlang pattern matching behavior.</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">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/:name/:name"</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>This is also true when an optional segment is present. In this +case the two values must be identical only if the segment is +available.</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">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/hats/:name/[:name]"</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>If a binding is defined in both the host and path, then they must +also share the same 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">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"/:user/[...]"</span><span style="color: #990000">.</span> +<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">":user.github.com"</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Finally, there are two special match values that can be used. The +first is the atom <code>'_'</code> which will match any host or path.</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">PathMatch</span> <span style="color: #990000">=</span> <span style="color: #FF6600">'_'</span><span style="color: #990000">.</span> +<span style="color: #009900">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF6600">'_'</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The second is the special host match <code>"*"</code> which will match the +wildcard path, generally used alongside the <code>OPTIONS</code> method.</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">HostMatch</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"*"</span><span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_constraints">Constraints</h2> +<div class="sectionbody"> +<div class="paragraph"><p>After the matching has completed, the resulting bindings can be tested +against a set of constraints. Constraints are only tested when the +binding is defined. They run in the order you defined them. The match +will succeed only if they all succeed. If the match fails, then Cowboy +tries the next route in the list.</p></div> +<div class="paragraph"><p>The format used for constraints is the same as match functions in +<code>cowboy_req</code>: they are provided as a list of fields which may have +one or more constraints. While the router accepts the same format, +it will skip fields with no constraints and will also ignore default +values, if any.</p></div> +<div class="paragraph"><p>Read more about <a href="../constraints">constraints</a>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_compilation">Compilation</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The routes must be compiled before Cowboy can use them. The compilation +step normalizes the routes to simplify the code and speed up the +execution, but the routes are still looked up one by one in the end. +Faster compilation strategies could be to compile the routes directly +to Erlang code, but would require heavier dependencies.</p></div> +<div class="paragraph"><p>To compile routes, just call the appropriate 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">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, 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_clear</span></span>(<span style="color: #FF6600">my_http_listener</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="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_live_update">Live update</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You can use the <code>cowboy:set_env/3</code> function for updating the dispatch +list used by routing. This will apply to all new connections accepted +by the listener:</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">Dispatch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:compile</span></span>(<span style="color: #009900">Routes</span>), +<span style="font-weight: bold"><span style="color: #000000">cowboy:set_env</span></span>(<span style="color: #FF6600">my_http_listener</span>, <span style="color: #FF6600">dispatch</span>, <span style="color: #009900">Dispatch</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Note that you need to compile the routes again before updating.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/specs.asciidoc b/docs/en/cowboy/2.0/guide/specs.asciidoc index db4abe45..ec101fbd 100644 --- a/docs/en/cowboy/2.0/guide/specs.asciidoc +++ b/docs/en/cowboy/2.0/guide/specs.asciidoc @@ -44,7 +44,6 @@ for or related to HTTP. * https://tools.ietf.org/html/rfc5789[RFC 5789]: PATCH Method for HTTP * https://tools.ietf.org/html/rfc5843[RFC 5843]: Additional Hash Algorithms for HTTP Instance Digests * https://tools.ietf.org/html/rfc5861[RFC 5861]: HTTP Cache-Control Extensions for Stale Content -* https://tools.ietf.org/html/rfc5987[RFC 5987]: Character Set and Language Encoding for HTTP Header Field Parameters * https://tools.ietf.org/html/rfc5988[RFC 5988]: Web Linking * https://tools.ietf.org/html/rfc6265[RFC 6265]: HTTP State Management Mechanism * https://tools.ietf.org/html/rfc6266[RFC 6266]: Use of the Content-Disposition Header Field @@ -83,7 +82,9 @@ for or related to HTTP. * https://tools.ietf.org/html/rfc7936[RFC 7936]: Clarifying Registry Procedures for the WebSocket Subprotocol Name Registry * https://tools.ietf.org/html/rfc8053[RFC 8053]: HTTP Authentication Extensions for Interactive Clients * https://tools.ietf.org/html/rfc8164[RFC 8164]: Opportunistic Security for HTTP/2 +* https://tools.ietf.org/html/rfc8187[RFC 8187]: Indicating Character Encoding and Language for HTTP Header Field Parameters * https://tools.ietf.org/html/rfc8188[RFC 8188]: Encrypted Content-Encoding for HTTP +* https://tools.ietf.org/html/rfc8246[RFC 8246]: HTTP Immutable Responses * https://www.w3.org/TR/webmention/[Webmention]: Webmention ==== Upcoming diff --git a/docs/en/cowboy/2.0/guide/specs/index.html b/docs/en/cowboy/2.0/guide/specs/index.html index be0d89be..b0511164 100644 --- a/docs/en/cowboy/2.0/guide/specs/index.html +++ b/docs/en/cowboy/2.0/guide/specs/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: HTTP and other specifications</title> @@ -67,840 +67,848 @@ <h1 class="lined-header"><span>HTTP and other specifications</span></h1> -<div class="paragraph"><p>This chapter intends to list all the specification documents
-for or related to HTTP.</p></div>
-<div class="sect1">
-<h2 id="_http">HTTP</h2>
-<div class="sectionbody">
-<div class="sect3">
-<h4 id="_iana_registries">IANA Registries</h4>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="https://www.iana.org/assignments/http-methods/http-methods.xhtml">HTTP Method Registry</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml">HTTP Status Code Registry</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.iana.org/assignments/message-headers/message-headers.xhtml">Message Headers</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.iana.org/assignments/http-parameters/http-parameters.xhtml">HTTP Parameters</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.iana.org/assignments/http-alt-svc-parameters/http-alt-svc-parameters.xhtml">HTTP Alt-Svc Parameter Registry</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml">HTTP Authentication Scheme Registry</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.iana.org/assignments/http-cache-directives/http-cache-directives.xhtml">HTTP Cache Directive Registry</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml">HTTP Digest Algorithm Values</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.iana.org/assignments/hoba-device-identifiers/hoba-device-identifiers.xhtml">HTTP Origin-Bound Authentication Device Identifier Types</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.iana.org/assignments/http-upgrade-tokens/http-upgrade-tokens.xhtml">HTTP Upgrade Token Registry</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.iana.org/assignments/http-warn-codes/http-warn-codes.xhtml">HTTP Warn Codes</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.iana.org/assignments/http2-parameters/http2-parameters.xhtml">HTTP/2 Parameters</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.ietf.org/assignments/websocket/websocket.xml">WebSocket Protocol Registries</a>
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect3">
-<h4 id="_current">Current</h4>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="http://www.w3.org/TR/cors/">CORS</a>: Cross-Origin Resource Sharing
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/CSP2/">CSP2</a>: Content Security Policy Level 2
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/tracking-dnt/">DNT</a>: Tracking Preference Expression (DNT)
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/eventsource/">eventsource</a>: Server-Sent Events
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.w3.org/TR/html4/interact/forms.html#h-17.13.4">Form content types</a>: Form content types
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.w3.org/TR/preload/">Preload</a>: Preload
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm">REST</a>: Fielding’s Dissertation
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc1945">RFC 1945</a>: HTTP/1.0
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc1951">RFC 1951</a>: DEFLATE Compressed Data Format Specification version 1.3
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc1952">RFC 1952</a>: GZIP file format specification version 4.3
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc2046#section-5.1">RFC 2046</a>: Multipart media type (in MIME Part Two: Media Types)
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc2295">RFC 2295</a>: Transparent Content Negotiation in HTTP
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc2296">RFC 2296</a>: HTTP Remote Variant Selection Algorithm: RVSA/1.0
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc2817">RFC 2817</a>: Upgrading to TLS Within HTTP/1.1
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc2818">RFC 2818</a>: HTTP Over TLS
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc3230">RFC 3230</a>: Instance Digests in HTTP
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc4559">RFC 4559</a>: SPNEGO-based Kerberos and NTLM HTTP Authentication in Microsoft Windows
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc5789">RFC 5789</a>: PATCH Method for HTTP
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc5843">RFC 5843</a>: Additional Hash Algorithms for HTTP Instance Digests
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc5861">RFC 5861</a>: HTTP Cache-Control Extensions for Stale Content
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc5987">RFC 5987</a>: Character Set and Language Encoding for HTTP Header Field Parameters
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc5988">RFC 5988</a>: Web Linking
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6265">RFC 6265</a>: HTTP State Management Mechanism
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6266">RFC 6266</a>: Use of the Content-Disposition Header Field
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6454">RFC 6454</a>: The Web Origin Concept
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6455">RFC 6455</a>: The WebSocket Protocol
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6585">RFC 6585</a>: Additional HTTP Status Codes
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6750">RFC 6750</a>: The OAuth 2.0 Authorization Framework: Bearer Token Usage
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6797">RFC 6797</a>: HTTP Strict Transport Security (HSTS)
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6903">RFC 6903</a>: Additional Link Relation Types
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7034">RFC 7034</a>: HTTP Header Field X-Frame-Options
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7089">RFC 7089</a>: Time-Based Access to Resource States: Memento
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7230">RFC 7230</a>: HTTP/1.1 Message Syntax and Routing
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7231">RFC 7231</a>: HTTP/1.1 Semantics and Content
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7232">RFC 7232</a>: HTTP/1.1 Conditional Requests
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7233">RFC 7233</a>: HTTP/1.1 Range Requests
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7234">RFC 7234</a>: HTTP/1.1 Caching
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7235">RFC 7235</a>: HTTP/1.1 Authentication
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7239">RFC 7239</a>: Forwarded HTTP Extension
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7240">RFC 7240</a>: Prefer Header for HTTP
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7469">RFC 7469</a>: Public Key Pinning Extension for HTTP
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7486">RFC 7486</a>: HTTP Origin-Bound Authentication (HOBA)
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7538">RFC 7538</a>: HTTP Status Code 308 (Permanent Redirect)
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7540">RFC 7540</a>: Hypertext Transfer Protocol Version 2 (HTTP/2)
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7541">RFC 7541</a>: HPACK: Header Compression for HTTP/2
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7578">RFC 7578</a>: Returning Values from Forms: multipart/form-data
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7615">RFC 7615</a>: HTTP Authentication-Info and Proxy-Authentication-Info Response Header Fields
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7616">RFC 7616</a>: HTTP Digest Access Authentication
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7617">RFC 7617</a>: The <em>Basic</em> HTTP Authentication Scheme
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7639">RFC 7639</a>: The ALPN HTTP Header Field
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7692">RFC 7692</a>: Compression Extensions for WebSocket
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7694">RFC 7694</a>: HTTP Client-Initiated Content-Encoding
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7725">RFC 7725</a>: An HTTP Status Code to Report Legal Obstacles
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7804">RFC 7804</a>: Salted Challenge Response HTTP Authentication Mechanism
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7838">RFC 7838</a>: HTTP Alternative Services
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7932">RFC 7932</a>: Brotli Compressed Data Format
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7936">RFC 7936</a>: Clarifying Registry Procedures for the WebSocket Subprotocol Name Registry
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc8053">RFC 8053</a>: HTTP Authentication Extensions for Interactive Clients
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc8164">RFC 8164</a>: Opportunistic Security for HTTP/2
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc8188">RFC 8188</a>: Encrypted Content-Encoding for HTTP
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.w3.org/TR/webmention/">Webmention</a>: Webmention
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect3">
-<h4 id="_upcoming">Upcoming</h4>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="https://www.w3.org/TR/csp-cookies/">Content Security Policy: Cookie Controls</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.w3.org/TR/csp-embedded-enforcement/">Content Security Policy: Embedded Enforcement</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.w3.org/TR/CSP3/">Content Security Policy Level 3</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.w3.org/TR/csp-pinning/">Content Security Policy Pinning</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/referrer-policy/">Referrer Policy</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/UISecurity/">User Interface Security Directives for Content Security Policy</a>
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect3">
-<h4 id="_informative">Informative</h4>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="http://www.w3.org/TR/webarch/">Architecture of the World Wide Web</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc2936">RFC 2936</a>: HTTP MIME Type Handler Detection
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc2964">RFC 2964</a>: Use of HTTP State Management
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc3143">RFC 3143</a>: Known HTTP Proxy/Caching Problems
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6202">RFC 6202</a>: Known Issues and Best Practices for the Use of Long Polling and Streaming in Bidirectional HTTP
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6838">RFC 6838</a>: Media Type Specifications and Registration Procedures
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7478">RFC 7478</a>: Web Real-Time Communication Use Cases and Requirements
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect3">
-<h4 id="_related">Related</h4>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="http://www.w3.org/TR/app-uri/">app: URL Scheme</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/beacon/">Beacon</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/FileAPI/">File API</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc8030">Generic Event Delivery Using HTTP Push</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/capability-urls/">Good Practices for Capability URLs</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://html.spec.whatwg.org/multipage/">HTML Living Standard</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://developers.whatwg.org/">HTML Living Standard for Web developers</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/html401/">HTML4.01</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/html5/">HTML5</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/html51/">HTML5.1</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://www.w3.org/TR/html52/">HTML5.2</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/media-frags/">Media Fragments URI 1.0</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6690">RFC 6690</a>: Constrained RESTful Environments (CoRE) Link Format
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7807">RFC 7807</a>: Problem Details for HTTP APIs
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6906">RFC 6906</a>: The <em>profile</em> Link Relation Type
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/SRI/">Subresource Integrity</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/tracking-compliance/">Tracking Compliance and Scope</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/media-frags-reqs/">Use cases and requirements for Media Fragments</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/webrtc/">WebRTC 1.0: Real-time Communication Between Browsers</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/websockets/">Websocket API</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/XMLHttpRequest/">XMLHttpRequest Level 1</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://xhr.spec.whatwg.org/">XMLHttpRequest Living Standard</a>
-</p>
-</li>
-</ul></div>
-</div>
-<div class="sect3">
-<h4 id="_seemingly_obsolete">Seemingly obsolete</h4>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc2227">RFC 2227</a>: Simple Hit-Metering and Usage-Limiting for HTTP
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc2310">RFC 2310</a>: The Safe Response Header Field
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc2324">RFC 2324</a>: Hyper Text Coffee Pot Control Protocol (HTCPCP/1.0)
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc2660">RFC 2660</a>: The Secure HyperText Transfer Protocol
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc2774">RFC 2774</a>: An HTTP Extension Framework
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc2965">RFC 2965</a>: HTTP State Management Mechanism (Cookie2)
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc3229">RFC 3229</a>: Delta encoding in HTTP
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7168">RFC 7168</a>: The Hyper Text Coffee Pot Control Protocol for Tea Efflux Appliances (HTCPCP-TEA)
-</p>
-</li>
-<li>
-<p>
-<a href="http://dev.chromium.org/spdy/spdy-protocol">SPDY</a>: SPDY Protocol
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/draft-tyoshino-hybi-websocket-perframe-deflate-06">x-webkit-deflate-frame</a>: Deprecated Websocket compression
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_url">URL</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc3986">RFC 3986</a>: URI Generic Syntax
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6570">RFC 6570</a>: URI Template
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6874">RFC 6874</a>: Representing IPv6 Zone Identifiers in Address Literals and URIs
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7320">RFC 7320</a>: URI Design and Ownership
-</p>
-</li>
-<li>
-<p>
-<a href="http://www.w3.org/TR/url-1/">URL</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://url.spec.whatwg.org/">URL Living Standard</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_webdav">WebDAV</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc3253">RFC 3253</a>: Versioning Extensions to WebDAV
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc3648">RFC 3648</a>: WebDAV Ordered Collections Protocol
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc3744">RFC 3744</a>: WebDAV Access Control Protocol
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc4316">RFC 4316</a>: Datatypes for WebDAV Properties
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc4331">RFC 4331</a>: Quota and Size Properties for DAV Collections
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc4437">RFC 4437</a>: WebDAV Redirect Reference Resources
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc4709">RFC 4709</a>: Mounting WebDAV Servers
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc4791">RFC 4791</a>: Calendaring Extensions to WebDAV (CalDAV)
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc4918">RFC 4918</a>: HTTP Extensions for WebDAV
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc5323">RFC 5323</a>: WebDAV SEARCH
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc5397">RFC 5397</a>: WebDAV Current Principal Extension
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc5689">RFC 5689</a>: Extended MKCOL for WebDAV
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc5842">RFC 5842</a>: Binding Extensions to WebDAV
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc5995">RFC 5995</a>: Using POST to Add Members to WebDAV Collections
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6352">RFC 6352</a>: CardDAV: vCard Extensions to WebDAV
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6578">RFC 6578</a>: Collection Synchronization for WebDAV
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6638">RFC 6638</a>: Scheduling Extensions to CalDAV
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc6764">RFC 6764</a>: Locating Services for Calendaring Extensions to WebDAV (CalDAV) and vCard Extensions to WebDAV (CardDAV)
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7809">RFC 7809</a>: Calendaring Extensions to WebDAV (CalDAV): Time Zones by Reference
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7953">RFC 7953</a>: Calendar Availability
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc8144">RFC 8144</a>: Use of the Prefer Header Field in WebDAV
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_coap">CoAP</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7252">RFC 7252</a>: The Constrained Application Protocol (CoAP)
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7390">RFC 7390</a>: Group Communication for CoAP
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7641">RFC 7641</a>: Observing Resources in CoAP
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7650">RFC 7650</a>: A CoAP Usage for REsource LOcation And Discovery (RELOAD)
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7959">RFC 7959</a>: Block-Wise Transfers in CoAP
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc7967">RFC 7967</a>: CoAP Option for No Server Response
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc8075">RFC 8075</a>: Guidelines for Mapping Implementations: HTTP to CoAP
-</p>
-</li>
-<li>
-<p>
-<a href="https://tools.ietf.org/html/rfc8132">RFC 8132</a>: PATCH and FETCH Methods for CoAP
-</p>
-</li>
-</ul></div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter intends to list all the specification documents +for or related to HTTP.</p></div> +<div class="sect1"> +<h2 id="_http">HTTP</h2> +<div class="sectionbody"> +<div class="sect3"> +<h4 id="_iana_registries">IANA Registries</h4> +<div class="ulist"><ul> +<li> +<p> +<a href="https://www.iana.org/assignments/http-methods/http-methods.xhtml">HTTP Method Registry</a> +</p> +</li> +<li> +<p> +<a href="https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml">HTTP Status Code Registry</a> +</p> +</li> +<li> +<p> +<a href="https://www.iana.org/assignments/message-headers/message-headers.xhtml">Message Headers</a> +</p> +</li> +<li> +<p> +<a href="https://www.iana.org/assignments/http-parameters/http-parameters.xhtml">HTTP Parameters</a> +</p> +</li> +<li> +<p> +<a href="https://www.iana.org/assignments/http-alt-svc-parameters/http-alt-svc-parameters.xhtml">HTTP Alt-Svc Parameter Registry</a> +</p> +</li> +<li> +<p> +<a href="https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml">HTTP Authentication Scheme Registry</a> +</p> +</li> +<li> +<p> +<a href="https://www.iana.org/assignments/http-cache-directives/http-cache-directives.xhtml">HTTP Cache Directive Registry</a> +</p> +</li> +<li> +<p> +<a href="https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml">HTTP Digest Algorithm Values</a> +</p> +</li> +<li> +<p> +<a href="https://www.iana.org/assignments/hoba-device-identifiers/hoba-device-identifiers.xhtml">HTTP Origin-Bound Authentication Device Identifier Types</a> +</p> +</li> +<li> +<p> +<a href="https://www.iana.org/assignments/http-upgrade-tokens/http-upgrade-tokens.xhtml">HTTP Upgrade Token Registry</a> +</p> +</li> +<li> +<p> +<a href="https://www.iana.org/assignments/http-warn-codes/http-warn-codes.xhtml">HTTP Warn Codes</a> +</p> +</li> +<li> +<p> +<a href="https://www.iana.org/assignments/http2-parameters/http2-parameters.xhtml">HTTP/2 Parameters</a> +</p> +</li> +<li> +<p> +<a href="https://www.ietf.org/assignments/websocket/websocket.xml">WebSocket Protocol Registries</a> +</p> +</li> +</ul></div> +</div> +<div class="sect3"> +<h4 id="_current">Current</h4> +<div class="ulist"><ul> +<li> +<p> +<a href="http://www.w3.org/TR/cors/">CORS</a>: Cross-Origin Resource Sharing +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/CSP2/">CSP2</a>: Content Security Policy Level 2 +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/tracking-dnt/">DNT</a>: Tracking Preference Expression (DNT) +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/eventsource/">eventsource</a>: Server-Sent Events +</p> +</li> +<li> +<p> +<a href="https://www.w3.org/TR/html4/interact/forms.html#h-17.13.4">Form content types</a>: Form content types +</p> +</li> +<li> +<p> +<a href="https://www.w3.org/TR/preload/">Preload</a>: Preload +</p> +</li> +<li> +<p> +<a href="http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm">REST</a>: Fielding’s Dissertation +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc1945">RFC 1945</a>: HTTP/1.0 +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc1951">RFC 1951</a>: DEFLATE Compressed Data Format Specification version 1.3 +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc1952">RFC 1952</a>: GZIP file format specification version 4.3 +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc2046#section-5.1">RFC 2046</a>: Multipart media type (in MIME Part Two: Media Types) +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc2295">RFC 2295</a>: Transparent Content Negotiation in HTTP +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc2296">RFC 2296</a>: HTTP Remote Variant Selection Algorithm: RVSA/1.0 +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc2817">RFC 2817</a>: Upgrading to TLS Within HTTP/1.1 +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc2818">RFC 2818</a>: HTTP Over TLS +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc3230">RFC 3230</a>: Instance Digests in HTTP +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc4559">RFC 4559</a>: SPNEGO-based Kerberos and NTLM HTTP Authentication in Microsoft Windows +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc5789">RFC 5789</a>: PATCH Method for HTTP +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc5843">RFC 5843</a>: Additional Hash Algorithms for HTTP Instance Digests +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc5861">RFC 5861</a>: HTTP Cache-Control Extensions for Stale Content +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc5988">RFC 5988</a>: Web Linking +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6265">RFC 6265</a>: HTTP State Management Mechanism +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6266">RFC 6266</a>: Use of the Content-Disposition Header Field +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6454">RFC 6454</a>: The Web Origin Concept +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6455">RFC 6455</a>: The WebSocket Protocol +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6585">RFC 6585</a>: Additional HTTP Status Codes +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6750">RFC 6750</a>: The OAuth 2.0 Authorization Framework: Bearer Token Usage +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6797">RFC 6797</a>: HTTP Strict Transport Security (HSTS) +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6903">RFC 6903</a>: Additional Link Relation Types +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7034">RFC 7034</a>: HTTP Header Field X-Frame-Options +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7089">RFC 7089</a>: Time-Based Access to Resource States: Memento +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7230">RFC 7230</a>: HTTP/1.1 Message Syntax and Routing +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7231">RFC 7231</a>: HTTP/1.1 Semantics and Content +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7232">RFC 7232</a>: HTTP/1.1 Conditional Requests +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7233">RFC 7233</a>: HTTP/1.1 Range Requests +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7234">RFC 7234</a>: HTTP/1.1 Caching +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7235">RFC 7235</a>: HTTP/1.1 Authentication +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7239">RFC 7239</a>: Forwarded HTTP Extension +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7240">RFC 7240</a>: Prefer Header for HTTP +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7469">RFC 7469</a>: Public Key Pinning Extension for HTTP +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7486">RFC 7486</a>: HTTP Origin-Bound Authentication (HOBA) +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7538">RFC 7538</a>: HTTP Status Code 308 (Permanent Redirect) +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7540">RFC 7540</a>: Hypertext Transfer Protocol Version 2 (HTTP/2) +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7541">RFC 7541</a>: HPACK: Header Compression for HTTP/2 +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7578">RFC 7578</a>: Returning Values from Forms: multipart/form-data +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7615">RFC 7615</a>: HTTP Authentication-Info and Proxy-Authentication-Info Response Header Fields +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7616">RFC 7616</a>: HTTP Digest Access Authentication +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7617">RFC 7617</a>: The <em>Basic</em> HTTP Authentication Scheme +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7639">RFC 7639</a>: The ALPN HTTP Header Field +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7692">RFC 7692</a>: Compression Extensions for WebSocket +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7694">RFC 7694</a>: HTTP Client-Initiated Content-Encoding +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7725">RFC 7725</a>: An HTTP Status Code to Report Legal Obstacles +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7804">RFC 7804</a>: Salted Challenge Response HTTP Authentication Mechanism +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7838">RFC 7838</a>: HTTP Alternative Services +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7932">RFC 7932</a>: Brotli Compressed Data Format +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7936">RFC 7936</a>: Clarifying Registry Procedures for the WebSocket Subprotocol Name Registry +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc8053">RFC 8053</a>: HTTP Authentication Extensions for Interactive Clients +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc8164">RFC 8164</a>: Opportunistic Security for HTTP/2 +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc8187">RFC 8187</a>: Indicating Character Encoding and Language for HTTP Header Field Parameters +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc8188">RFC 8188</a>: Encrypted Content-Encoding for HTTP +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc8246">RFC 8246</a>: HTTP Immutable Responses +</p> +</li> +<li> +<p> +<a href="https://www.w3.org/TR/webmention/">Webmention</a>: Webmention +</p> +</li> +</ul></div> +</div> +<div class="sect3"> +<h4 id="_upcoming">Upcoming</h4> +<div class="ulist"><ul> +<li> +<p> +<a href="https://www.w3.org/TR/csp-cookies/">Content Security Policy: Cookie Controls</a> +</p> +</li> +<li> +<p> +<a href="https://www.w3.org/TR/csp-embedded-enforcement/">Content Security Policy: Embedded Enforcement</a> +</p> +</li> +<li> +<p> +<a href="https://www.w3.org/TR/CSP3/">Content Security Policy Level 3</a> +</p> +</li> +<li> +<p> +<a href="https://www.w3.org/TR/csp-pinning/">Content Security Policy Pinning</a> +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/referrer-policy/">Referrer Policy</a> +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/UISecurity/">User Interface Security Directives for Content Security Policy</a> +</p> +</li> +</ul></div> +</div> +<div class="sect3"> +<h4 id="_informative">Informative</h4> +<div class="ulist"><ul> +<li> +<p> +<a href="http://www.w3.org/TR/webarch/">Architecture of the World Wide Web</a> +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc2936">RFC 2936</a>: HTTP MIME Type Handler Detection +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc2964">RFC 2964</a>: Use of HTTP State Management +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc3143">RFC 3143</a>: Known HTTP Proxy/Caching Problems +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6202">RFC 6202</a>: Known Issues and Best Practices for the Use of Long Polling and Streaming in Bidirectional HTTP +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6838">RFC 6838</a>: Media Type Specifications and Registration Procedures +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7478">RFC 7478</a>: Web Real-Time Communication Use Cases and Requirements +</p> +</li> +</ul></div> +</div> +<div class="sect3"> +<h4 id="_related">Related</h4> +<div class="ulist"><ul> +<li> +<p> +<a href="http://www.w3.org/TR/app-uri/">app: URL Scheme</a> +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/beacon/">Beacon</a> +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/FileAPI/">File API</a> +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc8030">Generic Event Delivery Using HTTP Push</a> +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/capability-urls/">Good Practices for Capability URLs</a> +</p> +</li> +<li> +<p> +<a href="https://html.spec.whatwg.org/multipage/">HTML Living Standard</a> +</p> +</li> +<li> +<p> +<a href="https://developers.whatwg.org/">HTML Living Standard for Web developers</a> +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/html401/">HTML4.01</a> +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/html5/">HTML5</a> +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/html51/">HTML5.1</a> +</p> +</li> +<li> +<p> +<a href="https://www.w3.org/TR/html52/">HTML5.2</a> +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/media-frags/">Media Fragments URI 1.0</a> +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6690">RFC 6690</a>: Constrained RESTful Environments (CoRE) Link Format +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7807">RFC 7807</a>: Problem Details for HTTP APIs +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6906">RFC 6906</a>: The <em>profile</em> Link Relation Type +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/SRI/">Subresource Integrity</a> +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/tracking-compliance/">Tracking Compliance and Scope</a> +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/media-frags-reqs/">Use cases and requirements for Media Fragments</a> +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/webrtc/">WebRTC 1.0: Real-time Communication Between Browsers</a> +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/websockets/">Websocket API</a> +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/XMLHttpRequest/">XMLHttpRequest Level 1</a> +</p> +</li> +<li> +<p> +<a href="https://xhr.spec.whatwg.org/">XMLHttpRequest Living Standard</a> +</p> +</li> +</ul></div> +</div> +<div class="sect3"> +<h4 id="_seemingly_obsolete">Seemingly obsolete</h4> +<div class="ulist"><ul> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc2227">RFC 2227</a>: Simple Hit-Metering and Usage-Limiting for HTTP +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc2310">RFC 2310</a>: The Safe Response Header Field +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc2324">RFC 2324</a>: Hyper Text Coffee Pot Control Protocol (HTCPCP/1.0) +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc2660">RFC 2660</a>: The Secure HyperText Transfer Protocol +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc2774">RFC 2774</a>: An HTTP Extension Framework +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc2965">RFC 2965</a>: HTTP State Management Mechanism (Cookie2) +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc3229">RFC 3229</a>: Delta encoding in HTTP +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7168">RFC 7168</a>: The Hyper Text Coffee Pot Control Protocol for Tea Efflux Appliances (HTCPCP-TEA) +</p> +</li> +<li> +<p> +<a href="http://dev.chromium.org/spdy/spdy-protocol">SPDY</a>: SPDY Protocol +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/draft-tyoshino-hybi-websocket-perframe-deflate-06">x-webkit-deflate-frame</a>: Deprecated Websocket compression +</p> +</li> +</ul></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_url">URL</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc3986">RFC 3986</a>: URI Generic Syntax +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6570">RFC 6570</a>: URI Template +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6874">RFC 6874</a>: Representing IPv6 Zone Identifiers in Address Literals and URIs +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7320">RFC 7320</a>: URI Design and Ownership +</p> +</li> +<li> +<p> +<a href="http://www.w3.org/TR/url-1/">URL</a> +</p> +</li> +<li> +<p> +<a href="https://url.spec.whatwg.org/">URL Living Standard</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_webdav">WebDAV</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc3253">RFC 3253</a>: Versioning Extensions to WebDAV +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc3648">RFC 3648</a>: WebDAV Ordered Collections Protocol +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc3744">RFC 3744</a>: WebDAV Access Control Protocol +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc4316">RFC 4316</a>: Datatypes for WebDAV Properties +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc4331">RFC 4331</a>: Quota and Size Properties for DAV Collections +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc4437">RFC 4437</a>: WebDAV Redirect Reference Resources +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc4709">RFC 4709</a>: Mounting WebDAV Servers +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc4791">RFC 4791</a>: Calendaring Extensions to WebDAV (CalDAV) +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc4918">RFC 4918</a>: HTTP Extensions for WebDAV +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc5323">RFC 5323</a>: WebDAV SEARCH +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc5397">RFC 5397</a>: WebDAV Current Principal Extension +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc5689">RFC 5689</a>: Extended MKCOL for WebDAV +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc5842">RFC 5842</a>: Binding Extensions to WebDAV +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc5995">RFC 5995</a>: Using POST to Add Members to WebDAV Collections +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6352">RFC 6352</a>: CardDAV: vCard Extensions to WebDAV +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6578">RFC 6578</a>: Collection Synchronization for WebDAV +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6638">RFC 6638</a>: Scheduling Extensions to CalDAV +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc6764">RFC 6764</a>: Locating Services for Calendaring Extensions to WebDAV (CalDAV) and vCard Extensions to WebDAV (CardDAV) +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7809">RFC 7809</a>: Calendaring Extensions to WebDAV (CalDAV): Time Zones by Reference +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7953">RFC 7953</a>: Calendar Availability +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc8144">RFC 8144</a>: Use of the Prefer Header Field in WebDAV +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_coap">CoAP</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7252">RFC 7252</a>: The Constrained Application Protocol (CoAP) +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7390">RFC 7390</a>: Group Communication for CoAP +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7641">RFC 7641</a>: Observing Resources in CoAP +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7650">RFC 7650</a>: A CoAP Usage for REsource LOcation And Discovery (RELOAD) +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7959">RFC 7959</a>: Block-Wise Transfers in CoAP +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc7967">RFC 7967</a>: CoAP Option for No Server Response +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc8075">RFC 8075</a>: Guidelines for Mapping Implementations: HTTP to CoAP +</p> +</li> +<li> +<p> +<a href="https://tools.ietf.org/html/rfc8132">RFC 8132</a>: PATCH and FETCH Methods for CoAP +</p> +</li> +</ul></div> +</div> +</div> + + + <nav style="margin:1em 0"> 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 2509348f..f7a5c7f9 100644 --- a/docs/en/cowboy/2.0/guide/static_files/index.html +++ b/docs/en/cowboy/2.0/guide/static_files/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Static files</title> @@ -67,179 +67,182 @@ <h1 class="lined-header"><span>Static files</span></h1> -<div class="paragraph"><p>Cowboy comes with a ready to use handler for serving static
-files. It is provided as a convenience for serving files
-during development.</p></div>
-<div class="paragraph"><p>For systems in production, consider using one of the many
-Content Distribution Network (CDN) available on the market,
-as they are the best solution for serving files.</p></div>
-<div class="paragraph"><p>The static handler can serve either one file or all files
-from a given directory. The etag generation and mime types
-can be configured.</p></div>
-<div class="sect1">
-<h2 id="_serve_one_file">Serve one file</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can use the static handler to serve one specific file
-from an application’s private directory. This is particularly
-useful to serve an <em>index.html</em> file when the client requests
-the <code>/</code> path, for example. The path configured is relative
-to the given application’s private directory.</p></div>
-<div class="paragraph"><p>The following rule will serve the file <em>static/index.html</em>
-from the application <code>my_app</code>'s priv directory whenever the
-path <code>/</code> is accessed:</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: #FF0000">"/"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_file</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/index.html"</span>}}</tt></pre></div></div>
-<div class="paragraph"><p>You can also specify the absolute path to a file, or the
-path to the file relative to the current directory:</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: #FF0000">"/"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">file</span>, <span style="color: #FF0000">"/var/www/index.html"</span>}}</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_serve_all_files_from_a_directory">Serve all files from a directory</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can also use the static handler to serve all files that
-can be found in the configured directory. The handler will
-use the <code>path_info</code> information to resolve the file location,
-which means that your route must end with a <code>[...]</code> pattern
-for it to work. All files are served, including the ones that
-may be found in subfolders.</p></div>
-<div class="paragraph"><p>You can specify the directory relative to an application’s
-private directory.</p></div>
-<div class="paragraph"><p>The following rule will serve any file found in the application
-<code>my_app</code>'s priv directory inside the <code>static/assets</code> folder
-whenever the requested path begins with <code>/assets/</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: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>}}</tt></pre></div></div>
-<div class="paragraph"><p>You can also specify the absolute path to the directory or
-set it relative to the current directory:</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: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">dir</span>, <span style="color: #FF0000">"/var/www/assets"</span>}}</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_customize_the_mimetype_detection">Customize the mimetype detection</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>By default, Cowboy will attempt to recognize the mimetype
-of your static files by looking at the extension.</p></div>
-<div class="paragraph"><p>You can override the function that figures out the mimetype
-of the static files. It can be useful when Cowboy is missing
-a mimetype you need to handle, or when you want to reduce
-the list to make lookups faster. You can also give a
-hard-coded mimetype that will be used unconditionally.</p></div>
-<div class="paragraph"><p>Cowboy comes with two functions built-in. The default
-function only handles common file types used when building
-Web applications. The other function is an extensive list
-of hundreds of mimetypes that should cover almost any need
-you may have. You can of course create your own function.</p></div>
-<div class="paragraph"><p>To use the default function, you should not have to configure
-anything, as it is the default. If you insist, though, the
-following will do the job:</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: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>,
- [{<span style="color: #FF6600">mimetypes</span>, <span style="color: #FF6600">cow_mimetypes</span>, <span style="color: #FF6600">web</span>}]}}</tt></pre></div></div>
-<div class="paragraph"><p>As you can see, there is an optional field that may contain
-a list of less used options, like mimetypes or etag. All option
-types have this optional field.</p></div>
-<div class="paragraph"><p>To use the function that will detect almost any mimetype,
-the following configuration will do:</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: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>,
- [{<span style="color: #FF6600">mimetypes</span>, <span style="color: #FF6600">cow_mimetypes</span>, <span style="color: #FF6600">all</span>}]}}</tt></pre></div></div>
-<div class="paragraph"><p>You probably noticed the pattern by now. The configuration
-expects a module and a function name, so you can use any
-of your own functions instead:</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: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>,
- [{<span style="color: #FF6600">mimetypes</span>, <span style="color: #009900">Module</span>, <span style="color: #009900">Function</span>}]}}</tt></pre></div></div>
-<div class="paragraph"><p>The function that performs the mimetype detection receives
-a single argument that is the path to the file on disk. It
-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,
-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.
-This is especially useful in combination with the <code>file</code>
-and <code>priv_file</code> options as it avoids needless computation:</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: #FF0000">"/"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_file</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/index.html"</span>,
- [{<span style="color: #FF6600">mimetypes</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">"html"</span><span style="color: #990000">>></span>, []}}]}}</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_generate_an_etag">Generate an etag</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>By default, the static handler will generate an etag header
-value based on the size and modified time. This solution
-can not be applied to all systems though. It would perform
-rather poorly over a cluster of nodes, for example, as the
-file metadata will vary from server to server, giving a
-different etag on each server.</p></div>
-<div class="paragraph"><p>You can however change the way the etag is calculated:</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: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>,
- [{<span style="color: #FF6600">etag</span>, <span style="color: #009900">Module</span>, <span style="color: #009900">Function</span>}]}}</tt></pre></div></div>
-<div class="paragraph"><p>This function will receive three arguments: the path to the
-file on disk, the size of the file and the last modification
-time. In a distributed setup, you would typically use the
-file path to retrieve an etag value that is identical across
-all your servers.</p></div>
-<div class="paragraph"><p>You can also completely disable etag handling:</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: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>,
- [{<span style="color: #FF6600">etag</span>, <span style="color: #000080">false</span>}]}}</tt></pre></div></div>
-</div>
-</div>
+<div class="paragraph"><p>Cowboy comes with a ready to use handler for serving static +files. It is provided as a convenience for serving files +during development.</p></div> +<div class="paragraph"><p>For systems in production, consider using one of the many +Content Distribution Network (CDN) available on the market, +as they are the best solution for serving files.</p></div> +<div class="paragraph"><p>The static handler can serve either one file or all files +from a given directory. The etag generation and mime types +can be configured.</p></div> +<div class="sect1"> +<h2 id="_serve_one_file">Serve one file</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You can use the static handler to serve one specific file +from an application’s private directory. This is particularly +useful to serve an <em>index.html</em> file when the client requests +the <code>/</code> path, for example. The path configured is relative +to the given application’s private directory.</p></div> +<div class="paragraph"><p>The following rule will serve the file <em>static/index.html</em> +from the application <code>my_app</code>'s priv directory whenever the +path <code>/</code> is accessed:</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: #FF0000">"/"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_file</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/index.html"</span>}}</tt></pre></div></div> +<div class="paragraph"><p>You can also specify the absolute path to a file, or the +path to the file relative to the current directory:</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: #FF0000">"/"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">file</span>, <span style="color: #FF0000">"/var/www/index.html"</span>}}</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_serve_all_files_from_a_directory">Serve all files from a directory</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You can also use the static handler to serve all files that +can be found in the configured directory. The handler will +use the <code>path_info</code> information to resolve the file location, +which means that your route must end with a <code>[...]</code> pattern +for it to work. All files are served, including the ones that +may be found in subfolders.</p></div> +<div class="paragraph"><p>You can specify the directory relative to an application’s +private directory.</p></div> +<div class="paragraph"><p>The following rule will serve any file found in the application +<code>my_app</code>'s priv directory inside the <code>static/assets</code> folder +whenever the requested path begins with <code>/assets/</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: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>}}</tt></pre></div></div> +<div class="paragraph"><p>You can also specify the absolute path to the directory or +set it relative to the current directory:</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: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">dir</span>, <span style="color: #FF0000">"/var/www/assets"</span>}}</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_customize_the_mimetype_detection">Customize the mimetype detection</h2> +<div class="sectionbody"> +<div class="paragraph"><p>By default, Cowboy will attempt to recognize the mimetype +of your static files by looking at the extension.</p></div> +<div class="paragraph"><p>You can override the function that figures out the mimetype +of the static files. It can be useful when Cowboy is missing +a mimetype you need to handle, or when you want to reduce +the list to make lookups faster. You can also give a +hard-coded mimetype that will be used unconditionally.</p></div> +<div class="paragraph"><p>Cowboy comes with two functions built-in. The default +function only handles common file types used when building +Web applications. The other function is an extensive list +of hundreds of mimetypes that should cover almost any need +you may have. You can of course create your own function.</p></div> +<div class="paragraph"><p>To use the default function, you should not have to configure +anything, as it is the default. If you insist, though, the +following will do the job:</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: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>, + [{<span style="color: #FF6600">mimetypes</span>, <span style="color: #FF6600">cow_mimetypes</span>, <span style="color: #FF6600">web</span>}]}}</tt></pre></div></div> +<div class="paragraph"><p>As you can see, there is an optional field that may contain +a list of less used options, like mimetypes or etag. All option +types have this optional field.</p></div> +<div class="paragraph"><p>To use the function that will detect almost any mimetype, +the following configuration will do:</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: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>, + [{<span style="color: #FF6600">mimetypes</span>, <span style="color: #FF6600">cow_mimetypes</span>, <span style="color: #FF6600">all</span>}]}}</tt></pre></div></div> +<div class="paragraph"><p>You probably noticed the pattern by now. The configuration +expects a module and a function name, so you can use any +of your own functions instead:</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: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>, + [{<span style="color: #FF6600">mimetypes</span>, <span style="color: #009900">Module</span>, <span style="color: #009900">Function</span>}]}}</tt></pre></div></div> +<div class="paragraph"><p>The function that performs the mimetype detection receives +a single argument that is the path to the file on disk. It +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, +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. +This is especially useful in combination with the <code>file</code> +and <code>priv_file</code> options as it avoids needless computation:</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: #FF0000">"/"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_file</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/index.html"</span>, + [{<span style="color: #FF6600">mimetypes</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">"html"</span><span style="color: #990000">>></span>, []}}]}}</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_generate_an_etag">Generate an etag</h2> +<div class="sectionbody"> +<div class="paragraph"><p>By default, the static handler will generate an etag header +value based on the size and modified time. This solution +can not be applied to all systems though. It would perform +rather poorly over a cluster of nodes, for example, as the +file metadata will vary from server to server, giving a +different etag on each server.</p></div> +<div class="paragraph"><p>You can however change the way the etag is calculated:</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: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>, + [{<span style="color: #FF6600">etag</span>, <span style="color: #009900">Module</span>, <span style="color: #009900">Function</span>}]}}</tt></pre></div></div> +<div class="paragraph"><p>This function will receive three arguments: the path to the +file on disk, the size of the file and the last modification +time. In a distributed setup, you would typically use the +file path to retrieve an etag value that is identical across +all your servers.</p></div> +<div class="paragraph"><p>You can also completely disable etag handling:</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: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>, + [{<span style="color: #FF6600">etag</span>, <span style="color: #000080">false</span>}]}}</tt></pre></div></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/streams/index.html b/docs/en/cowboy/2.0/guide/streams/index.html index 4641b9b1..e7c82dd1 100644 --- a/docs/en/cowboy/2.0/guide/streams/index.html +++ b/docs/en/cowboy/2.0/guide/streams/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Streams</title> @@ -67,67 +67,70 @@ <h1 class="lined-header"><span>Streams</span></h1> -<div class="paragraph"><p>A stream is the set of messages that form an HTTP
-request/response pair.</p></div>
-<div class="paragraph"><p>The term stream comes from HTTP/2. In Cowboy, it is
-also used when talking about HTTP/1.1 or HTTP/1.0.
-It should not be confused with streaming the request
-or response body.</p></div>
-<div class="paragraph"><p>All versions of HTTP allow clients to initiate
-streams. HTTP/2 is the only one also allowing servers,
-through its server push feature. Both client and
-server-initiated streams go through the same process
-in Cowboy.</p></div>
-<div class="sect1">
-<h2 id="_stream_handlers">Stream handlers</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Stream handlers must implement five different callbacks.
-Four of them are directly related; one is special.</p></div>
-<div class="paragraph"><p>All callbacks receives the stream ID as first argument.</p></div>
-<div class="paragraph"><p>Most of them can return a list of commands to be executed
-by Cowboy. When callbacks are chained, it is possible to
-intercept and modify these commands. This can be useful
-for modifying responses for example.</p></div>
-<div class="paragraph"><p>The <code>init/3</code> callback is invoked when a new request
-comes in. It receives the Req object and the protocol options
-for this listener.</p></div>
-<div class="paragraph"><p>The <code>data/4</code> callback is invoked when data from the request
-body is received. It receives both this data and a flag
-indicating whether more is to be expected.</p></div>
-<div class="paragraph"><p>The <code>info/3</code> callback is invoked when an Erlang message is
-received for this stream. They will typically be messages
-sent by the request process.</p></div>
-<div class="paragraph"><p>Finally the <code>terminate/3</code> callback is invoked with the
-terminate reason for the stream. The return value is ignored.
-Note that as with all terminate callbacks in Erlang, there
-is no strong guarantee that it will be called.</p></div>
-<div class="paragraph"><p>The special callback <code>early_error/5</code> is called when an error
-occurs before the request headers were fully received and
-Cowboy is sending a response. It receives the partial Req
-object, the error reason, the protocol options and the response
-Cowboy will send. This response must be returned, possibly
-modified.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_built_in_handlers">Built-in handlers</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy comes with two handlers.</p></div>
-<div class="paragraph"><p><code>cowboy_stream_h</code> is the default stream handler.
-It is the core of much of the functionality of Cowboy.
-All chains of stream handlers should call it last.</p></div>
-<div class="paragraph"><p><code>cowboy_compress_h</code> will automatically compress
-responses when possible. It is not enabled by default.
-It is a good example for writing your own handlers
-that will modify responses.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>A stream is the set of messages that form an HTTP +request/response pair.</p></div> +<div class="paragraph"><p>The term stream comes from HTTP/2. In Cowboy, it is +also used when talking about HTTP/1.1 or HTTP/1.0. +It should not be confused with streaming the request +or response body.</p></div> +<div class="paragraph"><p>All versions of HTTP allow clients to initiate +streams. HTTP/2 is the only one also allowing servers, +through its server push feature. Both client and +server-initiated streams go through the same process +in Cowboy.</p></div> +<div class="sect1"> +<h2 id="_stream_handlers">Stream handlers</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Stream handlers must implement five different callbacks. +Four of them are directly related; one is special.</p></div> +<div class="paragraph"><p>All callbacks receives the stream ID as first argument.</p></div> +<div class="paragraph"><p>Most of them can return a list of commands to be executed +by Cowboy. When callbacks are chained, it is possible to +intercept and modify these commands. This can be useful +for modifying responses for example.</p></div> +<div class="paragraph"><p>The <code>init/3</code> callback is invoked when a new request +comes in. It receives the Req object and the protocol options +for this listener.</p></div> +<div class="paragraph"><p>The <code>data/4</code> callback is invoked when data from the request +body is received. It receives both this data and a flag +indicating whether more is to be expected.</p></div> +<div class="paragraph"><p>The <code>info/3</code> callback is invoked when an Erlang message is +received for this stream. They will typically be messages +sent by the request process.</p></div> +<div class="paragraph"><p>Finally the <code>terminate/3</code> callback is invoked with the +terminate reason for the stream. The return value is ignored. +Note that as with all terminate callbacks in Erlang, there +is no strong guarantee that it will be called.</p></div> +<div class="paragraph"><p>The special callback <code>early_error/5</code> is called when an error +occurs before the request headers were fully received and +Cowboy is sending a response. It receives the partial Req +object, the error reason, the protocol options and the response +Cowboy will send. This response must be returned, possibly +modified.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_built_in_handlers">Built-in handlers</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy comes with two handlers.</p></div> +<div class="paragraph"><p><code>cowboy_stream_h</code> is the default stream handler. +It is the core of much of the functionality of Cowboy. +All chains of stream handlers should call it last.</p></div> +<div class="paragraph"><p><code>cowboy_compress_h</code> will automatically compress +responses when possible. It is not enabled by default. +It is a good example for writing your own handlers +that will modify responses.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/ws_handlers.asciidoc b/docs/en/cowboy/2.0/guide/ws_handlers.asciidoc index 61a523b0..84dfb9bc 100644 --- a/docs/en/cowboy/2.0/guide/ws_handlers.asciidoc +++ b/docs/en/cowboy/2.0/guide/ws_handlers.asciidoc @@ -151,7 +151,9 @@ websocket_info(_Info, State) -> === Sending frames -// @todo So yeah, reply makes no sense. Maybe change it to send. Sigh. +// @todo This will be deprecated and eventually replaced with a +// {Commands, State} interface that allows providing more +// functionality easily. All `websocket_` callbacks share return values. They may send zero, one or many frames to the client. @@ -222,8 +224,6 @@ init(Req, State) -> This value cannot be changed once it is set. It defaults to `60000`. -// @todo Perhaps the default should be changed. - === Saving memory The Websocket connection process can be set to hibernate 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 7ec685bf..334bb049 100644 --- a/docs/en/cowboy/2.0/guide/ws_handlers/index.html +++ b/docs/en/cowboy/2.0/guide/ws_handlers/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Websocket handlers</title> @@ -67,276 +67,279 @@ <h1 class="lined-header"><span>Websocket handlers</span></h1> -<div class="paragraph"><p>Websocket handlers provide an interface for upgrading HTTP/1.1
-connections to Websocket and sending or receiving frames on
-the Websocket connection.</p></div>
-<div class="paragraph"><p>As Websocket connections are established through the HTTP/1.1
-upgrade mechanism, Websocket handlers need to be able to first
-receive the HTTP request for the upgrade, before switching to
-Websocket and taking over the connection. They can then receive
-or send Websocket frames, handle incoming Erlang messages or
-close the connection.</p></div>
-<div class="sect1">
-<h2 id="_upgrade">Upgrade</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>init/2</code> callback is called when the request is received.
-To establish a Websocket connection, you must switch to the
-<code>cowboy_websocket</code> module:</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">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>Cowboy will perform the Websocket handshake immediately. Note
-that the handshake will fail if the client did not request an
-upgrade to Websocket.</p></div>
-<div class="paragraph"><p>The Req object becomes unavailable after this function returns.
-Any information required for proper execution of the Websocket
-handler must be saved in the state.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_subprotocol">Subprotocol</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The client may provide a list of Websocket subprotocols it
-supports in the sec-websocket-protocol header. The server <strong>must</strong>
-select one of them and send it back to the client or the
-handshake will fail.</p></div>
-<div class="paragraph"><p>For example, a client could understand both STOMP and MQTT over
-Websocket, and provide the header:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>sec-websocket-protocol: v12.stomp, mqtt</code></pre>
-</div></div>
-<div class="paragraph"><p>If the server only understands MQTT it can return:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>sec-websocket-protocol: mqtt</code></pre>
-</div></div>
-<div class="paragraph"><p>This selection must be done in <code>init/2</code>. An example usage could
-be:</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">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">cowboy_websocket</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">"mqtt"</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">"mqtt"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>),
- {<span style="color: #FF6600">cowboy_websocket</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: #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>
-</div>
-<div class="sect1">
-<h2 id="_post_upgrade_initialization">Post-upgrade initialization</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy has separate processes for handling the connection
-and requests. Because Websocket takes over the connection,
-the Websocket protocol handling occurs in a different
-process than the request handling.</p></div>
-<div class="paragraph"><p>This is reflected in the different callbacks Websocket
-handlers have. The <code>init/2</code> callback is called from the
-temporary request process and the <code>websocket_</code> callbacks
-from the connection process.</p></div>
-<div class="paragraph"><p>This means that some initialization cannot be done from
-<code>init/2</code>. Anything that would require the current pid,
-or be tied to the current pid, will not work as intended.
-The optional <code>websocket_init/1</code> can be used instead:</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">websocket_init</span></span>(<span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">erlang:start_timer</span></span>(<span style="color: #993399">1000</span>, <span style="font-weight: bold"><span style="color: #000080">self</span></span>(), <span style="color: #990000"><<</span><span style="color: #FF0000">"Hello!"</span><span style="color: #990000">>></span>),
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>All Websocket callbacks share the same return values. This
-means that we can send frames to the client right after
-the upgrade:</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">websocket_init</span></span>(<span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">reply</span>, {<span style="color: #FF6600">text</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"Hello!"</span><span style="color: #990000">>></span>}, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_receiving_frames">Receiving frames</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy will call <code>websocket_handle/2</code> whenever a text, binary,
-ping or pong frame arrives from the client.</p></div>
-<div class="paragraph"><p>The handler can handle or ignore the frames. It can also
-send frames back to the client or stop the connection.</p></div>
-<div class="paragraph"><p>The following snippet echoes back any text frame received and
-ignores all others:</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">websocket_handle</span></span>(<span style="color: #009900">Frame</span> <span style="color: #990000">=</span> {<span style="color: #FF6600">text</span>, <span style="color: #990000">_</span>}, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">reply</span>, <span style="color: #009900">Frame</span>, <span style="color: #009900">State</span>};
-<span style="font-weight: bold"><span style="color: #000000">websocket_handle</span></span>(<span style="color: #009900">_Frame</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Note that ping and pong frames require no action from the
-handler as Cowboy will automatically reply to ping frames.
-They are provided for informative purposes only.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_receiving_erlang_messages">Receiving Erlang messages</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy will call <code>websocket_info/2</code> whenever an Erlang message
-arrives.</p></div>
-<div class="paragraph"><p>The handler can handle or ignore the messages. It can also
-send frames to the client or stop the connection.</p></div>
-<div class="paragraph"><p>The following snippet forwards log messages to the client
-and ignores all others:</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">websocket_info</span></span>({<span style="font-weight: bold"><span style="color: #000080">log</span></span>, <span style="color: #009900">Text</span>}, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">reply</span>, {<span style="color: #FF6600">text</span>, <span style="color: #009900">Text</span>}, <span style="color: #009900">State</span>};
-<span style="font-weight: bold"><span style="color: #000000">websocket_info</span></span>(<span style="color: #009900">_Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_sending_frames">Sending frames</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>All <code>websocket_</code> callbacks share return values. They may
-send zero, one or many frames to the client.</p></div>
-<div class="paragraph"><p>To send nothing, just return an ok tuple:</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">websocket_info</span></span>(<span style="color: #009900">_Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>To send one frame, return a reply tuple with the frame to send:</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">websocket_info</span></span>(<span style="color: #009900">_Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">reply</span>, {<span style="color: #FF6600">text</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"Hello!"</span><span style="color: #990000">>></span>}, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can send frames of any type: text, binary, ping, pong
-or close frames.</p></div>
-<div class="paragraph"><p>To send many frames at once, return a reply tuple with the
-list of frames to send:</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">websocket_info</span></span>(<span style="color: #009900">_Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">reply</span>, [
- {<span style="color: #FF6600">text</span>, <span style="color: #FF0000">"Hello"</span>},
- {<span style="color: #FF6600">text</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"world!"</span><span style="color: #990000">>></span>},
- {<span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #990000"><<</span><span style="color: #993399">0</span><span style="color: #990000">:</span><span style="color: #993399">8000</span><span style="color: #990000">>></span>}
- ], <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>They are sent in the given order.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_keeping_the_connection_alive">Keeping the connection alive</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy will automatically respond to ping frames sent by
-the client. They are still forwarded to the handler for
-informative purposes, but no further action is required.</p></div>
-<div class="paragraph"><p>Cowboy does not send ping frames itself. The handler can
-do it if required. A better solution in most cases is to
-let the client handle pings. Doing it from the handler
-would imply having an additional timer per connection and
-this can be a considerable cost for servers that need to
-handle large numbers of connections.</p></div>
-<div class="paragraph"><p>Cowboy can be configured to close idle connections
-automatically. It is highly recommended to configure
-a timeout here, to avoid having processes linger longer
-than needed.</p></div>
-<div class="paragraph"><p>The <code>init/2</code> callback can set the timeout to be used
-for the connection. For example, this would make Cowboy
-close connections idle for more than 30 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="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: #0000FF">idle_timeout</span> <span style="color: #990000">=></span> <span style="color: #993399">30000</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>60000</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_saving_memory">Saving memory</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The Websocket connection process can be set to hibernate
-after the callback returns.</p></div>
-<div class="paragraph"><p>Simply add an <code>hibernate</code> field to the ok or reply tuples:</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">websocket_init</span></span>(<span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">websocket_handle</span></span>(<span style="color: #009900">_Frame</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">websocket_info</span></span>(<span style="color: #009900">_Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">reply</span>, {<span style="color: #FF6600">text</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"Hello!"</span><span style="color: #990000">>></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>It is highly recommended to write your handlers with
-hibernate enabled, as this allows to greatly reduce the
-memory usage. Do note however that an increase in the
-CPU usage or latency can be observed instead, in particular
-for the more busy connections.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_closing_the_connection">Closing the connection</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The connection can be closed at any time, either by telling
-Cowboy to stop it or by sending a close frame.</p></div>
-<div class="paragraph"><p>To tell Cowboy to close the connection, use a stop tuple:</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">websocket_info</span></span>(<span style="color: #009900">_Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">stop</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Sending a <code>close</code> frame will immediately initiate the closing
-of the Websocket connection. Note that when sending a list of
-frames that include a close frame, any frame found after the
-close frame will not be sent.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Websocket handlers provide an interface for upgrading HTTP/1.1 +connections to Websocket and sending or receiving frames on +the Websocket connection.</p></div> +<div class="paragraph"><p>As Websocket connections are established through the HTTP/1.1 +upgrade mechanism, Websocket handlers need to be able to first +receive the HTTP request for the upgrade, before switching to +Websocket and taking over the connection. They can then receive +or send Websocket frames, handle incoming Erlang messages or +close the connection.</p></div> +<div class="sect1"> +<h2 id="_upgrade">Upgrade</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>init/2</code> callback is called when the request is received. +To establish a Websocket connection, you must switch to the +<code>cowboy_websocket</code> module:</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">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>Cowboy will perform the Websocket handshake immediately. Note +that the handshake will fail if the client did not request an +upgrade to Websocket.</p></div> +<div class="paragraph"><p>The Req object becomes unavailable after this function returns. +Any information required for proper execution of the Websocket +handler must be saved in the state.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_subprotocol">Subprotocol</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The client may provide a list of Websocket subprotocols it +supports in the sec-websocket-protocol header. The server <strong>must</strong> +select one of them and send it back to the client or the +handshake will fail.</p></div> +<div class="paragraph"><p>For example, a client could understand both STOMP and MQTT over +Websocket, and provide the header:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><code>sec-websocket-protocol: v12.stomp, mqtt</code></pre> +</div></div> +<div class="paragraph"><p>If the server only understands MQTT it can return:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><code>sec-websocket-protocol: mqtt</code></pre> +</div></div> +<div class="paragraph"><p>This selection must be done in <code>init/2</code>. An example usage could +be:</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">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">cowboy_websocket</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">"mqtt"</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">"mqtt"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>), + {<span style="color: #FF6600">cowboy_websocket</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: #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> +</div> +<div class="sect1"> +<h2 id="_post_upgrade_initialization">Post-upgrade initialization</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy has separate processes for handling the connection +and requests. Because Websocket takes over the connection, +the Websocket protocol handling occurs in a different +process than the request handling.</p></div> +<div class="paragraph"><p>This is reflected in the different callbacks Websocket +handlers have. The <code>init/2</code> callback is called from the +temporary request process and the <code>websocket_</code> callbacks +from the connection process.</p></div> +<div class="paragraph"><p>This means that some initialization cannot be done from +<code>init/2</code>. Anything that would require the current pid, +or be tied to the current pid, will not work as intended. +The optional <code>websocket_init/1</code> can be used instead:</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">websocket_init</span></span>(<span style="color: #009900">State</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">erlang:start_timer</span></span>(<span style="color: #993399">1000</span>, <span style="font-weight: bold"><span style="color: #000080">self</span></span>(), <span style="color: #990000"><<</span><span style="color: #FF0000">"Hello!"</span><span style="color: #990000">>></span>), + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>All Websocket callbacks share the same return values. This +means that we can send frames to the client right after +the upgrade:</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">websocket_init</span></span>(<span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">reply</span>, {<span style="color: #FF6600">text</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"Hello!"</span><span style="color: #990000">>></span>}, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_receiving_frames">Receiving frames</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy will call <code>websocket_handle/2</code> whenever a text, binary, +ping or pong frame arrives from the client.</p></div> +<div class="paragraph"><p>The handler can handle or ignore the frames. It can also +send frames back to the client or stop the connection.</p></div> +<div class="paragraph"><p>The following snippet echoes back any text frame received and +ignores all others:</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">websocket_handle</span></span>(<span style="color: #009900">Frame</span> <span style="color: #990000">=</span> {<span style="color: #FF6600">text</span>, <span style="color: #990000">_</span>}, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">reply</span>, <span style="color: #009900">Frame</span>, <span style="color: #009900">State</span>}; +<span style="font-weight: bold"><span style="color: #000000">websocket_handle</span></span>(<span style="color: #009900">_Frame</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Note that ping and pong frames require no action from the +handler as Cowboy will automatically reply to ping frames. +They are provided for informative purposes only.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_receiving_erlang_messages">Receiving Erlang messages</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy will call <code>websocket_info/2</code> whenever an Erlang message +arrives.</p></div> +<div class="paragraph"><p>The handler can handle or ignore the messages. It can also +send frames to the client or stop the connection.</p></div> +<div class="paragraph"><p>The following snippet forwards log messages to the client +and ignores all others:</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">websocket_info</span></span>({<span style="font-weight: bold"><span style="color: #000080">log</span></span>, <span style="color: #009900">Text</span>}, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">reply</span>, {<span style="color: #FF6600">text</span>, <span style="color: #009900">Text</span>}, <span style="color: #009900">State</span>}; +<span style="font-weight: bold"><span style="color: #000000">websocket_info</span></span>(<span style="color: #009900">_Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_sending_frames">Sending frames</h2> +<div class="sectionbody"> +<div class="paragraph"><p>All <code>websocket_</code> callbacks share return values. They may +send zero, one or many frames to the client.</p></div> +<div class="paragraph"><p>To send nothing, just return an ok tuple:</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">websocket_info</span></span>(<span style="color: #009900">_Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>To send one frame, return a reply tuple with the frame to send:</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">websocket_info</span></span>(<span style="color: #009900">_Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">reply</span>, {<span style="color: #FF6600">text</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"Hello!"</span><span style="color: #990000">>></span>}, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You can send frames of any type: text, binary, ping, pong +or close frames.</p></div> +<div class="paragraph"><p>To send many frames at once, return a reply tuple with the +list of frames to send:</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">websocket_info</span></span>(<span style="color: #009900">_Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">reply</span>, [ + {<span style="color: #FF6600">text</span>, <span style="color: #FF0000">"Hello"</span>}, + {<span style="color: #FF6600">text</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"world!"</span><span style="color: #990000">>></span>}, + {<span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #990000"><<</span><span style="color: #993399">0</span><span style="color: #990000">:</span><span style="color: #993399">8000</span><span style="color: #990000">>></span>} + ], <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>They are sent in the given order.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_keeping_the_connection_alive">Keeping the connection alive</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy will automatically respond to ping frames sent by +the client. They are still forwarded to the handler for +informative purposes, but no further action is required.</p></div> +<div class="paragraph"><p>Cowboy does not send ping frames itself. The handler can +do it if required. A better solution in most cases is to +let the client handle pings. Doing it from the handler +would imply having an additional timer per connection and +this can be a considerable cost for servers that need to +handle large numbers of connections.</p></div> +<div class="paragraph"><p>Cowboy can be configured to close idle connections +automatically. It is highly recommended to configure +a timeout here, to avoid having processes linger longer +than needed.</p></div> +<div class="paragraph"><p>The <code>init/2</code> callback can set the timeout to be used +for the connection. For example, this would make Cowboy +close connections idle for more than 30 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="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: #0000FF">idle_timeout</span> <span style="color: #990000">=></span> <span style="color: #993399">30000</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>60000</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_saving_memory">Saving memory</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The Websocket connection process can be set to hibernate +after the callback returns.</p></div> +<div class="paragraph"><p>Simply add an <code>hibernate</code> field to the ok or reply tuples:</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">websocket_init</span></span>(<span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">websocket_handle</span></span>(<span style="color: #009900">_Frame</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">websocket_info</span></span>(<span style="color: #009900">_Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">reply</span>, {<span style="color: #FF6600">text</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"Hello!"</span><span style="color: #990000">>></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>It is highly recommended to write your handlers with +hibernate enabled, as this allows to greatly reduce the +memory usage. Do note however that an increase in the +CPU usage or latency can be observed instead, in particular +for the more busy connections.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_closing_the_connection">Closing the connection</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The connection can be closed at any time, either by telling +Cowboy to stop it or by sending a close frame.</p></div> +<div class="paragraph"><p>To tell Cowboy to close the connection, use a stop tuple:</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">websocket_info</span></span>(<span style="color: #009900">_Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">stop</span>, <span style="color: #009900">State</span>}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Sending a <code>close</code> frame will immediately initiate the closing +of the Websocket connection. Note that when sending a list of +frames that include a close frame, any frame found after the +close frame will not be sent.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/guide/ws_protocol/index.html b/docs/en/cowboy/2.0/guide/ws_protocol/index.html index 38b754b0..d70fe10d 100644 --- a/docs/en/cowboy/2.0/guide/ws_protocol/index.html +++ b/docs/en/cowboy/2.0/guide/ws_protocol/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: The Websocket protocol</title> @@ -67,76 +67,79 @@ <h1 class="lined-header"><span>The Websocket protocol</span></h1> -<div class="paragraph"><p>This chapter explains what Websocket is and why it is
-a vital component of soft realtime Web applications.</p></div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Websocket is an extension to HTTP that emulates plain TCP
-connections between the client, typically a Web browser,
-and the server. It uses the HTTP Upgrade mechanism to
-establish the connection.</p></div>
-<div class="paragraph"><p>Websocket connections are fully asynchronous, unlike
-HTTP/1.1 (synchronous) and HTTP/2 (asynchronous, but the
-server can only initiate streams in response to requests).
-With Websocket, the client and the server can both send
-frames at any time without any restriction. It is closer
-to TCP than any of the HTTP protocols.</p></div>
-<div class="paragraph"><p>Websocket is an IETF standard. Cowboy supports the standard
-and all drafts that were previously implemented by browsers,
-excluding the initial flawed draft sometimes known as
-"version 0".</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_websocket_vs_http_2">Websocket vs HTTP/2</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>For a few years Websocket was the only way to have a
-bidirectional asynchronous connection with the server.
-This changed when HTTP/2 was introduced. While HTTP/2
-requires the client to first perform a request before
-the server can push data, this is only a minor restriction
-as the client can do so just as it connects.</p></div>
-<div class="paragraph"><p>Websocket was designed as a kind-of-TCP channel to a
-server. It only defines the framing and connection
-management and lets the developer implement a protocol
-on top of it. For example you could implement IRC over
-Websocket and use a Javascript IRC client to speak to
-the server.</p></div>
-<div class="paragraph"><p>HTTP/2 on the other hand is just an improvement over
-the HTTP/1.1 connection and request/response mechanism.
-It has the same semantics as HTTP/1.1.</p></div>
-<div class="paragraph"><p>If all you need is to access an HTTP API, then HTTP/2
-should be your first choice. On the other hand, if what
-you need is a different protocol, then you can use
-Websocket to implement it.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_implementation">Implementation</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy implements Websocket as a protocol upgrade. Once the
-upgrade is performed from the <code>init/2</code> callback, Cowboy
-switches to Websocket. Please consult the next chapter for
-more information on initiating and handling Websocket
-connections.</p></div>
-<div class="paragraph"><p>The implementation of Websocket in Cowboy is validated using
-the Autobahn test suite, which is an extensive suite of tests
-covering all aspects of the protocol. Cowboy passes the
-suite with 100% success, including all optional tests.</p></div>
-<div class="paragraph"><p>Cowboy’s Websocket implementation also includes the
-permessage-deflate and x-webkit-deflate-frame compression
-extensions.</p></div>
-<div class="paragraph"><p>Cowboy will automatically use compression when the
-<code>compress</code> option is returned from the <code>init/2</code> function.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter explains what Websocket is and why it is +a vital component of soft realtime Web applications.</p></div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Websocket is an extension to HTTP that emulates plain TCP +connections between the client, typically a Web browser, +and the server. It uses the HTTP Upgrade mechanism to +establish the connection.</p></div> +<div class="paragraph"><p>Websocket connections are fully asynchronous, unlike +HTTP/1.1 (synchronous) and HTTP/2 (asynchronous, but the +server can only initiate streams in response to requests). +With Websocket, the client and the server can both send +frames at any time without any restriction. It is closer +to TCP than any of the HTTP protocols.</p></div> +<div class="paragraph"><p>Websocket is an IETF standard. Cowboy supports the standard +and all drafts that were previously implemented by browsers, +excluding the initial flawed draft sometimes known as +"version 0".</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_websocket_vs_http_2">Websocket vs HTTP/2</h2> +<div class="sectionbody"> +<div class="paragraph"><p>For a few years Websocket was the only way to have a +bidirectional asynchronous connection with the server. +This changed when HTTP/2 was introduced. While HTTP/2 +requires the client to first perform a request before +the server can push data, this is only a minor restriction +as the client can do so just as it connects.</p></div> +<div class="paragraph"><p>Websocket was designed as a kind-of-TCP channel to a +server. It only defines the framing and connection +management and lets the developer implement a protocol +on top of it. For example you could implement IRC over +Websocket and use a Javascript IRC client to speak to +the server.</p></div> +<div class="paragraph"><p>HTTP/2 on the other hand is just an improvement over +the HTTP/1.1 connection and request/response mechanism. +It has the same semantics as HTTP/1.1.</p></div> +<div class="paragraph"><p>If all you need is to access an HTTP API, then HTTP/2 +should be your first choice. On the other hand, if what +you need is a different protocol, then you can use +Websocket to implement it.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_implementation">Implementation</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy implements Websocket as a protocol upgrade. Once the +upgrade is performed from the <code>init/2</code> callback, Cowboy +switches to Websocket. Please consult the next chapter for +more information on initiating and handling Websocket +connections.</p></div> +<div class="paragraph"><p>The implementation of Websocket in Cowboy is validated using +the Autobahn test suite, which is an extensive suite of tests +covering all aspects of the protocol. Cowboy passes the +suite with 100% success, including all optional tests.</p></div> +<div class="paragraph"><p>Cowboy’s Websocket implementation also includes the +permessage-deflate and x-webkit-deflate-frame compression +extensions.</p></div> +<div class="paragraph"><p>Cowboy will automatically use compression when the +<code>compress</code> option is returned from the <code>init/2</code> function.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/cowboy/2.0/index.html b/docs/en/cowboy/2.0/index.html index d87c4243..0194031a 100644 --- a/docs/en/cowboy/2.0/index.html +++ b/docs/en/cowboy/2.0/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file diff --git a/docs/en/cowboy/2.0/manual/cowboy.set_env/index.html b/docs/en/cowboy/2.0/manual/cowboy.set_env/index.html index 1381c03d..914b466c 100644 --- a/docs/en/cowboy/2.0/manual/cowboy.set_env/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy.set_env/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy:set_env(3)</title> @@ -67,117 +67,117 @@ <h1 class="lined-header"><span>cowboy:set_env(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy:set_env - Update a listener’s environment value</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">set_env</span></span>(<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch:ref</span></span>(),
- <span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>(),
- <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>())
- <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span></tt></pre></div></div>
-<div class="paragraph"><p>Set or update an environment value for a previously started
-listener.</p></div>
-<div class="paragraph"><p>This is most useful for updating the routes dynamically,
-without having to restart the listener.</p></div>
-<div class="paragraph"><p>The new value will only be available to new connections.
-Pre-existing connections will still use the old value.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name
-</dt>
-<dd>
-<p>
-The name of the listener to update.
-</p>
-<div class="paragraph"><p>The name of the listener is the first argument given to the
-<a href="../cowboy.start_clear">cowboy:start_clear(3)</a>,
-<a href="../cowboy.start_tls">cowboy:start_tls(3)</a> or
-<a href="../ranch.start_listener">ranch:start_listener(3)</a> function.</p></div>
-</dd>
-<dt class="hdlist1">
-Key
-</dt>
-<dd>
-<p>
-The key in the environment map. Common keys include <code>dispatch</code>
-and <code>middlewares</code>.
-</p>
-</dd>
-<dt class="hdlist1">
-Value
-</dt>
-<dd>
-<p>
-The new value.
-</p>
-<div class="paragraph"><p>The type of the value differs depending on the key.</p></div>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The atom <code>ok</code> is returned on success.</p></div>
-<div class="paragraph"><p>An <code>exit:badarg</code> exception is thrown when the listener does
-not exist.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Update a listener’s routes</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">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">toppage_h</span>, []},
- {<span style="color: #FF0000">"/ws"</span>, <span style="color: #FF6600">websocket_h</span>, []}
- ]}
-]),
-
-<span style="font-weight: bold"><span style="color: #000000">cowboy:set_env</span></span>(<span style="color: #FF6600">example</span>, <span style="color: #FF6600">dispatch</span>, <span style="color: #009900">Dispatch</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy">cowboy(3)</a>,
-<a href="../cowboy.start_clear">cowboy:start_clear(3)</a>,
-<a href="../cowboy.start_tls">cowboy:start_tls(3)</a>,
-<a href="../ranch.set_protocol_options">ranch:set_protocol_options(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy:set_env - Update a listener’s environment value</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">set_env</span></span>(<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch:ref</span></span>(), + <span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>(), + <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()) + <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span></tt></pre></div></div> +<div class="paragraph"><p>Set or update an environment value for a previously started +listener.</p></div> +<div class="paragraph"><p>This is most useful for updating the routes dynamically, +without having to restart the listener.</p></div> +<div class="paragraph"><p>The new value will only be available to new connections. +Pre-existing connections will still use the old value.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name +</dt> +<dd> +<p> +The name of the listener to update. +</p> +<div class="paragraph"><p>The name of the listener is the first argument given to the +<a href="../cowboy.start_clear">cowboy:start_clear(3)</a>, +<a href="../cowboy.start_tls">cowboy:start_tls(3)</a> or +<a href="../ranch.start_listener">ranch:start_listener(3)</a> function.</p></div> +</dd> +<dt class="hdlist1"> +Key +</dt> +<dd> +<p> +The key in the environment map. Common keys include <code>dispatch</code> +and <code>middlewares</code>. +</p> +</dd> +<dt class="hdlist1"> +Value +</dt> +<dd> +<p> +The new value. +</p> +<div class="paragraph"><p>The type of the value differs depending on the key.</p></div> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The atom <code>ok</code> is returned on success.</p></div> +<div class="paragraph"><p>An <code>exit:badarg</code> exception is thrown when the listener does +not exist.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Update a listener’s routes</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">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">toppage_h</span>, []}, + {<span style="color: #FF0000">"/ws"</span>, <span style="color: #FF6600">websocket_h</span>, []} + ]} +]), + +<span style="font-weight: bold"><span style="color: #000000">cowboy:set_env</span></span>(<span style="color: #FF6600">example</span>, <span style="color: #FF6600">dispatch</span>, <span style="color: #009900">Dispatch</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy">cowboy(3)</a>, +<a href="../cowboy.start_clear">cowboy:start_clear(3)</a>, +<a href="../cowboy.start_tls">cowboy:start_tls(3)</a>, +<a href="../ranch.set_protocol_options">ranch:set_protocol_options(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy.start_clear/index.html b/docs/en/cowboy/2.0/manual/cowboy.start_clear/index.html index 81f53fd4..a544cc71 100644 --- a/docs/en/cowboy/2.0/manual/cowboy.start_clear/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy.start_clear/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy:start_clear(3)</title> @@ -67,151 +67,148 @@ <h1 class="lined-header"><span>cowboy:start_clear(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy:start_clear - Listen for connections using plain TCP</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">start_clear</span></span>(<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch:ref</span></span>(),
- <span style="color: #009900">TransportOpts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch_tcp:opts</span></span>(),
- <span style="color: #009900">ProtocolOpts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">opts</span></span>())
- <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">ListenerPid</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">pid</span></span>()}
- | {<span style="color: #FF6600">error</span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>Start listening for connections over a clear TCP channel.</p></div>
-<div class="paragraph"><p>Both HTTP/1.1 and HTTP/2 are supported on this listener.
-HTTP/2 has two methods of establishing a connection over
-a clear TCP channel. Both the upgrade and the prior knowledge
-methods are supported.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name
-</dt>
-<dd>
-<p>
-The listener name is used to refer to this listener in
-future calls, for example when stopping it or when
-updating the routes defined.
-</p>
-<div class="paragraph"><p>It can be any Erlang term. An atom is generally good enough,
-for example <code>api</code>, <code>my_app_clear</code> or <code>my_app_tls</code>.</p></div>
-</dd>
-<dt class="hdlist1">
-TransportOpts
-</dt>
-<dd>
-<p>
-The transport options are where the TCP options, including
-the listener’s port number, are defined. Transport options
-are provided as a list of keys and values, for example
-<code>[{port, 8080}]</code>.
-</p>
-<div class="paragraph"><p>The available options are documented in the
-<a href="../ranch_tcp">ranch_tcp(3)</a> manual.</p></div>
-</dd>
-<dt class="hdlist1">
-ProtocolOpts
-</dt>
-<dd>
-<p>
-The protocol options are in a map containing all the options for
-the different protocols that may be involved when connecting
-to the listener, including HTTP/1.1 and HTTP/2 but also
-subprotocols like Websocket.
-</p>
-<div class="paragraph"><p>The HTTP/1.1 options are documented in the
-<a href="../cowboy_http">cowboy_http(3)</a> manual;
-the HTTP/2 options in
-<a href="../cowboy_http2">cowboy_http2(3)</a>;
-and the Websocket options in
-<a href="../cowboy_websocket">cowboy_websocket(3)</a>.</p></div>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An ok tuple is returned on success. It contains the pid of
-the top-level supervisor for the listener.</p></div>
-<div class="paragraph"><p>An error tuple is returned on error. The error reason may
-be any Erlang term.</p></div>
-<div class="paragraph"><p>A common error is <code>eaddrinuse</code>. It indicates that the port
-configured for Cowboy is already in use.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: HTTP/2 support added.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced. Replaces <code>cowboy:start_http/4</code>.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Start a listener</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">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">toppage_h</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">example</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="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Start a listener on a random port</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">Name</span> <span style="color: #990000">=</span> <span style="color: #FF6600">example</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: #009900">Name</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: #009900">Port</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_port</span></span>(<span style="color: #009900">Name</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy">cowboy(3)</a>,
-<a href="../cowboy.start_tls">cowboy:start_tls(3)</a>,
-<a href="../cowboy.stop_listener">cowboy:stop_listener(3)</a>,
-<a href="../ranch">ranch(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy:start_clear - Listen for connections using plain TCP</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">start_clear</span></span>(<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch:ref</span></span>(), + <span style="color: #009900">TransportOpts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch_tcp:opts</span></span>(), + <span style="color: #009900">ProtocolOpts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">opts</span></span>()) + <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">ListenerPid</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">pid</span></span>()} + | {<span style="color: #FF6600">error</span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Start listening for connections over a clear TCP channel.</p></div> +<div class="paragraph"><p>Both HTTP/1.1 and HTTP/2 are supported on this listener. +HTTP/2 has two methods of establishing a connection over +a clear TCP channel. Both the upgrade and the prior knowledge +methods are supported.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name +</dt> +<dd> +<p> +The listener name is used to refer to this listener in +future calls, for example when stopping it or when +updating the routes defined. +</p> +<div class="paragraph"><p>It can be any Erlang term. An atom is generally good enough, +for example <code>api</code>, <code>my_app_clear</code> or <code>my_app_tls</code>.</p></div> +</dd> +<dt class="hdlist1"> +TransportOpts +</dt> +<dd> +<p> +The transport options are where the TCP options, including +the listener’s port number, are defined. Transport options +are provided as a list of keys and values, for example +<code>[{port, 8080}]</code>. +</p> +<div class="paragraph"><p>The available options are documented in the +<a href="../ranch_tcp">ranch_tcp(3)</a> manual.</p></div> +</dd> +<dt class="hdlist1"> +ProtocolOpts +</dt> +<dd> +<p> +The protocol options are in a map containing all the options for +the different protocols that may be involved when connecting +to the listener, including HTTP/1.1 and HTTP/2. +</p> +<div class="paragraph"><p>The HTTP/1.1 options are documented in the +<a href="../cowboy_http">cowboy_http(3)</a> manual; +and the HTTP/2 options in +<a href="../cowboy_http2">cowboy_http2(3)</a>.</p></div> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An ok tuple is returned on success. It contains the pid of +the top-level supervisor for the listener.</p></div> +<div class="paragraph"><p>An error tuple is returned on error. The error reason may +be any Erlang term.</p></div> +<div class="paragraph"><p>A common error is <code>eaddrinuse</code>. It indicates that the port +configured for Cowboy is already in use.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: HTTP/2 support added. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: Function introduced. Replaces <code>cowboy:start_http/4</code>. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Start a listener</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">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">toppage_h</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">example</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="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Start a listener on a random port</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">Name</span> <span style="color: #990000">=</span> <span style="color: #FF6600">example</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: #009900">Name</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: #009900">Port</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_port</span></span>(<span style="color: #009900">Name</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy">cowboy(3)</a>, +<a href="../cowboy.start_tls">cowboy:start_tls(3)</a>, +<a href="../cowboy.stop_listener">cowboy:stop_listener(3)</a>, +<a href="../ranch">ranch(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy.start_tls/index.html b/docs/en/cowboy/2.0/manual/cowboy.start_tls/index.html index 47097caf..7b660e07 100644 --- a/docs/en/cowboy/2.0/manual/cowboy.start_tls/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy.start_tls/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy:start_tls(3)</title> @@ -67,156 +67,153 @@ <h1 class="lined-header"><span>cowboy:start_tls(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy:start_tls - Listen for connections using TLS</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">start_tls</span></span>(<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch:ref</span></span>(),
- <span style="color: #009900">TransportOpts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch_ssl:opts</span></span>(),
- <span style="color: #009900">ProtocolOpts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">opts</span></span>())
- <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">ListenerPid</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">pid</span></span>()}
- | {<span style="color: #FF6600">error</span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>Start listening for connections over a secure TLS channel.</p></div>
-<div class="paragraph"><p>Both HTTP/1.1 and HTTP/2 are supported on this listener.
-The ALPN TLS extension must be used to initiate an HTTP/2
-connection.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name
-</dt>
-<dd>
-<p>
-The listener name is used to refer to this listener in
-future calls, for example when stopping it or when
-updating the routes defined.
-</p>
-<div class="paragraph"><p>It can be any Erlang term. An atom is generally good enough,
-for example <code>api</code>, <code>my_app_clear</code> or <code>my_app_tls</code>.</p></div>
-</dd>
-<dt class="hdlist1">
-TransportOpts
-</dt>
-<dd>
-<p>
-The transport options are where the TCP options, including
-the listener’s port number, are defined. They also contain
-the TLS options, like the server’s certificate. Transport options
-are provided as a list of keys and values, for example
-<code>[{port, 8443}, {certfile, "path/to/cert.pem"}]</code>.
-</p>
-<div class="paragraph"><p>The available options are documented in the
-<a href="../ranch_ssl">ranch_ssl(3)</a> manual.</p></div>
-</dd>
-<dt class="hdlist1">
-ProtocolOpts
-</dt>
-<dd>
-<p>
-The protocol options are in a map containing all the options for
-the different protocols that may be involved when connecting
-to the listener, including HTTP/1.1 and HTTP/2 but also
-subprotocols like Websocket.
-</p>
-<div class="paragraph"><p>The HTTP/1.1 options are documented in the
-<a href="../cowboy_http">cowboy_http(3)</a> manual;
-the HTTP/2 options in
-<a href="../cowboy_http2">cowboy_http2(3)</a>;
-and the Websocket options in
-<a href="../cowboy_websocket">cowboy_websocket(3)</a>.</p></div>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An ok tuple is returned on success. It contains the pid of
-the top-level supervisor for the listener.</p></div>
-<div class="paragraph"><p>An error tuple is returned on error. The error reason may
-be any Erlang term.</p></div>
-<div class="paragraph"><p>A common error is <code>eaddrinuse</code>. It indicates that the port
-configured for Cowboy is already in use.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: HTTP/2 support added.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced. Replaces <code>cowboy:start_https/4</code>.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Start a listener</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">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">toppage_h</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_tls</span></span>(<span style="color: #FF6600">example</span>, [
- {<span style="color: #FF6600">port</span>, <span style="color: #993399">8443</span>},
- {<span style="color: #FF6600">cert</span>, <span style="color: #FF0000">"path/to/cert.pem"</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="listingblock">
-<div class="title">Start a listener on a random port</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">Name</span> <span style="color: #990000">=</span> <span style="color: #FF6600">example</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_tls</span></span>(<span style="color: #009900">Name</span>, [
- {<span style="color: #FF6600">cert</span>, <span style="color: #FF0000">"path/to/cert.pem"</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: #009900">Port</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_port</span></span>(<span style="color: #009900">Name</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy">cowboy(3)</a>,
-<a href="../cowboy.start_clear">cowboy:start_clear(3)</a>,
-<a href="../cowboy.stop_listener">cowboy:stop_listener(3)</a>,
-<a href="../ranch">ranch(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy:start_tls - Listen for connections using TLS</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">start_tls</span></span>(<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch:ref</span></span>(), + <span style="color: #009900">TransportOpts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch_ssl:opts</span></span>(), + <span style="color: #009900">ProtocolOpts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">opts</span></span>()) + <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">ListenerPid</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">pid</span></span>()} + | {<span style="color: #FF6600">error</span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Start listening for connections over a secure TLS channel.</p></div> +<div class="paragraph"><p>Both HTTP/1.1 and HTTP/2 are supported on this listener. +The ALPN TLS extension must be used to initiate an HTTP/2 +connection.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name +</dt> +<dd> +<p> +The listener name is used to refer to this listener in +future calls, for example when stopping it or when +updating the routes defined. +</p> +<div class="paragraph"><p>It can be any Erlang term. An atom is generally good enough, +for example <code>api</code>, <code>my_app_clear</code> or <code>my_app_tls</code>.</p></div> +</dd> +<dt class="hdlist1"> +TransportOpts +</dt> +<dd> +<p> +The transport options are where the TCP options, including +the listener’s port number, are defined. They also contain +the TLS options, like the server’s certificate. Transport options +are provided as a list of keys and values, for example +<code>[{port, 8443}, {certfile, "path/to/cert.pem"}]</code>. +</p> +<div class="paragraph"><p>The available options are documented in the +<a href="../ranch_ssl">ranch_ssl(3)</a> manual.</p></div> +</dd> +<dt class="hdlist1"> +ProtocolOpts +</dt> +<dd> +<p> +The protocol options are in a map containing all the options for +the different protocols that may be involved when connecting +to the listener, including HTTP/1.1 and HTTP/2. +</p> +<div class="paragraph"><p>The HTTP/1.1 options are documented in the +<a href="../cowboy_http">cowboy_http(3)</a> manual; +and the HTTP/2 options in +<a href="../cowboy_http2">cowboy_http2(3)</a>.</p></div> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An ok tuple is returned on success. It contains the pid of +the top-level supervisor for the listener.</p></div> +<div class="paragraph"><p>An error tuple is returned on error. The error reason may +be any Erlang term.</p></div> +<div class="paragraph"><p>A common error is <code>eaddrinuse</code>. It indicates that the port +configured for Cowboy is already in use.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: HTTP/2 support added. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: Function introduced. Replaces <code>cowboy:start_https/4</code>. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Start a listener</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">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">toppage_h</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_tls</span></span>(<span style="color: #FF6600">example</span>, [ + {<span style="color: #FF6600">port</span>, <span style="color: #993399">8443</span>}, + {<span style="color: #FF6600">cert</span>, <span style="color: #FF0000">"path/to/cert.pem"</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="listingblock"> +<div class="title">Start a listener on a random port</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">Name</span> <span style="color: #990000">=</span> <span style="color: #FF6600">example</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_tls</span></span>(<span style="color: #009900">Name</span>, [ + {<span style="color: #FF6600">cert</span>, <span style="color: #FF0000">"path/to/cert.pem"</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: #009900">Port</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_port</span></span>(<span style="color: #009900">Name</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy">cowboy(3)</a>, +<a href="../cowboy.start_clear">cowboy:start_clear(3)</a>, +<a href="../cowboy.stop_listener">cowboy:stop_listener(3)</a>, +<a href="../ranch">ranch(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy.stop_listener/index.html b/docs/en/cowboy/2.0/manual/cowboy.stop_listener/index.html index 512fc5fa..b3d736f9 100644 --- a/docs/en/cowboy/2.0/manual/cowboy.stop_listener/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy.stop_listener/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy:stop_listener(3)</title> @@ -67,87 +67,87 @@ <h1 class="lined-header"><span>cowboy:stop_listener(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy:stop_listener - Stop the given listener</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">stop_listener</span></span>(<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch:ref</span></span>())
- <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span> | {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">not_found</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Stop a previously started listener.</p></div>
-<div class="paragraph"><p>Alias of <a href="../ranch.stop_listener">ranch:stop_listener(3)</a>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name
-</dt>
-<dd>
-<p>
-The name of the listener to be stopped.
-</p>
-<div class="paragraph"><p>The name of the listener is the first argument given to the
-<a href="../cowboy.start_clear">cowboy:start_clear(3)</a>,
-<a href="../cowboy.start_tls">cowboy:start_tls(3)</a> or
-<a href="../ranch.start_listener">ranch:start_listener(3)</a> function.</p></div>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The atom <code>ok</code> is returned on success.</p></div>
-<div class="paragraph"><p>The <code>{error, not_found}</code> tuple is returned when the listener
-does not exist.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Stop a listener</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: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:stop_listener</span></span>(<span style="color: #FF6600">example</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy">cowboy(3)</a>,
-<a href="../cowboy.start_clear">cowboy:start_clear(3)</a>,
-<a href="../cowboy.start_tls">cowboy:start_tls(3)</a>,
-<a href="../ranch">ranch(3)</a>,
-<a href="../ranch.start_listener">ranch:start_listener(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy:stop_listener - Stop the given listener</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">stop_listener</span></span>(<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch:ref</span></span>()) + <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span> | {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">not_found</span>}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Stop a previously started listener.</p></div> +<div class="paragraph"><p>Alias of <a href="../ranch.stop_listener">ranch:stop_listener(3)</a>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name +</dt> +<dd> +<p> +The name of the listener to be stopped. +</p> +<div class="paragraph"><p>The name of the listener is the first argument given to the +<a href="../cowboy.start_clear">cowboy:start_clear(3)</a>, +<a href="../cowboy.start_tls">cowboy:start_tls(3)</a> or +<a href="../ranch.start_listener">ranch:start_listener(3)</a> function.</p></div> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The atom <code>ok</code> is returned on success.</p></div> +<div class="paragraph"><p>The <code>{error, not_found}</code> tuple is returned when the listener +does not exist.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Stop a listener</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: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:stop_listener</span></span>(<span style="color: #FF6600">example</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy">cowboy(3)</a>, +<a href="../cowboy.start_clear">cowboy:start_clear(3)</a>, +<a href="../cowboy.start_tls">cowboy:start_tls(3)</a>, +<a href="../ranch">ranch(3)</a>, +<a href="../ranch.start_listener">ranch:start_listener(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy/index.html b/docs/en/cowboy/2.0/manual/cowboy/index.html index 1a2a4d08..8f2bc031 100644 --- a/docs/en/cowboy/2.0/manual/cowboy/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy(3)</title> @@ -67,129 +67,129 @@ <h1 class="lined-header"><span>cowboy(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy - HTTP server</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The module <code>cowboy</code> provides convenience functions for
-manipulating Ranch listeners.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exports">Exports</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy.start_clear">cowboy:start_clear(3)</a> - Listen for connections using plain TCP
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy.start_tls">cowboy:start_tls(3)</a> - Listen for connections using TLS
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy.stop_listener">cowboy:stop_listener(3)</a> - Stop the given listener
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy.set_env">cowboy:set_env(3)</a> - Update a listener’s environment value
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_fields">fields()</h3>
-<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">fields</span></span>() <span style="color: #990000">::</span> [<span style="color: #009900">Name</span>
- | {<span style="color: #009900">Name</span>, <span style="color: #009900">Constraints</span>}
- | {<span style="color: #009900">Name</span>, <span style="color: #009900">Constraints</span>, <span style="color: #009900">Default</span>}]
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()
-<span style="color: #009900">Constraints</span> <span style="color: #990000">::</span> <span style="color: #009900">Constraint</span> | [<span style="color: #009900">Constraint</span>]
-<span style="color: #009900">Constraint</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_constraints:constraint</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Fields description for match operations.</p></div>
-<div class="paragraph"><p>This type is used in <a href="../cowboy_router">cowboy_router(3)</a>
-for matching bindings and in the match functions found in
-<a href="../cowboy_req">cowboy_req(3)</a>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_http_headers">http_headers()</h3>
-<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">http_headers</span></span>() <span style="color: #990000">::</span> #{<span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>HTTP headers.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_http_status">http_status()</h3>
-<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">http_status</span></span>() <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>() | <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>HTTP response status.</p></div>
-<div class="paragraph"><p>A binary status can be used to set a reason phrase. Note
-however that HTTP/2 only sends the status code and drops
-the reason phrase entirely.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_http_version">http_version()</h3>
-<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">http_version</span></span>() <span style="color: #990000">::</span> <span style="color: #FF6600">'HTTP/2'</span> | <span style="color: #FF6600">'HTTP/1.1'</span> | <span style="color: #FF6600">'HTTP/1.0'</span></tt></pre></div></div>
-<div class="paragraph"><p>HTTP version.</p></div>
-<div class="paragraph"><p>Note that semantically, HTTP/1.1 and HTTP/2 are equivalent.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_opts">opts()</h3>
-<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">opts</span></span>() <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">map</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Options for the HTTP/1.1, HTTP/2 and Websocket protocols.</p></div>
-<div class="paragraph"><p>The protocol options are in a map containing all the options for
-the different protocols that may be involved when connecting
-to the listener, including HTTP/1.1 and HTTP/2.</p></div>
-<div class="paragraph"><p>The HTTP/1.1 options are documented in the
-<a href="../cowboy_http">cowboy_http(3)</a> manual
-and the HTTP/2 options in
-<a href="../cowboy_http2">cowboy_http2(3)</a>.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="..">cowboy(7)</a>,
-<a href="../ranch">ranch(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy - HTTP server</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The module <code>cowboy</code> provides convenience functions for +manipulating Ranch listeners.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="../cowboy.start_clear">cowboy:start_clear(3)</a> - Listen for connections using plain TCP +</p> +</li> +<li> +<p> +<a href="../cowboy.start_tls">cowboy:start_tls(3)</a> - Listen for connections using TLS +</p> +</li> +<li> +<p> +<a href="../cowboy.stop_listener">cowboy:stop_listener(3)</a> - Stop the given listener +</p> +</li> +<li> +<p> +<a href="../cowboy.set_env">cowboy:set_env(3)</a> - Update a listener’s environment value +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_fields">fields()</h3> +<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">fields</span></span>() <span style="color: #990000">::</span> [<span style="color: #009900">Name</span> + | {<span style="color: #009900">Name</span>, <span style="color: #009900">Constraints</span>} + | {<span style="color: #009900">Name</span>, <span style="color: #009900">Constraints</span>, <span style="color: #009900">Default</span>}] + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>() +<span style="color: #009900">Constraints</span> <span style="color: #990000">::</span> <span style="color: #009900">Constraint</span> | [<span style="color: #009900">Constraint</span>] +<span style="color: #009900">Constraint</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_constraints:constraint</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Fields description for match operations.</p></div> +<div class="paragraph"><p>This type is used in <a href="../cowboy_router">cowboy_router(3)</a> +for matching bindings and in the match functions found in +<a href="../cowboy_req">cowboy_req(3)</a>.</p></div> +</div> +<div class="sect2"> +<h3 id="_http_headers">http_headers()</h3> +<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">http_headers</span></span>() <span style="color: #990000">::</span> #{<span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>HTTP headers.</p></div> +</div> +<div class="sect2"> +<h3 id="_http_status">http_status()</h3> +<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">http_status</span></span>() <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>() | <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>HTTP response status.</p></div> +<div class="paragraph"><p>A binary status can be used to set a reason phrase. Note +however that HTTP/2 only sends the status code and drops +the reason phrase entirely.</p></div> +</div> +<div class="sect2"> +<h3 id="_http_version">http_version()</h3> +<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">http_version</span></span>() <span style="color: #990000">::</span> <span style="color: #FF6600">'HTTP/2'</span> | <span style="color: #FF6600">'HTTP/1.1'</span> | <span style="color: #FF6600">'HTTP/1.0'</span></tt></pre></div></div> +<div class="paragraph"><p>HTTP version.</p></div> +<div class="paragraph"><p>Note that semantically, HTTP/1.1 and HTTP/2 are equivalent.</p></div> +</div> +<div class="sect2"> +<h3 id="_opts">opts()</h3> +<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">opts</span></span>() <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">map</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Options for the HTTP/1.1, HTTP/2 and Websocket protocols.</p></div> +<div class="paragraph"><p>The protocol options are in a map containing all the options for +the different protocols that may be involved when connecting +to the listener, including HTTP/1.1 and HTTP/2.</p></div> +<div class="paragraph"><p>The HTTP/1.1 options are documented in the +<a href="../cowboy_http">cowboy_http(3)</a> manual +and the HTTP/2 options in +<a href="../cowboy_http2">cowboy_http2(3)</a>.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="..">cowboy(7)</a>, +<a href="../ranch">ranch(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_app/index.html b/docs/en/cowboy/2.0/manual/cowboy_app/index.html index 689915a5..0c92cf86 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_app/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_app/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy(7)</title> @@ -67,166 +67,171 @@ <h1 class="lined-header"><span>cowboy(7)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy - Small, fast, modern HTTP server for Erlang/OTP</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy is an HTTP server for Erlang/OTP with support for the
-HTTP/1.1, HTTP/2 and Websocket protocols.</p></div>
-<div class="paragraph"><p>Cowboy aims to provide a complete HTTP stack. This includes
-the implementation of the HTTP RFCs but also any directly
-related standards, like Websocket or Server-Sent Events.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_modules">Modules</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Functions:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy">cowboy(3)</a> - Listener management
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req">cowboy_req(3)</a> - Request and response
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_router">cowboy_router(3)</a> - Router
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Protocols:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy_http">cowboy_http(3)</a> - HTTP/1.1
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_http2">cowboy_http2(3)</a> - HTTP/2
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_websocket">cowboy_websocket(3)</a> - Websocket
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Handlers:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy_static">cowboy_static(3)</a> - Static file handler
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Behaviors:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy_handler">cowboy_handler(3)</a> - Plain HTTP handlers
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_loop">cowboy_loop(3)</a> - Loop handlers
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_middleware">cowboy_middleware(3)</a> - Middlewares
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_rest">cowboy_rest(3)</a> - REST handlers
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_stream">cowboy_stream(3)</a> - Stream handlers
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_websocket">cowboy_websocket(3)</a> - Websocket handlers
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Middlewares:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy_router">cowboy_router(3)</a> - Router middleware
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_handler">cowboy_handler(3)</a> - Handler middleware
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_dependencies">Dependencies</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../ranch">ranch(7)</a> - Socket acceptor pool for TCP protocols
-</p>
-</li>
-<li>
-<p>
-<a href="../cowlib">cowlib(7)</a> - Support library for manipulating Web protocols
-</p>
-</li>
-<li>
-<p>
-ssl - Secure communication over sockets
-</p>
-</li>
-<li>
-<p>
-crypto - Crypto functions
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>All these applications must be started before the <code>cowboy</code>
-application. To start Cowboy and all dependencies at once:</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: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">application:ensure_all_started</span></span>(<span style="color: #FF6600">cowboy</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_environment">Environment</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>cowboy</code> application does not define any application
-environment configuration parameters.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../ranch">ranch(7)</a>,
-<a href="../cowlib">cowlib(7)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy - Small, fast, modern HTTP server for Erlang/OTP</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy is an HTTP server for Erlang/OTP with support for the +HTTP/1.1, HTTP/2 and Websocket protocols.</p></div> +<div class="paragraph"><p>Cowboy aims to provide a complete HTTP stack. This includes +the implementation of the HTTP RFCs but also any directly +related standards, like Websocket or Server-Sent Events.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_modules">Modules</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Functions:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="../cowboy">cowboy(3)</a> - Listener management +</p> +</li> +<li> +<p> +<a href="../cowboy_req">cowboy_req(3)</a> - Request and response +</p> +</li> +<li> +<p> +<a href="../cowboy_router">cowboy_router(3)</a> - Router +</p> +</li> +<li> +<p> +<a href="../cowboy_constraints">cowboy_constraints(3)</a> - Constraints +</p> +</li> +</ul></div> +<div class="paragraph"><p>Protocols:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="../cowboy_http">cowboy_http(3)</a> - HTTP/1.1 +</p> +</li> +<li> +<p> +<a href="../cowboy_http2">cowboy_http2(3)</a> - HTTP/2 +</p> +</li> +<li> +<p> +<a href="../cowboy_websocket">cowboy_websocket(3)</a> - Websocket +</p> +</li> +</ul></div> +<div class="paragraph"><p>Handlers:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="../cowboy_static">cowboy_static(3)</a> - Static file handler +</p> +</li> +</ul></div> +<div class="paragraph"><p>Behaviors:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="../cowboy_handler">cowboy_handler(3)</a> - Plain HTTP handlers +</p> +</li> +<li> +<p> +<a href="../cowboy_loop">cowboy_loop(3)</a> - Loop handlers +</p> +</li> +<li> +<p> +<a href="../cowboy_middleware">cowboy_middleware(3)</a> - Middlewares +</p> +</li> +<li> +<p> +<a href="../cowboy_rest">cowboy_rest(3)</a> - REST handlers +</p> +</li> +<li> +<p> +<a href="../cowboy_stream">cowboy_stream(3)</a> - Stream handlers +</p> +</li> +<li> +<p> +<a href="../cowboy_websocket">cowboy_websocket(3)</a> - Websocket handlers +</p> +</li> +</ul></div> +<div class="paragraph"><p>Middlewares:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="../cowboy_router">cowboy_router(3)</a> - Router middleware +</p> +</li> +<li> +<p> +<a href="../cowboy_handler">cowboy_handler(3)</a> - Handler middleware +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_dependencies">Dependencies</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="../ranch">ranch(7)</a> - Socket acceptor pool for TCP protocols +</p> +</li> +<li> +<p> +<a href="../cowlib">cowlib(7)</a> - Support library for manipulating Web protocols +</p> +</li> +<li> +<p> +ssl - Secure communication over sockets +</p> +</li> +<li> +<p> +crypto - Crypto functions +</p> +</li> +</ul></div> +<div class="paragraph"><p>All these applications must be started before the <code>cowboy</code> +application. To start Cowboy and all dependencies at once:</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: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">application:ensure_all_started</span></span>(<span style="color: #FF6600">cowboy</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_environment">Environment</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>cowboy</code> application does not define any application +environment configuration parameters.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../ranch">ranch(7)</a>, +<a href="../cowlib">cowlib(7)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_constraints.int/index.html b/docs/en/cowboy/2.0/manual/cowboy_constraints.int/index.html new file mode 100644 index 00000000..70c8969e --- /dev/null +++ b/docs/en/cowboy/2.0/manual/cowboy_constraints.int/index.html @@ -0,0 +1,225 @@ +<!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.26" /> + + <title>Nine Nines: cowboy_constraints:int(3)</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=1" 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>cowboy_constraints:int(3)</span></h1> + +<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_constraints:int - Integer constraint</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Constraint functions implement a number of different operations.</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">int</span></span>(<span style="color: #FF6600">forward</span>, <span style="color: #009900">Bin</span>) <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Int</span>} | {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">not_an_integer</span>} + +<span style="color: #009900">Bin</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() +<span style="color: #009900">Int</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">integer</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Validate and convert the text representation of an integer.</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">int</span></span>(<span style="color: #FF6600">reverse</span>, <span style="color: #009900">Int</span>) <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Bin</span>} | {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">not_an_integer</span>}</tt></pre></div></div> +<div class="paragraph"><p>Convert an integer back to its text representation.</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">int</span></span>(<span style="color: #FF6600">format_error</span>, <span style="color: #009900">Error</span>) <span style="color: #990000">-></span> <span style="color: #009900">HumanReadable</span> + +<span style="color: #009900">Error</span> <span style="color: #990000">::</span> {<span style="color: #FF6600">not_an_integer</span>, <span style="color: #009900">Bin</span> | <span style="color: #009900">Int</span>} +<span style="color: #009900">HumanReadable</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iolist</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Generate a human-readable error message.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Arguments vary depending on the operation. Constraint +functions always take the operation type as first argument, +and the value as second argument.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The return value varies depending on the operation.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Interface modified to allow for a variety of operations. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Constraint introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This function is not meant to be called directly.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_constraints">cowboy_constraints(3)</a>, +<a href="../cowboy_constraints.nonempty">cowboy_constraints:nonempty(3)</a>, +<a href="../cowboy_router">cowboy_router(3)</a>, +<a href="../cowboy_req.match_cookies">cowboy_req:match_cookies(3)</a>, +<a href="../cowboy_req.match_qs">cowboy_req:match_qs(3)</a></p></div> +</div> +</div> + + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Cowboy + 2.0 + Function Reference + +</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/2.0/manual">2.0</a></li> + + <li><a href="/docs/en/cowboy/1.0/manual">1.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="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/cowboy/2.0/manual/cowboy_constraints.nonempty/index.html b/docs/en/cowboy/2.0/manual/cowboy_constraints.nonempty/index.html new file mode 100644 index 00000000..b833f1b1 --- /dev/null +++ b/docs/en/cowboy/2.0/manual/cowboy_constraints.nonempty/index.html @@ -0,0 +1,224 @@ +<!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.26" /> + + <title>Nine Nines: cowboy_constraints:nonempty(3)</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=1" 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>cowboy_constraints:nonempty(3)</span></h1> + +<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_constraints:nonempty - Non-empty constraint</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Constraint functions implement a number of different operations.</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">nonempty</span></span>(<span style="color: #FF6600">forward</span> | <span style="color: #FF6600">reverse</span>, <span style="color: #990000"><<>></span>) <span style="color: #990000">-></span> {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">empty</span>}</tt></pre></div></div> +<div class="paragraph"><p>Reject empty values.</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">nonempty</span></span>(<span style="color: #FF6600">forward</span> | <span style="color: #FF6600">reverse</span>, <span style="color: #009900">Bin</span>) <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Bin</span>} + +<span style="color: #009900">Bin</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Accept any other binary values.</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">nonempty</span></span>(<span style="color: #FF6600">format_error</span>, <span style="color: #009900">Error</span>) <span style="color: #990000">-></span> <span style="color: #009900">HumanReadable</span> + +<span style="color: #009900">Error</span> <span style="color: #990000">::</span> {<span style="color: #FF6600">empty</span>, <span style="color: #009900">Bin</span>} +<span style="color: #009900">HumanReadable</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iolist</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Generate a human-readable error message.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Arguments vary depending on the operation. Constraint +functions always take the operation type as first argument, +and the value as second argument.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The return value varies depending on the operation.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Interface modified to allow for a variety of operations. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Constraint introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This function is not meant to be called directly.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_constraints">cowboy_constraints(3)</a>, +<a href="../cowboy_constraints.int">cowboy_constraints:int(3)</a>, +<a href="../cowboy_router">cowboy_router(3)</a>, +<a href="../cowboy_req.match_cookies">cowboy_req:match_cookies(3)</a>, +<a href="../cowboy_req.match_qs">cowboy_req:match_qs(3)</a></p></div> +</div> +</div> + + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Cowboy + 2.0 + Function Reference + +</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/2.0/manual">2.0</a></li> + + <li><a href="/docs/en/cowboy/1.0/manual">1.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="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/cowboy/2.0/manual/cowboy_constraints/index.html b/docs/en/cowboy/2.0/manual/cowboy_constraints/index.html new file mode 100644 index 00000000..ae5340eb --- /dev/null +++ b/docs/en/cowboy/2.0/manual/cowboy_constraints/index.html @@ -0,0 +1,217 @@ +<!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.26" /> + + <title>Nine Nines: cowboy_constraints(3)</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=1" 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>cowboy_constraints(3)</span></h1> + +<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_constraints - Constraints</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The module <code>cowboy_constraints</code> defines the built-in +constraints in Cowboy and provides an interface for +manipulating these constraints.</p></div> +<div class="paragraph"><p>Constraints are functions that define what type of +input is allowed. They are used throughout Cowboy, +from the router to query strings to cookies.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Built-in constraints:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="../cowboy_constraints.int">cowboy_constraints:int(3)</a> - Integer constraint +</p> +</li> +<li> +<p> +<a href="../cowboy_constraints.nonempty">cowboy_constraints:nonempty(3)</a> - Non-empty constraint +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_constraint">constraint()</h3> +<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">constraint</span></span>() <span style="color: #990000">::</span> <span style="color: #FF6600">int</span> | <span style="color: #FF6600">nonempty</span> | <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>A constraint function.</p></div> +<div class="paragraph"><p>The atom constraints are built-in, see the corresponding +function in the exports list above.</p></div> +</div> +<div class="sect2"> +<h3 id="_reason">reason()</h3> +<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">reason</span></span>() <span style="color: #990000">::</span> {<span style="font-weight: bold"><span style="color: #000000">constraint</span></span>(), <span style="color: #009900">Reason</span>, <span style="color: #009900">Value</span>} + +<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() +<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Reason for the constraint failure.</p></div> +<div class="paragraph"><p>It includes the constraint function in question, +a machine-readable error reason and the value that +made the constraint fail.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="..">cowboy(7)</a>, +<a href="../cowboy">cowboy(3)</a>, +<a href="../cowboy_router">cowboy_router(3)</a>, +<a href="../cowboy_req.match_cookies">cowboy_req:match_cookies(3)</a>, +<a href="../cowboy_req.match_qs">cowboy_req:match_qs(3)</a></p></div> +</div> +</div> + + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Cowboy + 2.0 + Function Reference + +</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/2.0/manual">2.0</a></li> + + <li><a href="/docs/en/cowboy/1.0/manual">1.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="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/cowboy/2.0/manual/cowboy_handler.terminate/index.html b/docs/en/cowboy/2.0/manual/cowboy_handler.terminate/index.html index ab3155ae..c12945ed 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_handler.terminate/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_handler.terminate/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_handler:terminate(3)</title> @@ -67,109 +67,109 @@ <h1 class="lined-header"><span>cowboy_handler:terminate(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_handler:terminate - Terminate the handler</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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: #000080">undefined</span>, <span style="color: #009900">State</span>, <span style="color: #009900">Handler</span>) <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span>
-
-<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
-<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()
-<span style="color: #009900">State</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
-<span style="color: #009900">Handler</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">module</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Call the optional terminate callback if it is defined.</p></div>
-<div class="paragraph"><p>Make sure to use this function at the end of the execution
-of modules that implement custom handler behaviors.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Reason
-</dt>
-<dd>
-<p>
-Reason for termination.
-</p>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-<div class="paragraph"><p>It is possible to pass <code>undefined</code> if the handler has no concept
-of requests/responses and discarded the Req object before calling
-this function.</p></div>
-</dd>
-<dt class="hdlist1">
-State
-</dt>
-<dd>
-<p>
-Handler state.
-</p>
-</dd>
-<dt class="hdlist1">
-Handler
-</dt>
-<dd>
-<p>
-Handler module.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The atom <code>ok</code> is always returned. It can be safely ignored.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Terminate a handler normally</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="font-weight: bold"><span style="color: #000000">cowboy_handler:terminate</span></span>(<span style="font-weight: bold"><span style="color: #000080">normal</span></span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #009900">Handler</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_handler">cowboy_handler(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_handler:terminate - Terminate the handler</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">PartialReq</span>, <span style="color: #009900">State</span>, <span style="color: #009900">Handler</span>) <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span> + +<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() +<span style="color: #009900">PartialReq</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">map</span></span>() +<span style="color: #009900">State</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() +<span style="color: #009900">Handler</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">module</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Call the optional terminate callback if it is defined.</p></div> +<div class="paragraph"><p>Make sure to use this function at the end of the execution +of modules that implement custom handler behaviors.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Reason +</dt> +<dd> +<p> +Reason for termination. +</p> +</dd> +<dt class="hdlist1"> +PartialReq +</dt> +<dd> +<p> +The Req object. +</p> +<div class="paragraph"><p>It is possible to remove fields from the Req object to save memory +when the handler has no concept of requests/responses. The only +requirement is that a map is provided.</p></div> +</dd> +<dt class="hdlist1"> +State +</dt> +<dd> +<p> +Handler state. +</p> +</dd> +<dt class="hdlist1"> +Handler +</dt> +<dd> +<p> +Handler module. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The atom <code>ok</code> is always returned. It can be safely ignored.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Terminate a handler normally</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="font-weight: bold"><span style="color: #000000">cowboy_handler:terminate</span></span>(<span style="font-weight: bold"><span style="color: #000080">normal</span></span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #009900">Handler</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_handler">cowboy_handler(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_handler/index.html b/docs/en/cowboy/2.0/manual/cowboy_handler/index.html index 0c34537c..6c60377a 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_handler/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_handler/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_handler(3)</title> @@ -67,96 +67,96 @@ <h1 class="lined-header"><span>cowboy_handler(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_handler - Plain HTTP handlers</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>cowboy_handler</code> middleware executes the handler selected
-by the router or any other preceding middleware.</p></div>
-<div class="paragraph"><p>This middleware takes the handler module and initial state
-from the <code>handler</code> and <code>handler_opts</code> environment values,
-respectively. On completion, it adds a <code>result</code> value to
-the middleware environment, containing the return value
-of the <code>terminate/3</code> callback (if defined) and <code>ok</code> otherwise.</p></div>
-<div class="paragraph"><p>This module also defines a callback interface for handling
-HTTP requests.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_callbacks">Callbacks</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Plain HTTP handlers implement the following interface:</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">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="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="font-style: italic"><span style="color: #9A1900">%% optional</span></span>
-
-<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()
-<span style="color: #009900">State</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
-<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">normal</span></span>
- | {<span style="color: #FF6600">crash</span>, <span style="color: #FF6600">error</span> | <span style="font-weight: bold"><span style="color: #000080">exit</span></span> | <span style="font-weight: bold"><span style="color: #000080">throw</span></span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>These two callbacks are common to all handlers.</p></div>
-<div class="paragraph"><p>Plain HTTP handlers do all their work in the <code>init/2</code>
-callback. Returning <code>ok</code> terminates the handler. If no
-response is sent, Cowboy will send a <code>204 No Content</code>.</p></div>
-<div class="paragraph"><p>The optional <code>terminate/3</code> callback will ultimately be called
-with the reason for the termination of the handler.
-Cowboy will terminate the process right after this. There
-is no need to perform any cleanup in this callback.</p></div>
-<div class="paragraph"><p>The following terminate reasons are defined for plain HTTP
-handlers:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-normal
-</dt>
-<dd>
-<p>
- The connection was closed normally.
-</p>
-</dd>
-<dt class="hdlist1">
-{crash, Class, Reason}
-</dt>
-<dd>
-<p>
- A crash occurred in the handler. <code>Class</code> and <code>Reason</code> can be
- used to obtain more information about the crash. The function
- <code>erlang:get_stacktrace/0</code> can also be called to obtain the
- stacktrace of the process when the crash occurred.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exports">Exports</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The following function should be called by modules implementing
-custom handlers to execute the optional terminate callback:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy_handler.terminate">cowboy_handler:terminate(3)</a> - Terminate the handler
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="..">cowboy(7)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_handler - Plain HTTP handlers</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>cowboy_handler</code> middleware executes the handler selected +by the router or any other preceding middleware.</p></div> +<div class="paragraph"><p>This middleware takes the handler module and initial state +from the <code>handler</code> and <code>handler_opts</code> environment values, +respectively. On completion, it adds a <code>result</code> value to +the middleware environment, containing the return value +of the <code>terminate/3</code> callback (if defined) and <code>ok</code> otherwise.</p></div> +<div class="paragraph"><p>This module also defines a callback interface for handling +HTTP requests.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_callbacks">Callbacks</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Plain HTTP handlers implement the following interface:</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">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="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="font-style: italic"><span style="color: #9A1900">%% optional</span></span> + +<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>() +<span style="color: #009900">State</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() +<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">normal</span></span> + | {<span style="color: #FF6600">crash</span>, <span style="color: #FF6600">error</span> | <span style="font-weight: bold"><span style="color: #000080">exit</span></span> | <span style="font-weight: bold"><span style="color: #000080">throw</span></span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>These two callbacks are common to all handlers.</p></div> +<div class="paragraph"><p>Plain HTTP handlers do all their work in the <code>init/2</code> +callback. Returning <code>ok</code> terminates the handler. If no +response is sent, Cowboy will send a <code>204 No Content</code>.</p></div> +<div class="paragraph"><p>The optional <code>terminate/3</code> callback will ultimately be called +with the reason for the termination of the handler. +Cowboy will terminate the process right after this. There +is no need to perform any cleanup in this callback.</p></div> +<div class="paragraph"><p>The following terminate reasons are defined for plain HTTP +handlers:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +normal +</dt> +<dd> +<p> + The connection was closed normally. +</p> +</dd> +<dt class="hdlist1"> +{crash, Class, Reason} +</dt> +<dd> +<p> + A crash occurred in the handler. <code>Class</code> and <code>Reason</code> can be + used to obtain more information about the crash. The function + <code>erlang:get_stacktrace/0</code> can also be called to obtain the + stacktrace of the process when the crash occurred. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The following function should be called by modules implementing +custom handlers to execute the optional terminate callback:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="../cowboy_handler.terminate">cowboy_handler:terminate(3)</a> - Terminate the handler +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="..">cowboy(7)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_http/index.html b/docs/en/cowboy/2.0/manual/cowboy_http/index.html index 5fd3cecf..414880a1 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_http/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_http/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_http(3)</title> @@ -67,240 +67,240 @@ <h1 class="lined-header"><span>cowboy_http(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_http - HTTP/1.1</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The module <code>cowboy_http</code> implements HTTP/1.1 and HTTP/1.0
-as a Ranch protocol.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_options">Options</h2>
-<div class="sectionbody">
-<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">opts</span></span>() <span style="color: #990000">::</span> #{
- <span style="color: #0000FF">connection_type</span> <span style="color: #990000">=></span> <span style="color: #FF6600">worker</span> | <span style="color: #FF6600">supervisor</span>,
- <span style="color: #0000FF">env</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_middleware:env</span></span>(),
- <span style="color: #0000FF">idle_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(),
- <span style="color: #0000FF">inactivity_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(),
- <span style="color: #0000FF">max_empty_lines</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(),
- <span style="color: #0000FF">max_header_name_length</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(),
- <span style="color: #0000FF">max_header_value_length</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(),
- <span style="color: #0000FF">max_headers</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(),
- <span style="color: #0000FF">max_keepalive</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(),
- <span style="color: #0000FF">max_method_length</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(),
- <span style="color: #0000FF">max_request_line_length</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(),
- <span style="color: #0000FF">middlewares</span> <span style="color: #990000">=></span> [<span style="font-weight: bold"><span style="color: #000000">module</span></span>()],
- <span style="color: #0000FF">request_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(),
- <span style="color: #000080">shutdown</span><span style="color: #009900">_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(),
- <span style="color: #0000FF">stream_handlers</span> <span style="color: #990000">=></span> [<span style="font-weight: bold"><span style="color: #000000">module</span></span>()]
-}</tt></pre></div></div>
-<div class="paragraph"><p>Configuration for the HTTP/1.1 protocol.</p></div>
-<div class="paragraph"><p>This configuration is passed to Cowboy when starting listeners
-using <code>cowboy:start_clear/3</code> or <code>cowboy:start_tls/3</code> functions.</p></div>
-<div class="paragraph"><p>It can be updated without restarting listeners using the
-Ranch functions <code>ranch:get_protocol_options/1</code> and
-<code>ranch:set_protocol_options/2</code>.</p></div>
-<div class="paragraph"><p>The default value is given next to the option name:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-connection_type (supervisor)
-</dt>
-<dd>
-<p>
- Whether the connection process also acts as a supervisor.
-</p>
-</dd>
-<dt class="hdlist1">
-env (#{})
-</dt>
-<dd>
-<p>
- Middleware environment.
-</p>
-</dd>
-<dt class="hdlist1">
-idle_timeout (60000)
-</dt>
-<dd>
-<p>
- Time in ms with no data received before Cowboy closes the connection.
-</p>
-</dd>
-<dt class="hdlist1">
-inactivity_timeout (300000)
-</dt>
-<dd>
-<p>
- Time in ms with nothing received at all before Cowboy closes the connection.
-</p>
-</dd>
-<dt class="hdlist1">
-max_empty_lines (5)
-</dt>
-<dd>
-<p>
- Maximum number of empty lines before a request.
-</p>
-</dd>
-<dt class="hdlist1">
-max_header_name_length (64)
-</dt>
-<dd>
-<p>
- Maximum length of header names.
-</p>
-</dd>
-<dt class="hdlist1">
-max_header_value_length (4096)
-</dt>
-<dd>
-<p>
- Maximum length of header values.
-</p>
-</dd>
-<dt class="hdlist1">
-max_headers (100)
-</dt>
-<dd>
-<p>
- Maximum number of headers allowed per request.
-</p>
-</dd>
-<dt class="hdlist1">
-max_keepalive (100)
-</dt>
-<dd>
-<p>
- Maximum number of requests allowed per connection.
-</p>
-</dd>
-<dt class="hdlist1">
-max_method_length (32)
-</dt>
-<dd>
-<p>
- Maximum length of the method.
-</p>
-</dd>
-<dt class="hdlist1">
-max_request_line_length (8000)
-</dt>
-<dd>
-<p>
- Maximum length of the request line.
-</p>
-</dd>
-<dt class="hdlist1">
-middlewares ([cowboy_router, cowboy_handler])
-</dt>
-<dd>
-<p>
- Middlewares to run for every request.
-</p>
-</dd>
-<dt class="hdlist1">
-request_timeout (5000)
-</dt>
-<dd>
-<p>
- Time in ms with no requests before Cowboy closes the connection.
-</p>
-</dd>
-<dt class="hdlist1">
-shutdown_timeout (5000)
-</dt>
-<dd>
-<p>
- Time in ms Cowboy will wait for child processes to shut down before killing them.
-</p>
-</dd>
-<dt class="hdlist1">
-stream_handlers ([cowboy_stream_h])
-</dt>
-<dd>
-<p>
- Ordered list of stream handlers that will handle all stream events.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: The <code>timeout</code> option was renamed <code>request_timeout</code>.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: The <code>idle_timeout</code>, <code>inactivity_timeout</code> and <code>shutdown_timeout</code> options were added.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: The <code>max_method_length</code> option was added.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: The <code>max_request_line_length</code> default was increased from 4096 to 8000.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: The <code>connection_type</code> option was added.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: The <code>env</code> option is now a map instead of a proplist.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: The <code>stream_handlers</code> option was added.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: The <code>compress</code> option was removed in favor of the <code>cowboy_compress_h</code> stream handler.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: Options are now a map instead of a proplist.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: Protocol introduced. Replaces <code>cowboy_protocol</code>.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="..">cowboy(7)</a>,
-<a href="../cowboy_http2">cowboy_http2(3)</a>,
-<a href="../cowboy_websocket">cowboy_websocket(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_http - HTTP/1.1</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The module <code>cowboy_http</code> implements HTTP/1.1 and HTTP/1.0 +as a Ranch protocol.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_options">Options</h2> +<div class="sectionbody"> +<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">opts</span></span>() <span style="color: #990000">::</span> #{ + <span style="color: #0000FF">connection_type</span> <span style="color: #990000">=></span> <span style="color: #FF6600">worker</span> | <span style="color: #FF6600">supervisor</span>, + <span style="color: #0000FF">env</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_middleware:env</span></span>(), + <span style="color: #0000FF">idle_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(), + <span style="color: #0000FF">inactivity_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(), + <span style="color: #0000FF">max_empty_lines</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), + <span style="color: #0000FF">max_header_name_length</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), + <span style="color: #0000FF">max_header_value_length</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), + <span style="color: #0000FF">max_headers</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), + <span style="color: #0000FF">max_keepalive</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), + <span style="color: #0000FF">max_method_length</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), + <span style="color: #0000FF">max_request_line_length</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), + <span style="color: #0000FF">middlewares</span> <span style="color: #990000">=></span> [<span style="font-weight: bold"><span style="color: #000000">module</span></span>()], + <span style="color: #0000FF">request_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(), + <span style="color: #000080">shutdown</span><span style="color: #009900">_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(), + <span style="color: #0000FF">stream_handlers</span> <span style="color: #990000">=></span> [<span style="font-weight: bold"><span style="color: #000000">module</span></span>()] +}</tt></pre></div></div> +<div class="paragraph"><p>Configuration for the HTTP/1.1 protocol.</p></div> +<div class="paragraph"><p>This configuration is passed to Cowboy when starting listeners +using <code>cowboy:start_clear/3</code> or <code>cowboy:start_tls/3</code> functions.</p></div> +<div class="paragraph"><p>It can be updated without restarting listeners using the +Ranch functions <code>ranch:get_protocol_options/1</code> and +<code>ranch:set_protocol_options/2</code>.</p></div> +<div class="paragraph"><p>The default value is given next to the option name:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +connection_type (supervisor) +</dt> +<dd> +<p> + Whether the connection process also acts as a supervisor. +</p> +</dd> +<dt class="hdlist1"> +env (#{}) +</dt> +<dd> +<p> + Middleware environment. +</p> +</dd> +<dt class="hdlist1"> +idle_timeout (60000) +</dt> +<dd> +<p> + Time in ms with no data received before Cowboy closes the connection. +</p> +</dd> +<dt class="hdlist1"> +inactivity_timeout (300000) +</dt> +<dd> +<p> + Time in ms with nothing received at all before Cowboy closes the connection. +</p> +</dd> +<dt class="hdlist1"> +max_empty_lines (5) +</dt> +<dd> +<p> + Maximum number of empty lines before a request. +</p> +</dd> +<dt class="hdlist1"> +max_header_name_length (64) +</dt> +<dd> +<p> + Maximum length of header names. +</p> +</dd> +<dt class="hdlist1"> +max_header_value_length (4096) +</dt> +<dd> +<p> + Maximum length of header values. +</p> +</dd> +<dt class="hdlist1"> +max_headers (100) +</dt> +<dd> +<p> + Maximum number of headers allowed per request. +</p> +</dd> +<dt class="hdlist1"> +max_keepalive (100) +</dt> +<dd> +<p> + Maximum number of requests allowed per connection. +</p> +</dd> +<dt class="hdlist1"> +max_method_length (32) +</dt> +<dd> +<p> + Maximum length of the method. +</p> +</dd> +<dt class="hdlist1"> +max_request_line_length (8000) +</dt> +<dd> +<p> + Maximum length of the request line. +</p> +</dd> +<dt class="hdlist1"> +middlewares ([cowboy_router, cowboy_handler]) +</dt> +<dd> +<p> + Middlewares to run for every request. +</p> +</dd> +<dt class="hdlist1"> +request_timeout (5000) +</dt> +<dd> +<p> + Time in ms with no requests before Cowboy closes the connection. +</p> +</dd> +<dt class="hdlist1"> +shutdown_timeout (5000) +</dt> +<dd> +<p> + Time in ms Cowboy will wait for child processes to shut down before killing them. +</p> +</dd> +<dt class="hdlist1"> +stream_handlers ([cowboy_stream_h]) +</dt> +<dd> +<p> + Ordered list of stream handlers that will handle all stream events. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: The <code>timeout</code> option was renamed <code>request_timeout</code>. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: The <code>idle_timeout</code>, <code>inactivity_timeout</code> and <code>shutdown_timeout</code> options were added. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: The <code>max_method_length</code> option was added. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: The <code>max_request_line_length</code> default was increased from 4096 to 8000. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: The <code>connection_type</code> option was added. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: The <code>env</code> option is now a map instead of a proplist. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: The <code>stream_handlers</code> option was added. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: The <code>compress</code> option was removed in favor of the <code>cowboy_compress_h</code> stream handler. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: Options are now a map instead of a proplist. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: Protocol introduced. Replaces <code>cowboy_protocol</code>. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="..">cowboy(7)</a>, +<a href="../cowboy_http2">cowboy_http2(3)</a>, +<a href="../cowboy_websocket">cowboy_websocket(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_http2/index.html b/docs/en/cowboy/2.0/manual/cowboy_http2/index.html index ae0b7103..cac697fa 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_http2/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_http2/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_http2(3)</title> @@ -67,123 +67,123 @@ <h1 class="lined-header"><span>cowboy_http2(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_http2 - HTTP/2</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The module <code>cowboy_http2</code> implements HTTP/2
-as a Ranch protocol.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_options">Options</h2>
-<div class="sectionbody">
-<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">opts</span></span>() <span style="color: #990000">::</span> #{
- <span style="color: #0000FF">connection_type</span> <span style="color: #990000">=></span> <span style="color: #FF6600">worker</span> | <span style="color: #FF6600">supervisor</span>,
- <span style="color: #0000FF">env</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_middleware:env</span></span>(),
- <span style="color: #0000FF">inactivity_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(),
- <span style="color: #0000FF">middlewares</span> <span style="color: #990000">=></span> [<span style="font-weight: bold"><span style="color: #000000">module</span></span>()],
- <span style="color: #0000FF">preface_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(),
- <span style="color: #000080">shutdown</span><span style="color: #009900">_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(),
- <span style="color: #0000FF">stream_handlers</span> <span style="color: #990000">=></span> [<span style="font-weight: bold"><span style="color: #000000">module</span></span>()]
-}</tt></pre></div></div>
-<div class="paragraph"><p>Configuration for the HTTP/2 protocol.</p></div>
-<div class="paragraph"><p>This configuration is passed to Cowboy when starting listeners
-using <code>cowboy:start_clear/3</code> or <code>cowboy:start_tls/3</code> functions.</p></div>
-<div class="paragraph"><p>It can be updated without restarting listeners using the
-Ranch functions <code>ranch:get_protocol_options/1</code> and
-<code>ranch:set_protocol_options/2</code>.</p></div>
-<div class="paragraph"><p>The default value is given next to the option name:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-connection_type (supervisor)
-</dt>
-<dd>
-<p>
- Whether the connection process also acts as a supervisor.
-</p>
-</dd>
-<dt class="hdlist1">
-env (#{})
-</dt>
-<dd>
-<p>
- Middleware environment.
-</p>
-</dd>
-<dt class="hdlist1">
-inactivity_timeout (300000)
-</dt>
-<dd>
-<p>
- Time in ms with nothing received at all before Cowboy closes the connection.
-</p>
-</dd>
-<dt class="hdlist1">
-middlewares ([cowboy_router, cowboy_handler])
-</dt>
-<dd>
-<p>
- Middlewares to run for every request.
-</p>
-</dd>
-<dt class="hdlist1">
-preface_timeout (5000)
-</dt>
-<dd>
-<p>
- Time in ms Cowboy is willing to wait for the connection preface.
-</p>
-</dd>
-<dt class="hdlist1">
-shutdown_timeout (5000)
-</dt>
-<dd>
-<p>
- Time in ms Cowboy will wait for child processes to shut down before killing them.
-</p>
-</dd>
-<dt class="hdlist1">
-stream_handlers ([cowboy_stream_h])
-</dt>
-<dd>
-<p>
- Ordered list of stream handlers that will handle all stream events.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Protocol introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="..">cowboy(7)</a>,
-<a href="../cowboy_http">cowboy_http(3)</a>,
-<a href="../cowboy_websocket">cowboy_websocket(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_http2 - HTTP/2</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The module <code>cowboy_http2</code> implements HTTP/2 +as a Ranch protocol.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_options">Options</h2> +<div class="sectionbody"> +<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">opts</span></span>() <span style="color: #990000">::</span> #{ + <span style="color: #0000FF">connection_type</span> <span style="color: #990000">=></span> <span style="color: #FF6600">worker</span> | <span style="color: #FF6600">supervisor</span>, + <span style="color: #0000FF">env</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_middleware:env</span></span>(), + <span style="color: #0000FF">inactivity_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(), + <span style="color: #0000FF">middlewares</span> <span style="color: #990000">=></span> [<span style="font-weight: bold"><span style="color: #000000">module</span></span>()], + <span style="color: #0000FF">preface_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(), + <span style="color: #000080">shutdown</span><span style="color: #009900">_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(), + <span style="color: #0000FF">stream_handlers</span> <span style="color: #990000">=></span> [<span style="font-weight: bold"><span style="color: #000000">module</span></span>()] +}</tt></pre></div></div> +<div class="paragraph"><p>Configuration for the HTTP/2 protocol.</p></div> +<div class="paragraph"><p>This configuration is passed to Cowboy when starting listeners +using <code>cowboy:start_clear/3</code> or <code>cowboy:start_tls/3</code> functions.</p></div> +<div class="paragraph"><p>It can be updated without restarting listeners using the +Ranch functions <code>ranch:get_protocol_options/1</code> and +<code>ranch:set_protocol_options/2</code>.</p></div> +<div class="paragraph"><p>The default value is given next to the option name:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +connection_type (supervisor) +</dt> +<dd> +<p> + Whether the connection process also acts as a supervisor. +</p> +</dd> +<dt class="hdlist1"> +env (#{}) +</dt> +<dd> +<p> + Middleware environment. +</p> +</dd> +<dt class="hdlist1"> +inactivity_timeout (300000) +</dt> +<dd> +<p> + Time in ms with nothing received at all before Cowboy closes the connection. +</p> +</dd> +<dt class="hdlist1"> +middlewares ([cowboy_router, cowboy_handler]) +</dt> +<dd> +<p> + Middlewares to run for every request. +</p> +</dd> +<dt class="hdlist1"> +preface_timeout (5000) +</dt> +<dd> +<p> + Time in ms Cowboy is willing to wait for the connection preface. +</p> +</dd> +<dt class="hdlist1"> +shutdown_timeout (5000) +</dt> +<dd> +<p> + Time in ms Cowboy will wait for child processes to shut down before killing them. +</p> +</dd> +<dt class="hdlist1"> +stream_handlers ([cowboy_stream_h]) +</dt> +<dd> +<p> + Ordered list of stream handlers that will handle all stream events. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Protocol introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="..">cowboy(7)</a>, +<a href="../cowboy_http">cowboy_http(3)</a>, +<a href="../cowboy_websocket">cowboy_websocket(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_loop/index.html b/docs/en/cowboy/2.0/manual/cowboy_loop/index.html index b547cfe7..a1f0a289 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_loop/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_loop/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_loop(3)</title> @@ -67,120 +67,120 @@ <h1 class="lined-header"><span>cowboy_loop(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_loop - Loop handlers</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The module <code>cowboy_loop</code> defines a callback interface for
-long running HTTP connections.</p></div>
-<div class="paragraph"><p>You should switch to this behavior for long polling,
-server-sent events and similar long-running requests.</p></div>
-<div class="paragraph"><p>There are generally two usage patterns:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Loop until receiving a specific message, then send
- a response and stop execution (for example long polling);
-</p>
-</li>
-<li>
-<p>
-Or initiate a response in <code>init/2</code> and stream the
- body in <code>info/3</code> as necessary (for example server-sent events).
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_callbacks">Callbacks</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Loop handlers implement the following interface:</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">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: #FF6600">cowboy_loop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}
-
-<span style="font-weight: bold"><span style="color: #000000">info</span></span>(<span style="color: #009900">Info</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">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</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">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="font-style: italic"><span style="color: #9A1900">%% optional</span></span>
-
-<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()
-<span style="color: #009900">State</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
-<span style="color: #009900">Info</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
-<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="color: #FF6600">stop</span>
- | {<span style="color: #FF6600">crash</span>, <span style="color: #FF6600">error</span> | <span style="font-weight: bold"><span style="color: #000080">exit</span></span> | <span style="font-weight: bold"><span style="color: #000080">throw</span></span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>The <code>init/2</code> callback is common to all handlers. To switch
-to the loop behavior, it must return <code>cowboy_loop</code> as the
-first element of the tuple.</p></div>
-<div class="paragraph"><p>The <code>info/3</code> callback will be called for every Erlang message
-received. It may choose to continue the receive loop or stop
-it.</p></div>
-<div class="paragraph"><p>The optional <code>terminate/3</code> callback will ultimately be called
-with the reason for the termination of the handler.
-Cowboy will terminate the process right after this. There
-is no need to perform any cleanup in this callback.</p></div>
-<div class="paragraph"><p>The following terminate reasons are defined for loop handlers:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-stop
-</dt>
-<dd>
-<p>
- The handler requested to close the connection by returning
- a <code>stop</code> tuple.
-</p>
-</dd>
-<dt class="hdlist1">
-{crash, Class, Reason}
-</dt>
-<dd>
-<p>
- A crash occurred in the handler. <code>Class</code> and <code>Reason</code> can be
- used to obtain more information about the crash. The function
- <code>erlang:get_stacktrace/0</code> can also be called to obtain the
- stacktrace of the process when the crash occurred.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Loop handlers no longer need to handle overflow/timeouts.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Behavior introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="..">cowboy(7)</a>,
-<a href="../cowboy_handler">cowboy_handler(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_loop - Loop handlers</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The module <code>cowboy_loop</code> defines a callback interface for +long running HTTP connections.</p></div> +<div class="paragraph"><p>You should switch to this behavior for long polling, +server-sent events and similar long-running requests.</p></div> +<div class="paragraph"><p>There are generally two usage patterns:</p></div> +<div class="ulist"><ul> +<li> +<p> +Loop until receiving a specific message, then send + a response and stop execution (for example long polling); +</p> +</li> +<li> +<p> +Or initiate a response in <code>init/2</code> and stream the + body in <code>info/3</code> as necessary (for example server-sent events). +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_callbacks">Callbacks</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Loop handlers implement the following interface:</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">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: #FF6600">cowboy_loop</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>} + +<span style="font-weight: bold"><span style="color: #000000">info</span></span>(<span style="color: #009900">Info</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">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</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">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="font-style: italic"><span style="color: #9A1900">%% optional</span></span> + +<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>() +<span style="color: #009900">State</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() +<span style="color: #009900">Info</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() +<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="color: #FF6600">stop</span> + | {<span style="color: #FF6600">crash</span>, <span style="color: #FF6600">error</span> | <span style="font-weight: bold"><span style="color: #000080">exit</span></span> | <span style="font-weight: bold"><span style="color: #000080">throw</span></span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>The <code>init/2</code> callback is common to all handlers. To switch +to the loop behavior, it must return <code>cowboy_loop</code> as the +first element of the tuple.</p></div> +<div class="paragraph"><p>The <code>info/3</code> callback will be called for every Erlang message +received. It may choose to continue the receive loop or stop +it.</p></div> +<div class="paragraph"><p>The optional <code>terminate/3</code> callback will ultimately be called +with the reason for the termination of the handler. +Cowboy will terminate the process right after this. There +is no need to perform any cleanup in this callback.</p></div> +<div class="paragraph"><p>The following terminate reasons are defined for loop handlers:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +stop +</dt> +<dd> +<p> + The handler requested to close the connection by returning + a <code>stop</code> tuple. +</p> +</dd> +<dt class="hdlist1"> +{crash, Class, Reason} +</dt> +<dd> +<p> + A crash occurred in the handler. <code>Class</code> and <code>Reason</code> can be + used to obtain more information about the crash. The function + <code>erlang:get_stacktrace/0</code> can also be called to obtain the + stacktrace of the process when the crash occurred. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Loop handlers no longer need to handle overflow/timeouts. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Behavior introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="..">cowboy(7)</a>, +<a href="../cowboy_handler">cowboy_handler(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_middleware/index.html b/docs/en/cowboy/2.0/manual/cowboy_middleware/index.html index 2324a945..dbf5b412 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_middleware/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_middleware/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_middleware(3)</title> @@ -67,115 +67,115 @@ <h1 class="lined-header"><span>cowboy_middleware(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_middleware - Middlewares</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The module <code>cowboy_middleware</code> defines a callback interface for
-Cowboy middlewares.</p></div>
-<div class="paragraph"><p>Middlewares process the request sequentially in the order they
-are configured.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_callbacks">Callbacks</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Middlewares implement the following interface:</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">execute</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">Env</span>)
- <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">Env</span>}
- | {<span style="color: #FF6600">suspend</span>, <span style="font-weight: bold"><span style="color: #000000">module</span></span>(), <span style="font-weight: bold"><span style="color: #000080">atom</span></span>(), [<span style="font-weight: bold"><span style="color: #000000">any</span></span>()]}
- | {<span style="color: #FF6600">stop</span>, <span style="color: #009900">Req</span>}
-
-<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()
-<span style="color: #009900">Env</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_middleware:env</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>The <code>execute/2</code> is the only callback that needs to be
-implemented. It must execute the middleware and return
-with instructions for Cowboy.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ok
-</dt>
-<dd>
-<p>
-Cowboy should continue processing the request using the
-returned Req object and environment.
-</p>
-</dd>
-<dt class="hdlist1">
-suspend
-</dt>
-<dd>
-<p>
-Cowboy will hibernate the process. When resuming, Cowboy
-will apply the returned module, function and arguments.
-</p>
-</dd>
-<dt class="hdlist1">
-stop
-</dt>
-<dd>
-<p>
-Cowboy will stop middleware execution. No other middleware
-will be executed. This effectively ends the processing of
-the request.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_env">env()</h3>
-<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">env</span></span>() <span style="color: #990000">::</span> #{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>() <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>Middleware environment.</p></div>
-<div class="paragraph"><p>A new environment is created for every request. The initial
-environment contained the user configured environment values
-(like <code>dispatch</code> for example) plus the <code>listener</code> value which
-contains the name of the listener for this connection.</p></div>
-<div class="paragraph"><p>Middlewares may modify the environment as necessary.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: The <code>env</code> type is now a map instead of a proplist.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Behavior introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="..">cowboy(7)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_middleware - Middlewares</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The module <code>cowboy_middleware</code> defines a callback interface for +Cowboy middlewares.</p></div> +<div class="paragraph"><p>Middlewares process the request sequentially in the order they +are configured.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_callbacks">Callbacks</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Middlewares implement the following interface:</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">execute</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">Env</span>) + <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">Env</span>} + | {<span style="color: #FF6600">suspend</span>, <span style="font-weight: bold"><span style="color: #000000">module</span></span>(), <span style="font-weight: bold"><span style="color: #000080">atom</span></span>(), [<span style="font-weight: bold"><span style="color: #000000">any</span></span>()]} + | {<span style="color: #FF6600">stop</span>, <span style="color: #009900">Req</span>} + +<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>() +<span style="color: #009900">Env</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_middleware:env</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>The <code>execute/2</code> is the only callback that needs to be +implemented. It must execute the middleware and return +with instructions for Cowboy.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +ok +</dt> +<dd> +<p> +Cowboy should continue processing the request using the +returned Req object and environment. +</p> +</dd> +<dt class="hdlist1"> +suspend +</dt> +<dd> +<p> +Cowboy will hibernate the process. When resuming, Cowboy +will apply the returned module, function and arguments. +</p> +</dd> +<dt class="hdlist1"> +stop +</dt> +<dd> +<p> +Cowboy will stop middleware execution. No other middleware +will be executed. This effectively ends the processing of +the request. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_env">env()</h3> +<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">env</span></span>() <span style="color: #990000">::</span> #{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>() <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Middleware environment.</p></div> +<div class="paragraph"><p>A new environment is created for every request. The initial +environment contained the user configured environment values +(like <code>dispatch</code> for example) plus the <code>listener</code> value which +contains the name of the listener for this connection.</p></div> +<div class="paragraph"><p>Middlewares may modify the environment as necessary.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: The <code>env</code> type is now a map instead of a proplist. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Behavior introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="..">cowboy(7)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.binding/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.binding/index.html index 27bf3764..94112847 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.binding/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.binding/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:binding(3)</title> @@ -67,116 +67,116 @@ <h1 class="lined-header"><span>cowboy_req:binding(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:binding - Access a value bound from the route</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">binding</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">binding</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #000080">undefined</span>)
-<span style="font-weight: bold"><span style="color: #000000">binding</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">Default</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() | <span style="color: #009900">Default</span>
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()
-<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return the value for the given binding.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name
-</dt>
-<dd>
-<p>
-Desired binding name as an atom.
-</p>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-<dt class="hdlist1">
-Default
-</dt>
-<dd>
-<p>
-Default value returned when the binding is missing.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>By default the value is a case sensitive binary string, however
-constraints may change the type of this value (for example
-automatically converting numbers to integer).</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the value is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get the username from the path</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="font-style: italic"><span style="color: #9A1900">%% Route is "/users/:user"</span></span>
-<span style="color: #009900">Username</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:binding</span></span>(<span style="color: #FF6600">user</span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Get the branch name, with a default</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="font-style: italic"><span style="color: #9A1900">%% Route is "/log[/:branch]"</span></span>
-<span style="color: #009900">Branch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:binding</span></span>(<span style="color: #FF6600">branch</span>, <span style="color: #009900">Req</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"master"</span><span style="color: #990000">>></span>)</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a>,
-<a href="../cowboy_req.host_info">cowboy_req:host_info(3)</a>,
-<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a>,
-<a href="../cowboy_router">cowboy_router(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:binding - Access a value bound from the route</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">binding</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">binding</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #000080">undefined</span>) +<span style="font-weight: bold"><span style="color: #000000">binding</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">Default</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() | <span style="color: #009900">Default</span> + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>() +<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return the value for the given binding.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name +</dt> +<dd> +<p> +Desired binding name as an atom. +</p> +</dd> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +<dt class="hdlist1"> +Default +</dt> +<dd> +<p> +Default value returned when the binding is missing. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>By default the value is a case sensitive binary string, however +constraints may change the type of this value (for example +automatically converting numbers to integer).</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the value is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get the username from the path</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="font-style: italic"><span style="color: #9A1900">%% Route is "/users/:user"</span></span> +<span style="color: #009900">Username</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:binding</span></span>(<span style="color: #FF6600">user</span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Get the branch name, with a default</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="font-style: italic"><span style="color: #9A1900">%% Route is "/log[/:branch]"</span></span> +<span style="color: #009900">Branch</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:binding</span></span>(<span style="color: #FF6600">branch</span>, <span style="color: #009900">Req</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"master"</span><span style="color: #990000">>></span>)</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a>, +<a href="../cowboy_req.host_info">cowboy_req:host_info(3)</a>, +<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a>, +<a href="../cowboy_router">cowboy_router(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.bindings/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.bindings/index.html index 256f0491..29c994f8 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.bindings/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.bindings/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:bindings(3)</title> @@ -67,86 +67,86 @@ <h1 class="lined-header"><span>cowboy_req:bindings(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:bindings - Access all values bound from the route</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">bindings</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:bindings</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return a map containing all bindings.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>By default values are case sensitive binary strings, however
-constraints may change the type of this value (for example
-automatically converting numbers to integer).</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the values are returned, they are no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get all bindings</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">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>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.binding">cowboy_req:binding(3)</a>,
-<a href="../cowboy_req.host_info">cowboy_req:host_info(3)</a>,
-<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a>,
-<a href="../cowboy_router">cowboy_router(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:bindings - Access all values bound from the route</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">bindings</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:bindings</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return a map containing all bindings.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>By default values are case sensitive binary strings, however +constraints may change the type of this value (for example +automatically converting numbers to integer).</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the values are returned, they are no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get all bindings</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">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> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.binding">cowboy_req:binding(3)</a>, +<a href="../cowboy_req.host_info">cowboy_req:host_info(3)</a>, +<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a>, +<a href="../cowboy_router">cowboy_router(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.body_length/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.body_length/index.html index bd772ac0..3a360235 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.body_length/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.body_length/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:body_length(3)</title> @@ -67,89 +67,89 @@ <h1 class="lined-header"><span>cowboy_req:body_length(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:body_length - Body length</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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_length</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #000080">undefined</span> | <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return the length of the request body.</p></div>
-<div class="paragraph"><p>The length is not always known before reading the body.
-In those cases Cowboy will return <code>undefined</code>. The body
-length is available after the body has been fully read.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The length of the request body, or <code>undefined</code> if it is
-not known.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the length is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get the body length</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">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>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.has_body">cowboy_req:has_body(3)</a>,
-<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>,
-<a href="../cowboy_req.read_urlencoded_body">cowboy_req:read_urlencoded_body(3)</a>,
-<a href="../cowboy_req.read_part">cowboy_req:read_part(3)</a>,
-<a href="../cowboy_req.read_part_body">cowboy_req:read_part_body(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:body_length - Body length</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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_length</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #000080">undefined</span> | <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return the length of the request body.</p></div> +<div class="paragraph"><p>The length is not always known before reading the body. +In those cases Cowboy will return <code>undefined</code>. The body +length is available after the body has been fully read.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The length of the request body, or <code>undefined</code> if it is +not known.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the length is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get the body length</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">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> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.has_body">cowboy_req:has_body(3)</a>, +<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>, +<a href="../cowboy_req.read_urlencoded_body">cowboy_req:read_urlencoded_body(3)</a>, +<a href="../cowboy_req.read_part">cowboy_req:read_part(3)</a>, +<a href="../cowboy_req.read_part_body">cowboy_req:read_part_body(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.delete_resp_header/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.delete_resp_header/index.html index 1418de55..09e4f66f 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.delete_resp_header/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.delete_resp_header/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:delete_resp_header(3)</title> @@ -67,95 +67,95 @@ <h1 class="lined-header"><span>cowboy_req:delete_resp_header(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:delete_resp_header - Delete a response header</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">delete_resp_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Req</span>
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span></tt></pre></div></div>
-<div class="paragraph"><p>Delete the given response header.</p></div>
-<div class="paragraph"><p>The header name must be given as a lowercase binary string.
-While header names are case insensitive, Cowboy requires them
-to be given as lowercase to function properly.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name
-</dt>
-<dd>
-<p>
-Header name as a lowercase binary string.
-</p>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A new Req object is returned.</p></div>
-<div class="paragraph"><p>The returned Req object must be used from that point onward,
-otherwise the header will still be sent in the response.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Remove the content-type header from the response</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:delete_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>),</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>,
-<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>,
-<a href="../cowboy_req.has_resp_header">cowboy_req:has_resp_header(3)</a>,
-<a href="../cowboy_req.resp_header">cowboy_req:resp_header(3)</a>,
-<a href="../cowboy_req.resp_headers">cowboy_req:resp_headers(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:delete_resp_header - Delete a response header</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">delete_resp_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Req</span> + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span></tt></pre></div></div> +<div class="paragraph"><p>Delete the given response header.</p></div> +<div class="paragraph"><p>The header name must be given as a lowercase binary string. +While header names are case insensitive, Cowboy requires them +to be given as lowercase to function properly.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name +</dt> +<dd> +<p> +Header name as a lowercase binary string. +</p> +</dd> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A new Req object is returned.</p></div> +<div class="paragraph"><p>The returned Req object must be used from that point onward, +otherwise the header will still be sent in the response.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Remove the content-type header from the response</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:delete_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>),</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>, +<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>, +<a href="../cowboy_req.has_resp_header">cowboy_req:has_resp_header(3)</a>, +<a href="../cowboy_req.resp_header">cowboy_req:resp_header(3)</a>, +<a href="../cowboy_req.resp_headers">cowboy_req:resp_headers(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.has_body/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.has_body/index.html index 3935024c..3a8d97ce 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.has_body/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.has_body/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:has_body(3)</title> @@ -67,80 +67,80 @@ <h1 class="lined-header"><span>cowboy_req:has_body(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:has_body - Is there a request body?</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">has_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return whether the request has a body.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A boolean indicating whether the request has a body.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Ensure the request has a body</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: #000080">true</span> <span style="color: #990000">=</span> <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>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.body_length">cowboy_req:body_length(3)</a>,
-<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>,
-<a href="../cowboy_req.read_urlencoded_body">cowboy_req:read_urlencoded_body(3)</a>,
-<a href="../cowboy_req.read_part">cowboy_req:read_part(3)</a>,
-<a href="../cowboy_req.read_part_body">cowboy_req:read_part_body(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:has_body - Is there a request body?</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">has_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return whether the request has a body.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A boolean indicating whether the request has a body.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Ensure the request has a body</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: #000080">true</span> <span style="color: #990000">=</span> <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> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.body_length">cowboy_req:body_length(3)</a>, +<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>, +<a href="../cowboy_req.read_urlencoded_body">cowboy_req:read_urlencoded_body(3)</a>, +<a href="../cowboy_req.read_part">cowboy_req:read_part(3)</a>, +<a href="../cowboy_req.read_part_body">cowboy_req:read_part_body(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.has_resp_body/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.has_resp_body/index.html index 7391037c..9d6b92fe 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.has_resp_body/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.has_resp_body/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:has_resp_body(3)</title> @@ -67,82 +67,82 @@ <h1 class="lined-header"><span>cowboy_req:has_resp_body(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:has_resp_body - Is there a response body?</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">has_resp_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return whether a response body has been set.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A boolean indicating whether a response body has been set.</p></div>
-<div class="paragraph"><p>This function will return <code>false</code> when an empty response
-body has been set.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Check whether a body has been set</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: #000080">false</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:has_resp_body</span></span>(<span style="color: #009900">Req0</span>),
-<span style="color: #009900">Req1</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_body</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"Hello!"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>),
-<span style="color: #000080">true</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:has_resp_body</span></span>(<span style="color: #009900">Req1</span>),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_body</span></span>(<span style="color: #990000"><<>></span>, <span style="color: #009900">Req1</span>),
-<span style="color: #000080">false</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:has_resp_body</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.set_resp_body">cowboy_req:set_resp_body(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:has_resp_body - Is there a response body?</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">has_resp_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return whether a response body has been set.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A boolean indicating whether a response body has been set.</p></div> +<div class="paragraph"><p>This function will return <code>false</code> when an empty response +body has been set.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Check whether a body has been set</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: #000080">false</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:has_resp_body</span></span>(<span style="color: #009900">Req0</span>), +<span style="color: #009900">Req1</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_body</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"Hello!"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>), +<span style="color: #000080">true</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:has_resp_body</span></span>(<span style="color: #009900">Req1</span>), +<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_body</span></span>(<span style="color: #990000"><<>></span>, <span style="color: #009900">Req1</span>), +<span style="color: #000080">false</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:has_resp_body</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.set_resp_body">cowboy_req:set_resp_body(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.has_resp_header/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.has_resp_header/index.html index 4fabcde4..1fc629eb 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.has_resp_header/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.has_resp_header/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:has_resp_header(3)</title> @@ -67,95 +67,95 @@ <h1 class="lined-header"><span>cowboy_req:has_resp_header(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:has_resp_header - Is the given response header set?</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">has_resp_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether the given response header has been set.</p></div>
-<div class="paragraph"><p>The header name must be given as a lowercase binary string.
-While header names are case insensitive, Cowboy requires them
-to be given as lowercase to function properly.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name
-</dt>
-<dd>
-<p>
-Header name as a lowercase binary string.
-</p>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A boolean indicating whether the given response header has been set.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Check whether the content-type header has been set</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: #000080">false</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:has_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>),
-<span style="color: #009900">Req</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">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"text/html"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>),
-<span style="color: #000080">true</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:has_resp_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>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>,
-<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>,
-<a href="../cowboy_req.resp_header">cowboy_req:resp_header(3)</a>,
-<a href="../cowboy_req.resp_headers">cowboy_req:resp_headers(3)</a>,
-<a href="../cowboy_req.delete_resp_header">cowboy_req:delete_resp_header(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:has_resp_header - Is the given response header set?</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">has_resp_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span></tt></pre></div></div> +<div class="paragraph"><p>Return whether the given response header has been set.</p></div> +<div class="paragraph"><p>The header name must be given as a lowercase binary string. +While header names are case insensitive, Cowboy requires them +to be given as lowercase to function properly.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name +</dt> +<dd> +<p> +Header name as a lowercase binary string. +</p> +</dd> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A boolean indicating whether the given response header has been set.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Check whether the content-type header has been set</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: #000080">false</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:has_resp_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>), +<span style="color: #009900">Req</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">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"text/html"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req0</span>), +<span style="color: #000080">true</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:has_resp_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> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>, +<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>, +<a href="../cowboy_req.resp_header">cowboy_req:resp_header(3)</a>, +<a href="../cowboy_req.resp_headers">cowboy_req:resp_headers(3)</a>, +<a href="../cowboy_req.delete_resp_header">cowboy_req:delete_resp_header(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.header/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.header/index.html index 5a508ba4..4680b487 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.header/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.header/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:header(3)</title> @@ -67,122 +67,122 @@ <h1 class="lined-header"><span>cowboy_req:header(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:header - HTTP header</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #000080">undefined</span>)
-<span style="font-weight: bold"><span style="color: #000000">header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">Default</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #009900">Default</span>
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span>
-<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return the value for the given HTTP header.</p></div>
-<div class="paragraph"><p>The header name must be given as a lowercase binary string.
-While header names are case insensitive, Cowboy requires them
-to be given as lowercase to function properly.</p></div>
-<div class="paragraph"><p>Headers can also be obtained using pattern matching:</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">Name</span> <span style="color: #990000">:=</span> <span style="color: #009900">Value</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>Note that this snippet will crash if the header is missing.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name
-</dt>
-<dd>
-<p>
-Desired HTTP header name as a lowercase binary string.
-</p>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-<dt class="hdlist1">
-Default
-</dt>
-<dd>
-<p>
-Default value returned when the header is missing.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The header value is returned as a binary string. When the
-header is missing, the default argument is returned.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the header value is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get the accept header</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">Accept</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">"accept"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Get the content-length header with a default value</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">Length</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-length"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"0"</span><span style="color: #990000">>></span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.headers">cowboy_req:headers(3)</a>,
-<a href="../cowboy_req.parse_header">cowboy_req:parse_header(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:header - HTTP header</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #000080">undefined</span>) +<span style="font-weight: bold"><span style="color: #000000">header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">Default</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #009900">Default</span> + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span> +<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return the value for the given HTTP header.</p></div> +<div class="paragraph"><p>The header name must be given as a lowercase binary string. +While header names are case insensitive, Cowboy requires them +to be given as lowercase to function properly.</p></div> +<div class="paragraph"><p>Headers can also be obtained using pattern matching:</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">Name</span> <span style="color: #990000">:=</span> <span style="color: #009900">Value</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>Note that this snippet will crash if the header is missing.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name +</dt> +<dd> +<p> +Desired HTTP header name as a lowercase binary string. +</p> +</dd> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +<dt class="hdlist1"> +Default +</dt> +<dd> +<p> +Default value returned when the header is missing. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The header value is returned as a binary string. When the +header is missing, the default argument is returned.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the header value is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get the accept header</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">Accept</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">"accept"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Get the content-length header with a default value</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">Length</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-length"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"0"</span><span style="color: #990000">>></span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.headers">cowboy_req:headers(3)</a>, +<a href="../cowboy_req.parse_header">cowboy_req:parse_header(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.headers/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.headers/index.html index 61d71c81..28fc85cf 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.headers/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.headers/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:headers(3)</title> @@ -67,90 +67,90 @@ <h1 class="lined-header"><span>cowboy_req:headers(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:headers - HTTP headers</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">headers</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return all request headers.</p></div>
-<div class="paragraph"><p>Request headers can also be obtained using pattern matching:</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">Headers</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Headers are returned as a map with keys being lowercase
-binary strings, and values as binary strings.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the headers are returned, they are no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get all headers</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">Headers</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>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.header">cowboy_req:header(3)</a>,
-<a href="../cowboy_req.parse_header">cowboy_req:parse_header(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:headers - HTTP headers</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">headers</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return all request headers.</p></div> +<div class="paragraph"><p>Request headers can also be obtained using pattern matching:</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">Headers</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Headers are returned as a map with keys being lowercase +binary strings, and values as binary strings.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the headers are returned, they are no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get all headers</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">Headers</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> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.header">cowboy_req:header(3)</a>, +<a href="../cowboy_req.parse_header">cowboy_req:parse_header(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.host/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.host/index.html index cd6bc638..a5c28fc8 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.host/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.host/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:host(3)</title> @@ -67,91 +67,91 @@ <h1 class="lined-header"><span>cowboy_req:host(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:host - URI host name</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">host</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Host</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return the host name of the effective request URI.</p></div>
-<div class="paragraph"><p>The host name can also be obtained using pattern matching:</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">host</span> <span style="color: #990000">:=</span> <span style="color: #009900">Host</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The host name is returned as a lowercase binary string.
-It is case insensitive.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the host name is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get the effective request URI’s host name</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">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: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.binding">cowboy_req:binding(3)</a>,
-<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a>,
-<a href="../cowboy_req.host_info">cowboy_req:host_info(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:host - URI host name</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">host</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Host</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return the host name of the effective request URI.</p></div> +<div class="paragraph"><p>The host name can also be obtained using pattern matching:</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">host</span> <span style="color: #990000">:=</span> <span style="color: #009900">Host</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The host name is returned as a lowercase binary string. +It is case insensitive.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the host name is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get the effective request URI’s host name</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">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: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.binding">cowboy_req:binding(3)</a>, +<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a>, +<a href="../cowboy_req.host_info">cowboy_req:host_info(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.host_info/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.host_info/index.html index 14e065bc..a423256f 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.host_info/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.host_info/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:host_info(3)</title> @@ -67,87 +67,87 @@ <h1 class="lined-header"><span>cowboy_req:host_info(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:host_info - Access the route’s heading host segments</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">host_info</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:tokens</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return the tokens for the heading host segments.</p></div>
-<div class="paragraph"><p>This is the part of the host name that was matched using
-the <code>...</code> notation.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The tokens are returned as a list of case insensitive
-binary strings.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the tokens are returned, they are no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get the host_info tokens</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">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>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.binding">cowboy_req:binding(3)</a>,
-<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a>,
-<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a>,
-<a href="../cowboy_router">cowboy_router(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:host_info - Access the route’s heading host segments</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">host_info</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:tokens</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return the tokens for the heading host segments.</p></div> +<div class="paragraph"><p>This is the part of the host name that was matched using +the <code>...</code> notation.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The tokens are returned as a list of case insensitive +binary strings.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the tokens are returned, they are no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get the host_info tokens</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">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> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.binding">cowboy_req:binding(3)</a>, +<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a>, +<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a>, +<a href="../cowboy_router">cowboy_router(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.match_cookies/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.match_cookies/index.html index a1cf74a0..d07ea532 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.match_cookies/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.match_cookies/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:match_cookies(3)</title> @@ -67,123 +67,123 @@ <h1 class="lined-header"><span>cowboy_req:match_cookies(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:match_cookies - Match cookies against constraints</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">match_cookies</span></span>(<span style="color: #009900">Fields</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:fields</span></span>(), <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> #{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>() <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>Parse the cookies and match specific values against
-constraints.</p></div>
-<div class="paragraph"><p>Cowboy will only return the cookie values specified in the
-fields list, and ignore all others. Fields can be either
-the name of the cookie requested; the name along with a
-list of constraints; or the name, a list of constraints
-and a default value in case the cookie is missing.</p></div>
-<div class="paragraph"><p>This function will crash if the cookie is missing and no
-default value is provided. This function will also crash
-if a constraint fails.</p></div>
-<div class="paragraph"><p>The name of the cookie must be provided as an atom. The
-key of the returned map will be that atom. The value may
-be converted through the use of constraints, making this
-function able to extract, validate and convert values all
-in one step.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Fields
-</dt>
-<dd>
-<p>
-Cookies to retrieve.
-</p>
-<div class="paragraph"><p>See <a href="../cowboy">cowboy(3)</a> for a complete description.</p></div>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Desired values are returned as a map. The key is the atom
-that was given in the list of fields, and the value is the
-optionally converted value after applying constraints.</p></div>
-<div class="paragraph"><p>The map contains the same keys that were given in the fields.</p></div>
-<div class="paragraph"><p>An exception is triggered when the match fails.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Match fields</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="font-style: italic"><span style="color: #9A1900">%% ID and Lang are binaries.</span></span>
-#{<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_cookies</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="listingblock">
-<div class="title">Match fields and apply constraints</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="font-style: italic"><span style="color: #9A1900">%% ID is an integer and Lang a non-empty binary.</span></span>
-#{<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_cookies</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="listingblock">
-<div class="title">Match fields with default values</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: #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_cookies</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>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.parse_cookies">cowboy_req:parse_cookies(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:match_cookies - Match cookies against constraints</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">match_cookies</span></span>(<span style="color: #009900">Fields</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:fields</span></span>(), <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> #{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>() <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Parse the cookies and match specific values against +constraints.</p></div> +<div class="paragraph"><p>Cowboy will only return the cookie values specified in the +fields list, and ignore all others. Fields can be either +the name of the cookie requested; the name along with a +list of constraints; or the name, a list of constraints +and a default value in case the cookie is missing.</p></div> +<div class="paragraph"><p>This function will crash if the cookie is missing and no +default value is provided. This function will also crash +if a constraint fails.</p></div> +<div class="paragraph"><p>The name of the cookie must be provided as an atom. The +key of the returned map will be that atom. The value may +be converted through the use of constraints, making this +function able to extract, validate and convert values all +in one step.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Fields +</dt> +<dd> +<p> +Cookies to retrieve. +</p> +<div class="paragraph"><p>See <a href="../cowboy">cowboy(3)</a> for a complete description.</p></div> +</dd> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Desired values are returned as a map. The key is the atom +that was given in the list of fields, and the value is the +optionally converted value after applying constraints.</p></div> +<div class="paragraph"><p>The map contains the same keys that were given in the fields.</p></div> +<div class="paragraph"><p>An exception is triggered when the match fails.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Match fields</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="font-style: italic"><span style="color: #9A1900">%% ID and Lang are binaries.</span></span> +#{<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_cookies</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="listingblock"> +<div class="title">Match fields and apply constraints</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="font-style: italic"><span style="color: #9A1900">%% ID is an integer and Lang a non-empty binary.</span></span> +#{<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_cookies</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="listingblock"> +<div class="title">Match fields with default values</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: #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_cookies</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> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.parse_cookies">cowboy_req:parse_cookies(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.match_qs/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.match_qs/index.html index da342012..bfbc7496 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.match_qs/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.match_qs/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:match_qs(3)</title> @@ -67,123 +67,123 @@ <h1 class="lined-header"><span>cowboy_req:match_qs(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:match_qs - Match the query string against constraints</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">match_qs</span></span>(<span style="color: #009900">Fields</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:fields</span></span>(), <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> #{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>() <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>Parse the query string and match specific values against
-constraints.</p></div>
-<div class="paragraph"><p>Cowboy will only return the query string values specified
-in the fields list, and ignore all others. Fields can be
-either the key requested; the key along with a list of
-constraints; or the key, a list of constraints and a
-default value in case the key is missing.</p></div>
-<div class="paragraph"><p>This function will crash if the key is missing and no
-default value is provided. This function will also crash
-if a constraint fails.</p></div>
-<div class="paragraph"><p>The key must be provided as an atom. The key of the
-returned map will be that atom. The value may be converted
-through the use of constraints, making this function able
-to extract, validate and convert values all in one step.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Fields
-</dt>
-<dd>
-<p>
-Fields to retrieve from the query string.
-</p>
-<div class="paragraph"><p>See <a href="../cowboy">cowboy(3)</a> for a complete description.</p></div>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Desired values are returned as a map. The key is the atom
-that was given in the list of fields, and the value is the
-optionally converted value after applying constraints.</p></div>
-<div class="paragraph"><p>The map contains the same keys that were given in the fields.</p></div>
-<div class="paragraph"><p>An exception is triggered when the match fails.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Match fields</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="font-style: italic"><span style="color: #9A1900">%% ID and Lang are binaries.</span></span>
-#{<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="listingblock">
-<div class="title">Match fields and apply constraints</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="font-style: italic"><span style="color: #9A1900">%% ID is an integer and Lang a non-empty binary.</span></span>
-#{<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">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="listingblock">
-<div class="title">Match fields with default values</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: #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>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.qs">cowboy_req:qs(3)</a>,
-<a href="../cowboy_req.parse_qs">cowboy_req:parse_qs(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:match_qs - Match the query string against constraints</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">match_qs</span></span>(<span style="color: #009900">Fields</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:fields</span></span>(), <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> #{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>() <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Parse the query string and match specific values against +constraints.</p></div> +<div class="paragraph"><p>Cowboy will only return the query string values specified +in the fields list, and ignore all others. Fields can be +either the key requested; the key along with a list of +constraints; or the key, a list of constraints and a +default value in case the key is missing.</p></div> +<div class="paragraph"><p>This function will crash if the key is missing and no +default value is provided. This function will also crash +if a constraint fails.</p></div> +<div class="paragraph"><p>The key must be provided as an atom. The key of the +returned map will be that atom. The value may be converted +through the use of constraints, making this function able +to extract, validate and convert values all in one step.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Fields +</dt> +<dd> +<p> +Fields to retrieve from the query string. +</p> +<div class="paragraph"><p>See <a href="../cowboy">cowboy(3)</a> for a complete description.</p></div> +</dd> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Desired values are returned as a map. The key is the atom +that was given in the list of fields, and the value is the +optionally converted value after applying constraints.</p></div> +<div class="paragraph"><p>The map contains the same keys that were given in the fields.</p></div> +<div class="paragraph"><p>An exception is triggered when the match fails.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Match fields</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="font-style: italic"><span style="color: #9A1900">%% ID and Lang are binaries.</span></span> +#{<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="listingblock"> +<div class="title">Match fields and apply constraints</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="font-style: italic"><span style="color: #9A1900">%% ID is an integer and Lang a non-empty binary.</span></span> +#{<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">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="listingblock"> +<div class="title">Match fields with default values</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: #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> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.qs">cowboy_req:qs(3)</a>, +<a href="../cowboy_req.parse_qs">cowboy_req:parse_qs(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.method/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.method/index.html index da70b08c..1beab4a6 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.method/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.method/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:method(3)</title> @@ -67,100 +67,100 @@ <h1 class="lined-header"><span>cowboy_req:method(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:method - HTTP method</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">method</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Method</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return the request’s HTTP method.</p></div>
-<div class="paragraph"><p>The method can also be obtained using pattern matching:</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>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The request’s HTTP method is returned as a binary string.
-While methods are case sensitive, standard methods are
-always uppercase.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the method is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Ensure the request’s method is GET</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: #990000"><<</span><span style="color: #FF0000">"GET"</span><span style="color: #990000">>></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="listingblock">
-<div class="title">Allow methods from list</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="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">lists:member</span></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><span style="color: #FF0000">"GET"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"POST"</span><span style="color: #990000">>></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="font-weight: bold"><span style="color: #000000">handle</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>);
- <span style="color: #000080">false</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">method_not_allowed</span></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="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:method - HTTP method</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">method</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Method</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return the request’s HTTP method.</p></div> +<div class="paragraph"><p>The method can also be obtained using pattern matching:</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> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The request’s HTTP method is returned as a binary string. +While methods are case sensitive, standard methods are +always uppercase.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the method is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Ensure the request’s method is GET</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: #990000"><<</span><span style="color: #FF0000">"GET"</span><span style="color: #990000">>></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="listingblock"> +<div class="title">Allow methods from list</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="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">lists:member</span></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><span style="color: #FF0000">"GET"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"POST"</span><span style="color: #990000">>></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="font-weight: bold"><span style="color: #000000">handle</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>); + <span style="color: #000080">false</span> <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">method_not_allowed</span></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="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.parse_cookies/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.parse_cookies/index.html index d04e504d..f5949f9f 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.parse_cookies/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.parse_cookies/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:parse_cookies(3)</title> @@ -67,91 +67,91 @@ <h1 class="lined-header"><span>cowboy_req:parse_cookies(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:parse_cookies - Parse cookie headers</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">parse_cookies</span></span>(<span style="color: #009900">Req</span>) <span style="color: #990000">-></span> [{<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>}]
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
-<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div>
-<div class="paragraph"><p>Parse cookie headers.</p></div>
-<div class="paragraph"><p>Alias for <a href="../cowboy_req.parse_header">cowboy_req:parse_header(<a href="#cookie">[cookie]</a>, Req)</a>.</p></div>
-<div class="paragraph"><p>When the cookie header is missing, <code>[]</code> is returned.</p></div>
-<div class="paragraph"><p>While an empty cookie header is not valid, some clients do
-send it. Cowboy will in this case also return <code>[]</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The cookies are returned as a list of key/values. Keys and
-values are case sensitive binary strings.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the parsed header value is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced. Replaces <code>cookie/2,3</code> and <code>cookies/1</code>.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Look for a specific cookie</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">Cookies</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_cookies</span></span>(<span style="color: #009900">Req</span>),
-{<span style="color: #990000">_</span>, <span style="color: #009900">Token</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">lists:keyfind</span></span>(<span style="color: #FF6600">token</span>, <span style="color: #993399">1</span>, <span style="color: #009900">Cookies</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.parse_header">cowboy_req:parse_header(3)</a>,
-<a href="../cowboy_req.match_cookies">cowboy_req:match_cookies(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:parse_cookies - Parse cookie headers</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">parse_cookies</span></span>(<span style="color: #009900">Req</span>) <span style="color: #990000">-></span> [{<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>}] + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> +<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div> +<div class="paragraph"><p>Parse cookie headers.</p></div> +<div class="paragraph"><p>Alias for <a href="../cowboy_req.parse_header">cowboy_req:parse_header(<a href="#cookie">[cookie]</a>, Req)</a>.</p></div> +<div class="paragraph"><p>When the cookie header is missing, <code>[]</code> is returned.</p></div> +<div class="paragraph"><p>While an empty cookie header is not valid, some clients do +send it. Cowboy will in this case also return <code>[]</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The cookies are returned as a list of key/values. Keys and +values are case sensitive binary strings.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the parsed header value is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: Function introduced. Replaces <code>cookie/2,3</code> and <code>cookies/1</code>. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Look for a specific cookie</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">Cookies</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_cookies</span></span>(<span style="color: #009900">Req</span>), +{<span style="color: #990000">_</span>, <span style="color: #009900">Token</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">lists:keyfind</span></span>(<span style="color: #FF6600">token</span>, <span style="color: #993399">1</span>, <span style="color: #009900">Cookies</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.parse_header">cowboy_req:parse_header(3)</a>, +<a href="../cowboy_req.match_cookies">cowboy_req:match_cookies(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.parse_header/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.parse_header/index.html index aad1926f..7e22192a 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.parse_header/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.parse_header/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:parse_header(3)</title> @@ -67,283 +67,283 @@ <h1 class="lined-header"><span>cowboy_req:parse_header(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:parse_header - Parse the given HTTP header</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="color: #009900">ParsedValue</span> | <span style="color: #009900">Default</span>
-<span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">Default</span>) <span style="color: #990000">-></span> <span style="color: #009900">ParsedValue</span> | <span style="color: #009900">Default</span>
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()
-<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()
-<span style="color: #009900">ParsedValue</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Parse the given HTTP header.</p></div>
-<div class="paragraph"><p>The header name must be given as a lowercase binary string.
-While header names are case insensitive, Cowboy requires them
-to be given as lowercase to function properly.</p></div>
-<div class="paragraph"><p>The type of the parsed value varies depending on
-the header. Similarly, the default value when calling
-<code>cowboy_req:parse_header/2</code> differs depending on the
-header.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name
-</dt>
-<dd>
-<p>
-Desired HTTP header name as a lowercase binary string.
-</p>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-<dt class="hdlist1">
-Default
-</dt>
-<dd>
-<p>
-Default value returned when the header is missing.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The parsed header value varies depending on the header.
-When the header is missing, the default argument is returned.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_headers">Headers</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The following snippets detail the types returned by the
-different headers. Unless mentioned otherwise, the
-default value when the header is missing will be <code>undefined</code>:</p></div>
-<div class="listingblock">
-<div class="title">accept</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="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)
- <span style="color: #990000">-></span> [{{<span style="color: #009900">Type</span>, <span style="color: #009900">SubType</span>, <span style="color: #009900">Params</span>}, <span style="color: #009900">Quality</span>, <span style="color: #009900">AcceptExt</span>}]
-
-<span style="color: #009900">Type</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span>
-<span style="color: #009900">SubType</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span>
-<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span>, <span style="color: #009900">Value</span>}]
-<span style="color: #009900">Quality</span> <span style="color: #990000">::</span> <span style="color: #993399">0</span><span style="color: #990000">..</span><span style="color: #993399">1000</span>
-<span style="color: #009900">AcceptExt</span> <span style="color: #990000">::</span> [<span style="color: #009900">Key</span> | {<span style="color: #009900">Key</span>, <span style="color: #009900">Value</span>}]
-<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span>
-<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">accept-charset, accept-encoding and accept-language</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="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> [{<span style="color: #009900">Value</span>, <span style="color: #009900">Quality</span>}]
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="color: #990000"><<</span><span style="color: #FF0000">"accept-charset"</span><span style="color: #990000">>></span>
- | <span style="color: #990000"><<</span><span style="color: #FF0000">"accept-encoding"</span><span style="color: #990000">>></span>
- | <span style="color: #990000"><<</span><span style="color: #FF0000">"accept-language"</span><span style="color: #990000">>></span>
-<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span>
-<span style="color: #009900">Quality</span> <span style="color: #990000">::</span> <span style="color: #993399">0</span><span style="color: #990000">..</span><span style="color: #993399">1000</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">authorization</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="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"authorization"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)
- <span style="color: #990000">-></span> {<span style="color: #FF6600">basic</span>, <span style="color: #009900">Username</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Password</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}
- | {<span style="color: #FF6600">bearer</span>, <span style="color: #009900">Token</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}
- | {<span style="color: #FF6600">digest</span>, [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}]}</tt></pre></div></div>
-<div class="listingblock">
-<div class="title">content-length</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="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-length"</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">non_neg_integer</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>When the content-length header is missing, <code>0</code> is returned.</p></div>
-<div class="listingblock">
-<div class="title">content-type</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="font-weight: bold"><span style="color: #000000">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: #009900">Type</span>, <span style="color: #009900">SubType</span>, <span style="color: #009900">Params</span>}
-
-<span style="color: #009900">Type</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span>
-<span style="color: #009900">SubType</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span>
-<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span>, <span style="color: #009900">Value</span>}]
-<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span>
-<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive;</span></span></tt></pre></div></div>
-<div class="paragraph"><p>Note that the value for the charset parameter is case insensitive
-and returned as a lowercase binary string.</p></div>
-<div class="listingblock">
-<div class="title">cookie</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="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"cookie"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> [{<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>}]
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
-<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div>
-<div class="paragraph"><p>When the cookie header is missing, <code>[]</code> is returned.</p></div>
-<div class="paragraph"><p>While an empty cookie header is not valid, some clients do
-send it. Cowboy will in this case also return <code>[]</code>.</p></div>
-<div class="listingblock">
-<div class="title">expect</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="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"expect"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="color: #FF6600">continue</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">if-match and if-none-match</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="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>)
- <span style="color: #990000">-></span> <span style="color: #FF6600">'*'</span> | [{<span style="color: #FF6600">weak</span> | <span style="color: #FF6600">strong</span>, <span style="color: #009900">OpaqueTag</span>}]
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="color: #990000"><<</span><span style="color: #FF0000">"if-match"</span><span style="color: #990000">>></span>
- | <span style="color: #990000"><<</span><span style="color: #FF0000">"if-none-match"</span><span style="color: #990000">>></span>
-<span style="color: #009900">OpaqueTag</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">if-modified-since and if-unmodified-since</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="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">calendar:datetime</span></span>()</tt></pre></div></div>
-<div class="listingblock">
-<div class="title">range</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="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"range"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> {<span style="color: #009900">From</span>, <span style="color: #009900">To</span>} | <span style="color: #009900">Final</span>
-
-<span style="color: #009900">From</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()
-<span style="color: #009900">To</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>() | <span style="color: #FF6600">infinity</span>
-<span style="color: #009900">Final</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">neg_integer</span></span>()</tt></pre></div></div>
-<div class="listingblock">
-<div class="title">sec-websocket-extensions</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="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sec-websocket-extensions"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)
- <span style="color: #990000">-></span> [{<span style="color: #009900">Extension</span>, <span style="color: #009900">Params</span>}]
-
-<span style="color: #009900">Extension</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
-<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [<span style="color: #009900">Key</span> | {<span style="color: #009900">Key</span>, <span style="color: #009900">Value</span>}]
-<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
-<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">sec-websocket-protocol and upgrade</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="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> [<span style="color: #009900">Token</span>]
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</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">"upgrade"</span><span style="color: #990000">>></span>
-<span style="color: #009900">Token</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">x-forwarded-for</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="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"x-forwarded-for"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> [<span style="color: #009900">Token</span>]
-
-<span style="color: #009900">Token</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Unknown headers</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="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000">_</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> {<span style="color: #000080">undefined</span>, <span style="color: #009900">RawValue</span>}</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the parsed header value is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Parse the accept header with a custom default value</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="font-style: italic"><span style="color: #9A1900">%% Accept everything when header is missing.</span></span>
-<span style="color: #009900">Accept</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">"accept"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>,
- [{{ <span style="color: #990000"><<</span><span style="color: #FF0000">"*"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"*"</span><span style="color: #990000">>></span>, []}, <span style="color: #993399">1000</span>, []}])<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Parse the content-length header</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="font-style: italic"><span style="color: #9A1900">%% Default content-length is 0.</span></span>
-<span style="color: #009900">Length</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-length"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.header">cowboy_req:header(3)</a>,
-<a href="../cowboy_req.headers">cowboy_req:headers(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:parse_header - Parse the given HTTP header</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="color: #009900">ParsedValue</span> | <span style="color: #009900">Default</span> +<span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">Default</span>) <span style="color: #990000">-></span> <span style="color: #009900">ParsedValue</span> | <span style="color: #009900">Default</span> + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() +<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>() +<span style="color: #009900">ParsedValue</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Parse the given HTTP header.</p></div> +<div class="paragraph"><p>The header name must be given as a lowercase binary string. +While header names are case insensitive, Cowboy requires them +to be given as lowercase to function properly.</p></div> +<div class="paragraph"><p>The type of the parsed value varies depending on +the header. Similarly, the default value when calling +<code>cowboy_req:parse_header/2</code> differs depending on the +header.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name +</dt> +<dd> +<p> +Desired HTTP header name as a lowercase binary string. +</p> +</dd> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +<dt class="hdlist1"> +Default +</dt> +<dd> +<p> +Default value returned when the header is missing. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The parsed header value varies depending on the header. +When the header is missing, the default argument is returned.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_headers">Headers</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The following snippets detail the types returned by the +different headers. Unless mentioned otherwise, the +default value when the header is missing will be <code>undefined</code>:</p></div> +<div class="listingblock"> +<div class="title">accept</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="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) + <span style="color: #990000">-></span> [{{<span style="color: #009900">Type</span>, <span style="color: #009900">SubType</span>, <span style="color: #009900">Params</span>}, <span style="color: #009900">Quality</span>, <span style="color: #009900">AcceptExt</span>}] + +<span style="color: #009900">Type</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span> +<span style="color: #009900">SubType</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span> +<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span>, <span style="color: #009900">Value</span>}] +<span style="color: #009900">Quality</span> <span style="color: #990000">::</span> <span style="color: #993399">0</span><span style="color: #990000">..</span><span style="color: #993399">1000</span> +<span style="color: #009900">AcceptExt</span> <span style="color: #990000">::</span> [<span style="color: #009900">Key</span> | {<span style="color: #009900">Key</span>, <span style="color: #009900">Value</span>}] +<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span> +<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">accept-charset, accept-encoding and accept-language</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="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> [{<span style="color: #009900">Value</span>, <span style="color: #009900">Quality</span>}] + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="color: #990000"><<</span><span style="color: #FF0000">"accept-charset"</span><span style="color: #990000">>></span> + | <span style="color: #990000"><<</span><span style="color: #FF0000">"accept-encoding"</span><span style="color: #990000">>></span> + | <span style="color: #990000"><<</span><span style="color: #FF0000">"accept-language"</span><span style="color: #990000">>></span> +<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span> +<span style="color: #009900">Quality</span> <span style="color: #990000">::</span> <span style="color: #993399">0</span><span style="color: #990000">..</span><span style="color: #993399">1000</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">authorization</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="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"authorization"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) + <span style="color: #990000">-></span> {<span style="color: #FF6600">basic</span>, <span style="color: #009900">Username</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Password</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()} + | {<span style="color: #FF6600">bearer</span>, <span style="color: #009900">Token</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()} + | {<span style="color: #FF6600">digest</span>, [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}]}</tt></pre></div></div> +<div class="listingblock"> +<div class="title">content-length</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="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-length"</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">non_neg_integer</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>When the content-length header is missing, <code>0</code> is returned.</p></div> +<div class="listingblock"> +<div class="title">content-type</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="font-weight: bold"><span style="color: #000000">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: #009900">Type</span>, <span style="color: #009900">SubType</span>, <span style="color: #009900">Params</span>} + +<span style="color: #009900">Type</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span> +<span style="color: #009900">SubType</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span> +<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span>, <span style="color: #009900">Value</span>}] +<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span> +<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive;</span></span></tt></pre></div></div> +<div class="paragraph"><p>Note that the value for the charset parameter is case insensitive +and returned as a lowercase binary string.</p></div> +<div class="listingblock"> +<div class="title">cookie</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="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"cookie"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> [{<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>}] + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> +<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div> +<div class="paragraph"><p>When the cookie header is missing, <code>[]</code> is returned.</p></div> +<div class="paragraph"><p>While an empty cookie header is not valid, some clients do +send it. Cowboy will in this case also return <code>[]</code>.</p></div> +<div class="listingblock"> +<div class="title">expect</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="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"expect"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="color: #FF6600">continue</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">if-match and if-none-match</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="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) + <span style="color: #990000">-></span> <span style="color: #FF6600">'*'</span> | [{<span style="color: #FF6600">weak</span> | <span style="color: #FF6600">strong</span>, <span style="color: #009900">OpaqueTag</span>}] + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="color: #990000"><<</span><span style="color: #FF0000">"if-match"</span><span style="color: #990000">>></span> + | <span style="color: #990000"><<</span><span style="color: #FF0000">"if-none-match"</span><span style="color: #990000">>></span> +<span style="color: #009900">OpaqueTag</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">if-modified-since and if-unmodified-since</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="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">calendar:datetime</span></span>()</tt></pre></div></div> +<div class="listingblock"> +<div class="title">range</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="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"range"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> {<span style="color: #009900">From</span>, <span style="color: #009900">To</span>} | <span style="color: #009900">Final</span> + +<span style="color: #009900">From</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>() +<span style="color: #009900">To</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>() | <span style="color: #FF6600">infinity</span> +<span style="color: #009900">Final</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">neg_integer</span></span>()</tt></pre></div></div> +<div class="listingblock"> +<div class="title">sec-websocket-extensions</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="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sec-websocket-extensions"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) + <span style="color: #990000">-></span> [{<span style="color: #009900">Extension</span>, <span style="color: #009900">Params</span>}] + +<span style="color: #009900">Extension</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> +<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [<span style="color: #009900">Key</span> | {<span style="color: #009900">Key</span>, <span style="color: #009900">Value</span>}] +<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> +<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">sec-websocket-protocol and upgrade</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="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> [<span style="color: #009900">Token</span>] + +<span style="color: #009900">Name</span> <span style="color: #990000">::</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">"upgrade"</span><span style="color: #990000">>></span> +<span style="color: #009900">Token</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">x-forwarded-for</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="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"x-forwarded-for"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> [<span style="color: #009900">Token</span>] + +<span style="color: #009900">Token</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Unknown headers</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="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000">_</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> {<span style="color: #000080">undefined</span>, <span style="color: #009900">RawValue</span>}</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the parsed header value is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Parse the accept header with a custom default value</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="font-style: italic"><span style="color: #9A1900">%% Accept everything when header is missing.</span></span> +<span style="color: #009900">Accept</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">"accept"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>, + [{{ <span style="color: #990000"><<</span><span style="color: #FF0000">"*"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"*"</span><span style="color: #990000">>></span>, []}, <span style="color: #993399">1000</span>, []}])<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Parse the content-length header</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="font-style: italic"><span style="color: #9A1900">%% Default content-length is 0.</span></span> +<span style="color: #009900">Length</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-length"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.header">cowboy_req:header(3)</a>, +<a href="../cowboy_req.headers">cowboy_req:headers(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.parse_qs/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.parse_qs/index.html index 9ac6af9a..3b9970cc 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.parse_qs/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.parse_qs/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:parse_qs(3)</title> @@ -67,117 +67,117 @@ <h1 class="lined-header"><span>cowboy_req:parse_qs(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:parse_qs - Parse the query string</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">parse_qs</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #000080">true</span>}]</tt></pre></div></div>
-<div class="paragraph"><p>Parse the query string as a list of key/value pairs.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The parsed query string is returned as a list of key/value pairs.
-The key is a binary string. The value is either a binary string,
-or the atom <code>true</code>. Both key and value are case sensitive.</p></div>
-<div class="paragraph"><p>The atom <code>true</code> is returned when a key is present in the query
-string without a value. For example, in the following URIs
-the key <code><<"edit">></code> will always have the value <code>true</code>:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<code>/posts/42?edit</code>
-</p>
-</li>
-<li>
-<p>
-<code>/posts/42?edit&exclusive=1</code>
-</p>
-</li>
-<li>
-<p>
-<code>/posts/42?exclusive=1&edit</code>
-</p>
-</li>
-<li>
-<p>
-<code>/posts/42?exclusive=1&edit&from=web</code>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: The parsed value is not longer cached in the Req object.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: Only the parsed query string is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced. Replaces <code>qs_val/1</code> and <code>qs_vals/1</code>.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Parse the query string and convert the keys to atoms</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">ParsedQs</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: #009900">AtomsQs</span> <span style="color: #990000">=</span> [{<span style="font-weight: bold"><span style="color: #000000">binary_to_existing_atom</span></span>(<span style="color: #009900">K</span>, <span style="color: #FF6600">latin1</span>), <span style="color: #009900">V</span>}
- || {<span style="color: #009900">K</span>, <span style="color: #009900">V</span>} <span style="color: #990000"><-</span> <span style="color: #009900">ParsedQs</span>]<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.qs">cowboy_req:qs(3)</a>,
-<a href="../cowboy_req.match_qs">cowboy_req:match_qs(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:parse_qs - Parse the query string</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">parse_qs</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #000080">true</span>}]</tt></pre></div></div> +<div class="paragraph"><p>Parse the query string as a list of key/value pairs.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The parsed query string is returned as a list of key/value pairs. +The key is a binary string. The value is either a binary string, +or the atom <code>true</code>. Both key and value are case sensitive.</p></div> +<div class="paragraph"><p>The atom <code>true</code> is returned when a key is present in the query +string without a value. For example, in the following URIs +the key <code><<"edit">></code> will always have the value <code>true</code>:</p></div> +<div class="ulist"><ul> +<li> +<p> +<code>/posts/42?edit</code> +</p> +</li> +<li> +<p> +<code>/posts/42?edit&exclusive=1</code> +</p> +</li> +<li> +<p> +<code>/posts/42?exclusive=1&edit</code> +</p> +</li> +<li> +<p> +<code>/posts/42?exclusive=1&edit&from=web</code> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: The parsed value is not longer cached in the Req object. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: Only the parsed query string is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: Function introduced. Replaces <code>qs_val/1</code> and <code>qs_vals/1</code>. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Parse the query string and convert the keys to atoms</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">ParsedQs</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: #009900">AtomsQs</span> <span style="color: #990000">=</span> [{<span style="font-weight: bold"><span style="color: #000000">binary_to_existing_atom</span></span>(<span style="color: #009900">K</span>, <span style="color: #FF6600">latin1</span>), <span style="color: #009900">V</span>} + || {<span style="color: #009900">K</span>, <span style="color: #009900">V</span>} <span style="color: #990000"><-</span> <span style="color: #009900">ParsedQs</span>]<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.qs">cowboy_req:qs(3)</a>, +<a href="../cowboy_req.match_qs">cowboy_req:match_qs(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.path/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.path/index.html index e5a69e4f..0836001b 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.path/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.path/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:path(3)</title> @@ -67,90 +67,90 @@ <h1 class="lined-header"><span>cowboy_req:path(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:path - URI path</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">path</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Path</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return the path of the effective request URI.</p></div>
-<div class="paragraph"><p>The path can also be obtained using pattern matching:</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">path</span> <span style="color: #990000">:=</span> <span style="color: #009900">Path</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The path is returned as a binary string. It is case sensitive.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the path is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get the effective request URI’s path</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">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>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.binding">cowboy_req:binding(3)</a>,
-<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a>,
-<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:path - URI path</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">path</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Path</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return the path of the effective request URI.</p></div> +<div class="paragraph"><p>The path can also be obtained using pattern matching:</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">path</span> <span style="color: #990000">:=</span> <span style="color: #009900">Path</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The path is returned as a binary string. It is case sensitive.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the path is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get the effective request URI’s path</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">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> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.binding">cowboy_req:binding(3)</a>, +<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a>, +<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.path_info/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.path_info/index.html index 39ef5f81..03649d9b 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.path_info/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.path_info/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:path_info(3)</title> @@ -67,87 +67,87 @@ <h1 class="lined-header"><span>cowboy_req:path_info(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:path_info - Access the route’s trailing path segments</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">path_info</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:tokens</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return the tokens for the trailing path segments.</p></div>
-<div class="paragraph"><p>This is the part of the host name that was matched using
-the <code>...</code> notation.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The tokens are returned as a list of case sensitive
-binary strings.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the tokens are returned, they are no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get the path_info tokens</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">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>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.binding">cowboy_req:binding(3)</a>,
-<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a>,
-<a href="../cowboy_req.host_info">cowboy_req:host_info(3)</a>,
-<a href="../cowboy_router">cowboy_router(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:path_info - Access the route’s trailing path segments</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">path_info</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:tokens</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return the tokens for the trailing path segments.</p></div> +<div class="paragraph"><p>This is the part of the host name that was matched using +the <code>...</code> notation.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The tokens are returned as a list of case sensitive +binary strings.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the tokens are returned, they are no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get the path_info tokens</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">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> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.binding">cowboy_req:binding(3)</a>, +<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a>, +<a href="../cowboy_req.host_info">cowboy_req:host_info(3)</a>, +<a href="../cowboy_router">cowboy_router(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.peer/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.peer/index.html index 6568e749..634b8e08 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.peer/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.peer/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:peer(3)</title> @@ -67,96 +67,96 @@ <h1 class="lined-header"><span>cowboy_req:peer(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:peer - Peer address and port</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">peer</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Peer</span>
-
-<span style="color: #009900">Peer</span> <span style="color: #990000">::</span> {<span style="font-weight: bold"><span style="color: #000000">inet:ip_address</span></span>(), <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>Return the peer’s IP address and port number.</p></div>
-<div class="paragraph"><p>The peer can also be obtained using pattern matching:</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">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>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The peer’s IP address and port number.</p></div>
-<div class="paragraph"><p>The peer is not necessarily the client’s IP address and port.
-It is the IP address of the endpoint connecting directly to
-the server, which may be a gateway or a proxy.</p></div>
-<div class="paragraph"><p>The forwarded header can be used to get better information
-about the different endpoints from the client to the server.
-Note however that it is only informative; there is no reliable
-way of determining the source of an HTTP request.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the peer is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get the peer IP address and port number.</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">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>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:peer - Peer address and port</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">peer</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Peer</span> + +<span style="color: #009900">Peer</span> <span style="color: #990000">::</span> {<span style="font-weight: bold"><span style="color: #000000">inet:ip_address</span></span>(), <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Return the peer’s IP address and port number.</p></div> +<div class="paragraph"><p>The peer can also be obtained using pattern matching:</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">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> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The peer’s IP address and port number.</p></div> +<div class="paragraph"><p>The peer is not necessarily the client’s IP address and port. +It is the IP address of the endpoint connecting directly to +the server, which may be a gateway or a proxy.</p></div> +<div class="paragraph"><p>The forwarded header can be used to get better information +about the different endpoints from the client to the server. +Note however that it is only informative; there is no reliable +way of determining the source of an HTTP request.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the peer is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get the peer IP address and port number.</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">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> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.port/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.port/index.html index 93f106b0..5864d84a 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.port/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.port/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:port(3)</title> @@ -67,90 +67,90 @@ <h1 class="lined-header"><span>cowboy_req:port(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:port - URI port number</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">port</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Port</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return the port number of the effective request URI.</p></div>
-<div class="paragraph"><p>Note that the port number returned by this function is obtained
-by parsing the host header. It may be different from the port
-the peer used to connect to Cowboy.</p></div>
-<div class="paragraph"><p>The port number can also be obtained using pattern matching:</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">port</span> <span style="color: #990000">:=</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>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The port number is returned as an integer.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the port number is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get the effective request URI’s port number</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">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: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:port - URI port number</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">port</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Port</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return the port number of the effective request URI.</p></div> +<div class="paragraph"><p>Note that the port number returned by this function is obtained +by parsing the host header. It may be different from the port +the peer used to connect to Cowboy.</p></div> +<div class="paragraph"><p>The port number can also be obtained using pattern matching:</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">port</span> <span style="color: #990000">:=</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> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The port number is returned as an integer.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the port number is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get the effective request URI’s port number</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">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: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.push/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.push/index.html index 8097d067..bc56d006 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.push/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.push/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:push(3)</title> @@ -67,141 +67,141 @@ <h1 class="lined-header"><span>cowboy_req:push(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:push - Push a resource to the client</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">push</span></span>(<span style="color: #009900">Path</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">push</span></span>(<span style="color: #009900">Path</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span>, #{})
-
-<span style="font-weight: bold"><span style="color: #000000">push</span></span>(<span style="color: #009900">Path</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>)
- <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span>
-
-<span style="color: #009900">Path</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
-<span style="color: #009900">Headers</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>()
-<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:push_opts</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Push a resource to the client.</p></div>
-<div class="paragraph"><p>Cowboy handles push requests the same way as if they came
-from the client, including the creation of a request handling
-process, routing and middlewares and so on.</p></div>
-<div class="paragraph"><p>This function does nothing when the HTTP/1.1 protocol is
-used. You may call it safely without first checking whether
-the connection uses HTTP/2.</p></div>
-<div class="paragraph"><p>The header names must be given as lowercase binary strings.
-While header names are case insensitive, Cowboy requires them
-to be given as lowercase to function properly.</p></div>
-<div class="paragraph"><p>Note that the headers must be the headers the client is expected
-to send if it were to perform the request. They are therefore
-request headers, and not response headers.</p></div>
-<div class="paragraph"><p>By default, Cowboy will use the GET method, an empty query string,
-and take the scheme, host and port directly from the current
-request’s URI. You can override them by passing options.</p></div>
-<div class="paragraph"><p>It is not possible to push resources after sending a response.
-Any attempt will result in an error.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Path
-</dt>
-<dd>
-<p>
-The status code for the response.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers
-</dt>
-<dd>
-<p>
-The response headers.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Header names must be given as lowercase binary strings.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-<dt class="hdlist1">
-Opts
-</dt>
-<dd>
-<p>
-Customize the HTTP method or the URI scheme, host, port
-or query string.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The atom <code>ok</code> is always returned. It can be safely ignored.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Push a resource</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="font-weight: bold"><span style="color: #000000">cowboy_req:push</span></span>(<span style="color: #FF0000">"/static/style.css"</span>, #{
- <span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/css"</span><span style="color: #990000">>></span>
-}, <span style="color: #009900">Req</span>),</tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Push a resource with a custom host</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="font-weight: bold"><span style="color: #000000">cowboy_req:push</span></span>(<span style="color: #FF0000">"/static/style.css"</span>, #{
- <span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/css"</span><span style="color: #990000">>></span>
-}, #{<span style="color: #0000FF">host</span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"cdn.example.org"</span><span style="color: #990000">>></span>}, <span style="color: #009900">Req</span>),</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.reply">cowboy_req:reply(3)</a>,
-<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:push - Push a resource to the client</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">push</span></span>(<span style="color: #009900">Path</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">push</span></span>(<span style="color: #009900">Path</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span>, #{}) + +<span style="font-weight: bold"><span style="color: #000000">push</span></span>(<span style="color: #009900">Path</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>) + <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span> + +<span style="color: #009900">Path</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> +<span style="color: #009900">Headers</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>() +<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:push_opts</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Push a resource to the client.</p></div> +<div class="paragraph"><p>Cowboy handles push requests the same way as if they came +from the client, including the creation of a request handling +process, routing and middlewares and so on.</p></div> +<div class="paragraph"><p>This function does nothing when the HTTP/1.1 protocol is +used. You may call it safely without first checking whether +the connection uses HTTP/2.</p></div> +<div class="paragraph"><p>The header names must be given as lowercase binary strings. +While header names are case insensitive, Cowboy requires them +to be given as lowercase to function properly.</p></div> +<div class="paragraph"><p>Note that the headers must be the headers the client is expected +to send if it were to perform the request. They are therefore +request headers, and not response headers.</p></div> +<div class="paragraph"><p>By default, Cowboy will use the GET method, an empty query string, +and take the scheme, host and port directly from the current +request’s URI. You can override them by passing options.</p></div> +<div class="paragraph"><p>It is not possible to push resources after sending a response. +Any attempt will result in an error.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Path +</dt> +<dd> +<p> +The status code for the response. +</p> +</dd> +<dt class="hdlist1"> +Headers +</dt> +<dd> +<p> +The response headers. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Header names must be given as lowercase binary strings.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +<dt class="hdlist1"> +Opts +</dt> +<dd> +<p> +Customize the HTTP method or the URI scheme, host, port +or query string. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The atom <code>ok</code> is always returned. It can be safely ignored.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Push a resource</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="font-weight: bold"><span style="color: #000000">cowboy_req:push</span></span>(<span style="color: #FF0000">"/static/style.css"</span>, #{ + <span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/css"</span><span style="color: #990000">>></span> +}, <span style="color: #009900">Req</span>),</tt></pre></div></div> +<div class="listingblock"> +<div class="title">Push a resource with a custom host</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="font-weight: bold"><span style="color: #000000">cowboy_req:push</span></span>(<span style="color: #FF0000">"/static/style.css"</span>, #{ + <span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"text/css"</span><span style="color: #990000">>></span> +}, #{<span style="color: #0000FF">host</span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"cdn.example.org"</span><span style="color: #990000">>></span>}, <span style="color: #009900">Req</span>),</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.reply">cowboy_req:reply(3)</a>, +<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.qs/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.qs/index.html index 39ec5d7c..62407766 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.qs/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.qs/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:qs(3)</title> @@ -67,89 +67,89 @@ <h1 class="lined-header"><span>cowboy_req:qs(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:qs - URI query string</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">qs</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></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: #000080">binary</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return the query string of the effective request URI.</p></div>
-<div class="paragraph"><p>The query string can also be obtained using pattern matching:</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">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>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The query string is returned as a binary string. It is case sensitive.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the query string is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get the effective request URI’s query string</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">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>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.parse_qs">cowboy_req:parse_qs(3)</a>,
-<a href="../cowboy_req.match_qs">cowboy_req:match_qs(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:qs - URI query string</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">qs</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></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: #000080">binary</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return the query string of the effective request URI.</p></div> +<div class="paragraph"><p>The query string can also be obtained using pattern matching:</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">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> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The query string is returned as a binary string. It is case sensitive.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the query string is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get the effective request URI’s query string</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">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> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.parse_qs">cowboy_req:parse_qs(3)</a>, +<a href="../cowboy_req.match_qs">cowboy_req:match_qs(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.read_body/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.read_body/index.html index e792a7a6..08b506f0 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.read_body/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.read_body/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:read_body(3)</title> @@ -67,143 +67,143 @@ <h1 class="lined-header"><span>cowboy_req:read_body(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:read_body - Read the request body</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">read_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">read_body</span></span>(<span style="color: #009900">Req</span>, #{})
-
-<span style="font-weight: bold"><span style="color: #000000">read_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>)
- <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Req</span>}
- | {<span style="color: #FF6600">more</span>, <span style="color: #009900">Data</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Req</span>}
-
-<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body_opts</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Read the request body.</p></div>
-<div class="paragraph"><p>This function reads a chunk of the request body. A <code>more</code> tuple
-is returned when more data remains to be read. Call the function
-repeatedly until an <code>ok</code> tuple is returned to read the entire body.</p></div>
-<div class="paragraph"><p>An <code>ok</code> tuple with empty data is returned when the request has no body,
-or when calling this function again after the body has already
-been read. It is therefore safe to call this function directly.
-Note that the body can only be read once.</p></div>
-<div class="paragraph"><p>This function reads the request body from the connection process.
-The connection process is responsible for reading from the socket.
-The exact behavior varies depending on the protocol.</p></div>
-<div class="paragraph"><p>The options therefore are only related to the communication
-between the request process and the connection process.</p></div>
-<div class="paragraph"><p>Cowboy will automatically handle protocol details including
-the expect header, chunked transfer-encoding and others.</p></div>
-<div class="paragraph"><p>Once the body has been read fully, Cowboy sets the content-length
-header if it was not previously provided.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-<dt class="hdlist1">
-Opts
-</dt>
-<dd>
-<p>
-A map of body reading options.
-</p>
-<div class="paragraph"><p>The <code>length</code> option can be used to request smaller or bigger
-chunks of data to be sent. It is a best effort approach, Cowboy
-may send more data than configured on occasions. It defaults
-to 8MB.</p></div>
-<div class="paragraph"><p>The <code>period</code> indicates how long the connection process will wait
-before it provides us with the data it received. It defaults
-to 15 seconds.</p></div>
-<div class="paragraph"><p>The connection process sends data to the request process when
-either the <code>length</code> of data or the <code>period</code> of time is reached.</p></div>
-<div class="paragraph"><p>The <code>timeout</code> option is a safeguard in case the connection
-process becomes unresponsive. The function will crash if no
-message was received in that interval. The timeout should be
-larger than the period. It defaults to the period + 1 second.</p></div>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A <code>more</code> tuple is returned when there are more data to be read.</p></div>
-<div class="paragraph"><p>An <code>ok</code> tuple is returned when there are no more data to be read,
-either because this is the last chunk of data, the body has already
-been read, or there was no body to begin with.</p></div>
-<div class="paragraph"><p>The data is always returned as a binary.</p></div>
-<div class="paragraph"><p>The Req object returned in the tuple must be used for that point
-onward. It contains a more up to date representation of the request.
-For example it may have an added content-length header once the
-body has been read.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced. Replaces <code>body/1,2</code>.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Read the entire body</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="font-weight: bold"><span style="color: #000000">read_body</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">Acc</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="color: #FF6600">ok</span>, <span style="color: #990000"><<</span> <span style="color: #009900">Acc</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Data</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></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">read_body</span></span>(<span style="color: #009900">Req</span>, <span style="color: #990000"><<</span> <span style="color: #009900">Acc</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Data</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span> <span style="color: #990000">>></span>)
- <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Read the body in small chunks</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="font-weight: bold"><span style="color: #000000">cowboy_req:read_body</span></span>(<span style="color: #009900">Req</span>, #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="color: #993399">64000</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.has_body">cowboy_req:has_body(3)</a>,
-<a href="../cowboy_req.body_length">cowboy_req:body_length(3)</a>,
-<a href="../cowboy_req.read_urlencoded_body">cowboy_req:read_urlencoded_body(3)</a>,
-<a href="../cowboy_req.read_part">cowboy_req:read_part(3)</a>,
-<a href="../cowboy_req.read_part_body">cowboy_req:read_part_body(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:read_body - Read the request body</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">read_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">read_body</span></span>(<span style="color: #009900">Req</span>, #{}) + +<span style="font-weight: bold"><span style="color: #000000">read_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>) + <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Req</span>} + | {<span style="color: #FF6600">more</span>, <span style="color: #009900">Data</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Req</span>} + +<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body_opts</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Read the request body.</p></div> +<div class="paragraph"><p>This function reads a chunk of the request body. A <code>more</code> tuple +is returned when more data remains to be read. Call the function +repeatedly until an <code>ok</code> tuple is returned to read the entire body.</p></div> +<div class="paragraph"><p>An <code>ok</code> tuple with empty data is returned when the request has no body, +or when calling this function again after the body has already +been read. It is therefore safe to call this function directly. +Note that the body can only be read once.</p></div> +<div class="paragraph"><p>This function reads the request body from the connection process. +The connection process is responsible for reading from the socket. +The exact behavior varies depending on the protocol.</p></div> +<div class="paragraph"><p>The options therefore are only related to the communication +between the request process and the connection process.</p></div> +<div class="paragraph"><p>Cowboy will automatically handle protocol details including +the expect header, chunked transfer-encoding and others.</p></div> +<div class="paragraph"><p>Once the body has been read fully, Cowboy sets the content-length +header if it was not previously provided.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +<dt class="hdlist1"> +Opts +</dt> +<dd> +<p> +A map of body reading options. +</p> +<div class="paragraph"><p>The <code>length</code> option can be used to request smaller or bigger +chunks of data to be sent. It is a best effort approach, Cowboy +may send more data than configured on occasions. It defaults +to 8MB.</p></div> +<div class="paragraph"><p>The <code>period</code> indicates how long the connection process will wait +before it provides us with the data it received. It defaults +to 15 seconds.</p></div> +<div class="paragraph"><p>The connection process sends data to the request process when +either the <code>length</code> of data or the <code>period</code> of time is reached.</p></div> +<div class="paragraph"><p>The <code>timeout</code> option is a safeguard in case the connection +process becomes unresponsive. The function will crash if no +message was received in that interval. The timeout should be +larger than the period. It defaults to the period + 1 second.</p></div> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A <code>more</code> tuple is returned when there are more data to be read.</p></div> +<div class="paragraph"><p>An <code>ok</code> tuple is returned when there are no more data to be read, +either because this is the last chunk of data, the body has already +been read, or there was no body to begin with.</p></div> +<div class="paragraph"><p>The data is always returned as a binary.</p></div> +<div class="paragraph"><p>The Req object returned in the tuple must be used for that point +onward. It contains a more up to date representation of the request. +For example it may have an added content-length header once the +body has been read.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Function introduced. Replaces <code>body/1,2</code>. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Read the entire body</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="font-weight: bold"><span style="color: #000000">read_body</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">Acc</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="color: #FF6600">ok</span>, <span style="color: #990000"><<</span> <span style="color: #009900">Acc</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Data</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></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">read_body</span></span>(<span style="color: #009900">Req</span>, <span style="color: #990000"><<</span> <span style="color: #009900">Acc</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Data</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span> <span style="color: #990000">>></span>) + <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Read the body in small chunks</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="font-weight: bold"><span style="color: #000000">cowboy_req:read_body</span></span>(<span style="color: #009900">Req</span>, #{<span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="color: #993399">64000</span>})<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.has_body">cowboy_req:has_body(3)</a>, +<a href="../cowboy_req.body_length">cowboy_req:body_length(3)</a>, +<a href="../cowboy_req.read_urlencoded_body">cowboy_req:read_urlencoded_body(3)</a>, +<a href="../cowboy_req.read_part">cowboy_req:read_part(3)</a>, +<a href="../cowboy_req.read_part_body">cowboy_req:read_part_body(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.read_part/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.read_part/index.html index 29f18993..c5b548d3 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.read_part/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.read_part/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:read_part(3)</title> @@ -67,162 +67,162 @@ <h1 class="lined-header"><span>cowboy_req:read_part(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:read_part - Read the next multipart headers</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">read_part</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">read_part</span></span>(<span style="color: #009900">Req</span>, #{})
-
-<span style="font-weight: bold"><span style="color: #000000">read_part</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>)
- <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span>} | {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>}
-
-<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body_opts</span></span>()
-<span style="color: #009900">Headers</span> <span style="color: #990000">::</span> #{<span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>Read the next part of a multipart body.</p></div>
-<div class="paragraph"><p>This function reads the request body and parses it as
-multipart. Each parts of a multipart representation have
-their own headers and body. This function parses and returns
-headers. Examples of multipart media types are
-<code>multipart/form-data</code> and <code>multipart/byteranges</code>.</p></div>
-<div class="paragraph"><p>Cowboy will skip any data remaining until the beginning of
-the next part. This includes the preamble to the multipart
-message but also the body of a previous part if it hasn’t
-been read. Both are skipped automatically when calling this
-function.</p></div>
-<div class="paragraph"><p>Cowboy will read the body before parsing in chunks of size
-up to 64KB, with a period of 5 seconds. This is tailored for
-reading part headers and might not be the most efficient for
-skipping the previous part’s body.</p></div>
-<div class="paragraph"><p>The headers returned are MIME headers, <strong>NOT</strong> HTTP headers.
-They can be parsed using the functions from the <code>cow_multipart</code>
-module. In addition, the <code>cow_multipart:form_data/1</code> function
-can be used to quickly extract information from <code>multipart/form-data</code>
-representations.</p></div>
-<div class="paragraph"><p>Once a part has been read, it can not be read again.</p></div>
-<div class="paragraph"><p>Once the body has been read, Cowboy sets the content-length
-header if it was not previously provided.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-<dt class="hdlist1">
-Opts
-</dt>
-<dd>
-<p>
-A map of body reading options. Please refer to
-<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>
-for details about each option.
-</p>
-<div class="paragraph"><p>This function defaults the <code>length</code> to 64KB and the <code>period</code>
-to 5 seconds.</p></div>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An <code>ok</code> tuple is returned containing the next part’s headers
-as a map.</p></div>
-<div class="paragraph"><p>A <code>done</code> tuple is returned if there are no more parts to read.</p></div>
-<div class="paragraph"><p>The Req object returned in the tuple must be used for that point
-onward. It contains a more up to date representation of the request.
-For example it may have an added content-length header once the
-body has been read.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced. Replaces <code>part/1,2</code>.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Read all parts</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="font-weight: bold"><span style="color: #000000">acc_multipart</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">Acc</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_part</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">Headers</span>, <span style="color: #009900">Req1</span>} <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Body</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">stream_body</span></span>(<span style="color: #009900">Req1</span>, <span style="color: #990000"><<>></span>),
- <span style="font-weight: bold"><span style="color: #000000">acc_multipart</span></span>(<span style="color: #009900">Req</span>, [{<span style="color: #009900">Headers</span>, <span style="color: #009900">Body</span>}|<span style="color: #009900">Acc</span>]);
- {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span>
- {<span style="font-weight: bold"><span style="color: #000000">lists:reverse</span></span>(<span style="color: #009900">Acc</span>), <span style="color: #009900">Req</span>}
- <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">stream_body</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">Acc</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_part_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">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">stream_body</span></span>(<span style="color: #009900">Req</span>, <span style="color: #990000"><<</span> <span style="color: #009900">Acc</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Data</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span> <span style="color: #990000">>></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="color: #FF6600">ok</span>, <span style="color: #990000"><<</span> <span style="color: #009900">Acc</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Data</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span> <span style="color: #990000">>></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="listingblock">
-<div class="title">Read all part headers, skipping bodies</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="font-weight: bold"><span style="color: #000000">skip_body_multipart</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">Acc</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_part</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">Headers</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">skip_body_multipart</span></span>(<span style="color: #009900">Req</span>, [<span style="color: #009900">Headers</span>|<span style="color: #009900">Acc</span>]);
- {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span>
- {<span style="font-weight: bold"><span style="color: #000000">lists:reverse</span></span>(<span style="color: #009900">Acc</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="listingblock">
-<div class="title">Read a part header in larger chunks</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: #FF6600">ok</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_part</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: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.has_body">cowboy_req:has_body(3)</a>,
-<a href="../cowboy_req.body_length">cowboy_req:body_length(3)</a>,
-<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>,
-<a href="../cowboy_req.read_urlencoded_body">cowboy_req:read_urlencoded_body(3)</a>,
-<a href="../cowboy_req.read_part_body">cowboy_req:read_part_body(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:read_part - Read the next multipart headers</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">read_part</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">read_part</span></span>(<span style="color: #009900">Req</span>, #{}) + +<span style="font-weight: bold"><span style="color: #000000">read_part</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>) + <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span>} | {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>} + +<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body_opts</span></span>() +<span style="color: #009900">Headers</span> <span style="color: #990000">::</span> #{<span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Read the next part of a multipart body.</p></div> +<div class="paragraph"><p>This function reads the request body and parses it as +multipart. Each parts of a multipart representation have +their own headers and body. This function parses and returns +headers. Examples of multipart media types are +<code>multipart/form-data</code> and <code>multipart/byteranges</code>.</p></div> +<div class="paragraph"><p>Cowboy will skip any data remaining until the beginning of +the next part. This includes the preamble to the multipart +message but also the body of a previous part if it hasn’t +been read. Both are skipped automatically when calling this +function.</p></div> +<div class="paragraph"><p>Cowboy will read the body before parsing in chunks of size +up to 64KB, with a period of 5 seconds. This is tailored for +reading part headers and might not be the most efficient for +skipping the previous part’s body.</p></div> +<div class="paragraph"><p>The headers returned are MIME headers, <strong>NOT</strong> HTTP headers. +They can be parsed using the functions from the <code>cow_multipart</code> +module. In addition, the <code>cow_multipart:form_data/1</code> function +can be used to quickly extract information from <code>multipart/form-data</code> +representations.</p></div> +<div class="paragraph"><p>Once a part has been read, it can not be read again.</p></div> +<div class="paragraph"><p>Once the body has been read, Cowboy sets the content-length +header if it was not previously provided.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +<dt class="hdlist1"> +Opts +</dt> +<dd> +<p> +A map of body reading options. Please refer to +<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a> +for details about each option. +</p> +<div class="paragraph"><p>This function defaults the <code>length</code> to 64KB and the <code>period</code> +to 5 seconds.</p></div> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An <code>ok</code> tuple is returned containing the next part’s headers +as a map.</p></div> +<div class="paragraph"><p>A <code>done</code> tuple is returned if there are no more parts to read.</p></div> +<div class="paragraph"><p>The Req object returned in the tuple must be used for that point +onward. It contains a more up to date representation of the request. +For example it may have an added content-length header once the +body has been read.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Function introduced. Replaces <code>part/1,2</code>. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Read all parts</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="font-weight: bold"><span style="color: #000000">acc_multipart</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">Acc</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_part</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">Headers</span>, <span style="color: #009900">Req1</span>} <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Body</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">stream_body</span></span>(<span style="color: #009900">Req1</span>, <span style="color: #990000"><<>></span>), + <span style="font-weight: bold"><span style="color: #000000">acc_multipart</span></span>(<span style="color: #009900">Req</span>, [{<span style="color: #009900">Headers</span>, <span style="color: #009900">Body</span>}|<span style="color: #009900">Acc</span>]); + {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> + {<span style="font-weight: bold"><span style="color: #000000">lists:reverse</span></span>(<span style="color: #009900">Acc</span>), <span style="color: #009900">Req</span>} + <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">stream_body</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">Acc</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_part_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">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">stream_body</span></span>(<span style="color: #009900">Req</span>, <span style="color: #990000"><<</span> <span style="color: #009900">Acc</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Data</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span> <span style="color: #990000">>></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="color: #FF6600">ok</span>, <span style="color: #990000"><<</span> <span style="color: #009900">Acc</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Data</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span> <span style="color: #990000">>></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="listingblock"> +<div class="title">Read all part headers, skipping bodies</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="font-weight: bold"><span style="color: #000000">skip_body_multipart</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">Acc</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_part</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">Headers</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">skip_body_multipart</span></span>(<span style="color: #009900">Req</span>, [<span style="color: #009900">Headers</span>|<span style="color: #009900">Acc</span>]); + {<span style="color: #FF6600">done</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">-></span> + {<span style="font-weight: bold"><span style="color: #000000">lists:reverse</span></span>(<span style="color: #009900">Acc</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="listingblock"> +<div class="title">Read a part header in larger chunks</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: #FF6600">ok</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_part</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: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.has_body">cowboy_req:has_body(3)</a>, +<a href="../cowboy_req.body_length">cowboy_req:body_length(3)</a>, +<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>, +<a href="../cowboy_req.read_urlencoded_body">cowboy_req:read_urlencoded_body(3)</a>, +<a href="../cowboy_req.read_part_body">cowboy_req:read_part_body(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.read_part_body/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.read_part_body/index.html index 54a79c15..28fe5e6e 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.read_part_body/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.read_part_body/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:read_part_body(3)</title> @@ -67,130 +67,130 @@ <h1 class="lined-header"><span>cowboy_req:read_part_body(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:read_part_body - Read the current part’s body</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">read_part_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">read_part_body</span></span>(<span style="color: #009900">Req</span>, #{})
-
-<span style="font-weight: bold"><span style="color: #000000">read_part_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>)
- <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Req</span>}
- | {<span style="color: #FF6600">more</span>, <span style="color: #009900">Data</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Req</span>}
-
-<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body_opts</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Read the body of the current part of the multipart message.</p></div>
-<div class="paragraph"><p>This function reads the request body and parses it as
-multipart. Each parts of a multipart representation have
-their own headers and body. This function returns the
-body of the current part. Examples of multipart media types
-are <code>multipart/form-data</code> and <code>multipart/byteranges</code>.</p></div>
-<div class="paragraph"><p>This function reads a chunk of the part’s body. A <code>more</code> tuple
-is returned when more data remains to be read. Call the function
-repeatedly until an <code>ok</code> tuple is returned to read the entire body.</p></div>
-<div class="paragraph"><p>Once a part has been read, it can not be read again.</p></div>
-<div class="paragraph"><p>Once the body has been read, Cowboy sets the content-length
-header if it was not previously provided.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-<dt class="hdlist1">
-Opts
-</dt>
-<dd>
-<p>
-A map of body reading options. Please refer to
-<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>
-for details about each option.
-</p>
-<div class="paragraph"><p>This function uses the same default options as the
-<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>
-function.</p></div>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A <code>more</code> tuple is returned when there are more data to be read.</p></div>
-<div class="paragraph"><p>An <code>ok</code> tuple is returned when there are no more data to be read.</p></div>
-<div class="paragraph"><p>The data is always returned as a binary.</p></div>
-<div class="paragraph"><p>The Req object returned in the tuple must be used for that point
-onward. It contains a more up to date representation of the request.
-For example it may have an added content-length header once the
-body has been read.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced. Replaces <code>part_body/1,2</code>.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Read a full part’s body</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="font-weight: bold"><span style="color: #000000">stream_body</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">Acc</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_part_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">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">stream_body</span></span>(<span style="color: #009900">Req</span>, <span style="color: #990000"><<</span> <span style="color: #009900">Acc</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Data</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span> <span style="color: #990000">>></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="color: #FF6600">ok</span>, <span style="color: #990000"><<</span> <span style="color: #009900">Acc</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Data</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span> <span style="color: #990000">>></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="listingblock">
-<div class="title">Ensure a part’s body is smaller than 64KB</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: #FF6600">ok</span>, <span style="color: #009900">Body</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_part_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">64000</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.has_body">cowboy_req:has_body(3)</a>,
-<a href="../cowboy_req.body_length">cowboy_req:body_length(3)</a>,
-<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>,
-<a href="../cowboy_req.read_urlencoded_body">cowboy_req:read_urlencoded_body(3)</a>,
-<a href="../cowboy_req.read_part">cowboy_req:read_part(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:read_part_body - Read the current part’s body</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">read_part_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">read_part_body</span></span>(<span style="color: #009900">Req</span>, #{}) + +<span style="font-weight: bold"><span style="color: #000000">read_part_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>) + <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Req</span>} + | {<span style="color: #FF6600">more</span>, <span style="color: #009900">Data</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Req</span>} + +<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body_opts</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Read the body of the current part of the multipart message.</p></div> +<div class="paragraph"><p>This function reads the request body and parses it as +multipart. Each parts of a multipart representation have +their own headers and body. This function returns the +body of the current part. Examples of multipart media types +are <code>multipart/form-data</code> and <code>multipart/byteranges</code>.</p></div> +<div class="paragraph"><p>This function reads a chunk of the part’s body. A <code>more</code> tuple +is returned when more data remains to be read. Call the function +repeatedly until an <code>ok</code> tuple is returned to read the entire body.</p></div> +<div class="paragraph"><p>Once a part has been read, it can not be read again.</p></div> +<div class="paragraph"><p>Once the body has been read, Cowboy sets the content-length +header if it was not previously provided.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +<dt class="hdlist1"> +Opts +</dt> +<dd> +<p> +A map of body reading options. Please refer to +<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a> +for details about each option. +</p> +<div class="paragraph"><p>This function uses the same default options as the +<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a> +function.</p></div> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A <code>more</code> tuple is returned when there are more data to be read.</p></div> +<div class="paragraph"><p>An <code>ok</code> tuple is returned when there are no more data to be read.</p></div> +<div class="paragraph"><p>The data is always returned as a binary.</p></div> +<div class="paragraph"><p>The Req object returned in the tuple must be used for that point +onward. It contains a more up to date representation of the request. +For example it may have an added content-length header once the +body has been read.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Function introduced. Replaces <code>part_body/1,2</code>. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Read a full part’s body</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="font-weight: bold"><span style="color: #000000">stream_body</span></span>(<span style="color: #009900">Req0</span>, <span style="color: #009900">Acc</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_part_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">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">stream_body</span></span>(<span style="color: #009900">Req</span>, <span style="color: #990000"><<</span> <span style="color: #009900">Acc</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Data</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span> <span style="color: #990000">>></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="color: #FF6600">ok</span>, <span style="color: #990000"><<</span> <span style="color: #009900">Acc</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Data</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span> <span style="color: #990000">>></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="listingblock"> +<div class="title">Ensure a part’s body is smaller than 64KB</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: #FF6600">ok</span>, <span style="color: #009900">Body</span>, <span style="color: #009900">Req</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_part_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">64000</span>})<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.has_body">cowboy_req:has_body(3)</a>, +<a href="../cowboy_req.body_length">cowboy_req:body_length(3)</a>, +<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>, +<a href="../cowboy_req.read_urlencoded_body">cowboy_req:read_urlencoded_body(3)</a>, +<a href="../cowboy_req.read_part">cowboy_req:read_part(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.read_urlencoded_body/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.read_urlencoded_body/index.html index 1be7f378..2fbe784d 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.read_urlencoded_body/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.read_urlencoded_body/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:read_urlencoded_body(3)</title> @@ -67,126 +67,126 @@ <h1 class="lined-header"><span>cowboy_req:read_urlencoded_body(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:read_urlencoded_body - Read and parse a urlencoded request body</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">read_urlencoded_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">read_urlencoded_body</span></span>(<span style="color: #009900">Req</span>, #{})
-
-<span style="font-weight: bold"><span style="color: #000000">read_urlencoded_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>)
- <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Body</span>, <span style="color: #009900">Req</span>}
-
-<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body_opts</span></span>()
-<span style="color: #009900">Body</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #000080">true</span>}]</tt></pre></div></div>
-<div class="paragraph"><p>Read and parse a urlencoded request body.</p></div>
-<div class="paragraph"><p>This function reads the request body and parses it as
-<code>application/x-www-form-urlencoded</code>. It returns a list
-of key/values.</p></div>
-<div class="paragraph"><p>The urlencoded media type is used by Web browsers when
-submitting HTML forms using the POST method.</p></div>
-<div class="paragraph"><p>Cowboy needs to read the full body before parsing. By default
-it will read bodies of size up to 64KB. It is possible to
-provide options to read larger bodies if required.</p></div>
-<div class="paragraph"><p>Cowboy will automatically handle protocol details including
-the expect header, chunked transfer-encoding and others.</p></div>
-<div class="paragraph"><p>Once the body has been read, Cowboy sets the content-length
-header if it was not previously provided.</p></div>
-<div class="paragraph"><p>This function can only be called once. Calling it again will
-result in undefined behavior.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-<dt class="hdlist1">
-Opts
-</dt>
-<dd>
-<p>
-A map of body reading options. Please refer to
-<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>
-for details about each option.
-</p>
-<div class="paragraph"><p>This function defaults the <code>length</code> to 64KB and the <code>period</code>
-to 5 seconds.</p></div>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An <code>ok</code> tuple is returned containing a list of key/values found
-in the body.</p></div>
-<div class="paragraph"><p>The Req object returned in the tuple must be used for that point
-onward. It contains a more up to date representation of the request.
-For example it may have an added content-length header once the
-body has been read.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced. Replaces <code>body_qs/1,2</code>.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Read a urlencoded body</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: #FF6600">ok</span>, <span style="color: #009900">Body</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>, <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">Body</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Allow large urlencoded bodies</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: #FF6600">ok</span>, <span style="color: #009900">Body</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">1000000</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.has_body">cowboy_req:has_body(3)</a>,
-<a href="../cowboy_req.body_length">cowboy_req:body_length(3)</a>,
-<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>,
-<a href="../cowboy_req.read_part">cowboy_req:read_part(3)</a>,
-<a href="../cowboy_req.read_part_body">cowboy_req:read_part_body(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:read_urlencoded_body - Read and parse a urlencoded request body</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">read_urlencoded_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">read_urlencoded_body</span></span>(<span style="color: #009900">Req</span>, #{}) + +<span style="font-weight: bold"><span style="color: #000000">read_urlencoded_body</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>) + <span style="color: #990000">-></span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Body</span>, <span style="color: #009900">Req</span>} + +<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:read_body_opts</span></span>() +<span style="color: #009900">Body</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #000080">true</span>}]</tt></pre></div></div> +<div class="paragraph"><p>Read and parse a urlencoded request body.</p></div> +<div class="paragraph"><p>This function reads the request body and parses it as +<code>application/x-www-form-urlencoded</code>. It returns a list +of key/values.</p></div> +<div class="paragraph"><p>The urlencoded media type is used by Web browsers when +submitting HTML forms using the POST method.</p></div> +<div class="paragraph"><p>Cowboy needs to read the full body before parsing. By default +it will read bodies of size up to 64KB. It is possible to +provide options to read larger bodies if required.</p></div> +<div class="paragraph"><p>Cowboy will automatically handle protocol details including +the expect header, chunked transfer-encoding and others.</p></div> +<div class="paragraph"><p>Once the body has been read, Cowboy sets the content-length +header if it was not previously provided.</p></div> +<div class="paragraph"><p>This function can only be called once. Calling it again will +result in undefined behavior.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +<dt class="hdlist1"> +Opts +</dt> +<dd> +<p> +A map of body reading options. Please refer to +<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a> +for details about each option. +</p> +<div class="paragraph"><p>This function defaults the <code>length</code> to 64KB and the <code>period</code> +to 5 seconds.</p></div> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An <code>ok</code> tuple is returned containing a list of key/values found +in the body.</p></div> +<div class="paragraph"><p>The Req object returned in the tuple must be used for that point +onward. It contains a more up to date representation of the request. +For example it may have an added content-length header once the +body has been read.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Function introduced. Replaces <code>body_qs/1,2</code>. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Read a urlencoded body</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: #FF6600">ok</span>, <span style="color: #009900">Body</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>, <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">Body</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Allow large urlencoded bodies</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: #FF6600">ok</span>, <span style="color: #009900">Body</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">1000000</span>})<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.has_body">cowboy_req:has_body(3)</a>, +<a href="../cowboy_req.body_length">cowboy_req:body_length(3)</a>, +<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a>, +<a href="../cowboy_req.read_part">cowboy_req:read_part(3)</a>, +<a href="../cowboy_req.read_part_body">cowboy_req:read_part_body(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.reply/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.reply/index.html index 49b346dd..7f1fe714 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.reply/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.reply/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:reply(3)</title> @@ -67,164 +67,164 @@ <h1 class="lined-header"><span>cowboy_req:reply(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:reply - Send the response</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">reply</span></span>(<span style="color: #009900">Status</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">reply</span></span>(<span style="color: #009900">StatusCode</span>, #{}, <span style="color: #009900">Req</span>)
-
-<span style="font-weight: bold"><span style="color: #000000">reply</span></span>(<span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> <span style="color: #009900">Req</span>
-
-<span style="font-weight: bold"><span style="color: #000000">reply</span></span>(<span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Body</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> <span style="color: #009900">Req</span>
-
-<span style="color: #009900">Status</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_status</span></span>()
-<span style="color: #009900">Headers</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>()
-<span style="color: #009900">Body</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_body</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Send the response.</p></div>
-<div class="paragraph"><p>The header names must be given as lowercase binary strings.
-While header names are case insensitive, Cowboy requires them
-to be given as lowercase to function properly.</p></div>
-<div class="paragraph"><p>Cowboy does not allow duplicate header names. Headers set
-by this function may overwrite those set by <code>set_resp_header/3</code>
-and <code>set_resp_headers/2</code>.</p></div>
-<div class="paragraph"><p>Use <a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a>
-instead of this function to set cookies.</p></div>
-<div class="paragraph"><p>The <code>reply/2,3</code> functions will send the body set previously,
-if any. The <code>reply/4</code> function always sends the given body,
-overriding any previously set.</p></div>
-<div class="paragraph"><p>You do not need to set the content-length header when
-sending a response body. Cowboy takes care of it automatically.
-You should however provide a content-type header.</p></div>
-<div class="paragraph"><p>No further data can be transmitted after this function
-returns. This includes the push mechanism. Attempting to
-send two replies, or to push resources after a reply has
-been sent, will result in an error.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Status
-</dt>
-<dd>
-<p>
-The status code for the response.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers
-</dt>
-<dd>
-<p>
-The response headers.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Header names must be given as lowercase binary strings.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Body
-</dt>
-<dd>
-<p>
-The body can be either a binary value, an iolist or a
-<code>sendfile</code> tuple telling Cowboy to send the contents of
-a file.
-</p>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A new Req object is returned.</p></div>
-<div class="paragraph"><p>The returned Req object should be used from that point onward
-as it contains updated information about the state of the request.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the Req is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Reply</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">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">404</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Reply with custom headers</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">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">401</span>, #{
- <span style="color: #990000"><<</span><span style="color: #FF0000">"www-authenticate"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"Basic realm=\"erlang.org\""</span><span style="color: #990000">>></span>
-}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Reply with custom headers and a body</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">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: #FF0000">"Hello world!"</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a>,
-<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>,
-<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>,
-<a href="../cowboy_req.set_resp_body">cowboy_req:set_resp_body(3)</a>,
-<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a>,
-<a href="../cowboy_req.push">cowboy_req:push(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:reply - Send the response</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">reply</span></span>(<span style="color: #009900">Status</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">reply</span></span>(<span style="color: #009900">StatusCode</span>, #{}, <span style="color: #009900">Req</span>) + +<span style="font-weight: bold"><span style="color: #000000">reply</span></span>(<span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> <span style="color: #009900">Req</span> + +<span style="font-weight: bold"><span style="color: #000000">reply</span></span>(<span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Body</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> <span style="color: #009900">Req</span> + +<span style="color: #009900">Status</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_status</span></span>() +<span style="color: #009900">Headers</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>() +<span style="color: #009900">Body</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_body</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Send the response.</p></div> +<div class="paragraph"><p>The header names must be given as lowercase binary strings. +While header names are case insensitive, Cowboy requires them +to be given as lowercase to function properly.</p></div> +<div class="paragraph"><p>Cowboy does not allow duplicate header names. Headers set +by this function may overwrite those set by <code>set_resp_header/3</code> +and <code>set_resp_headers/2</code>.</p></div> +<div class="paragraph"><p>Use <a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a> +instead of this function to set cookies.</p></div> +<div class="paragraph"><p>The <code>reply/2,3</code> functions will send the body set previously, +if any. The <code>reply/4</code> function always sends the given body, +overriding any previously set.</p></div> +<div class="paragraph"><p>You do not need to set the content-length header when +sending a response body. Cowboy takes care of it automatically. +You should however provide a content-type header.</p></div> +<div class="paragraph"><p>No further data can be transmitted after this function +returns. This includes the push mechanism. Attempting to +send two replies, or to push resources after a reply has +been sent, will result in an error.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Status +</dt> +<dd> +<p> +The status code for the response. +</p> +</dd> +<dt class="hdlist1"> +Headers +</dt> +<dd> +<p> +The response headers. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Header names must be given as lowercase binary strings.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +Body +</dt> +<dd> +<p> +The body can be either a binary value, an iolist or a +<code>sendfile</code> tuple telling Cowboy to send the contents of +a file. +</p> +</dd> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A new Req object is returned.</p></div> +<div class="paragraph"><p>The returned Req object should be used from that point onward +as it contains updated information about the state of the request.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the Req is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Reply</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">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">404</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Reply with custom headers</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">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">401</span>, #{ + <span style="color: #990000"><<</span><span style="color: #FF0000">"www-authenticate"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"Basic realm=\"erlang.org\""</span><span style="color: #990000">>></span> +}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Reply with custom headers and a body</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">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: #FF0000">"Hello world!"</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a>, +<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>, +<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>, +<a href="../cowboy_req.set_resp_body">cowboy_req:set_resp_body(3)</a>, +<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a>, +<a href="../cowboy_req.push">cowboy_req:push(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.resp_header/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.resp_header/index.html index c210dd2f..0154a3e9 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.resp_header/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.resp_header/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:resp_header(3)</title> @@ -67,113 +67,113 @@ <h1 class="lined-header"><span>cowboy_req:resp_header(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:resp_header - Response header</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">resp_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">resp_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #000080">undefined</span>)
-<span style="font-weight: bold"><span style="color: #000000">resp_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">Default</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #009900">Default</span>
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span>
-<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return the value for the given response header.</p></div>
-<div class="paragraph"><p>The response header must have been set previously using
-<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a> or
-<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>.</p></div>
-<div class="paragraph"><p>The header name must be given as a lowercase binary string.
-While header names are case insensitive, Cowboy requires them
-to be given as lowercase to function properly.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name
-</dt>
-<dd>
-<p>
-Desired response header name as a lowercase binary string.
-</p>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-<dt class="hdlist1">
-Default
-</dt>
-<dd>
-<p>
-Default value returned when the header is missing.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The header value is returned as a binary string. When the
-header is missing, the default argument is returned.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get the content-type response header</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">Type</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_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="listingblock">
-<div class="title">Get the content-type response header with a default value</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">Type</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_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/html"</span><span style="color: #990000">>></span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.resp_headers">cowboy_req:resp_headers(3)</a>,
-<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>,
-<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:resp_header - Response header</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">resp_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">resp_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #000080">undefined</span>) +<span style="font-weight: bold"><span style="color: #000000">resp_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">Default</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #009900">Default</span> + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span> +<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return the value for the given response header.</p></div> +<div class="paragraph"><p>The response header must have been set previously using +<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a> or +<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>.</p></div> +<div class="paragraph"><p>The header name must be given as a lowercase binary string. +While header names are case insensitive, Cowboy requires them +to be given as lowercase to function properly.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name +</dt> +<dd> +<p> +Desired response header name as a lowercase binary string. +</p> +</dd> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +<dt class="hdlist1"> +Default +</dt> +<dd> +<p> +Default value returned when the header is missing. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The header value is returned as a binary string. When the +header is missing, the default argument is returned.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get the content-type response header</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">Type</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_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="listingblock"> +<div class="title">Get the content-type response header with a default value</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">Type</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_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/html"</span><span style="color: #990000">>></span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.resp_headers">cowboy_req:resp_headers(3)</a>, +<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>, +<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.resp_headers/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.resp_headers/index.html index 47e9dcca..731ef078 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.resp_headers/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.resp_headers/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:resp_headers(3)</title> @@ -67,79 +67,79 @@ <h1 class="lined-header"><span>cowboy_req:resp_headers(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:resp_headers - Response headers</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">resp_headers</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return all response headers.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Headers are returned as a map with keys being lowercase
-binary strings, and values as binary strings.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get all response headers</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">Headers</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_headers</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.resp_header">cowboy_req:resp_header(3)</a>,
-<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>,
-<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:resp_headers - Response headers</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">resp_headers</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return all response headers.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Headers are returned as a map with keys being lowercase +binary strings, and values as binary strings.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get all response headers</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">Headers</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_headers</span></span>(<span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.resp_header">cowboy_req:resp_header(3)</a>, +<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>, +<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.scheme/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.scheme/index.html index 12e1fb8b..cb8ea3b9 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.scheme/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.scheme/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:scheme(3)</title> @@ -67,89 +67,89 @@ <h1 class="lined-header"><span>cowboy_req:scheme(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:scheme - URI scheme</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">scheme</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Scheme</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return the scheme of the effective request URI.</p></div>
-<div class="paragraph"><p>The scheme can also be obtained using pattern matching:</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">scheme</span> <span style="color: #990000">:=</span> <span style="color: #009900">Scheme</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The scheme is returned as a binary. It is case insensitive.</p></div>
-<div class="paragraph"><p>Cowboy will only set the scheme to <code><<"http">></code> or <code><<"https">></code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Redirect HTTP to HTTPS</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="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">scheme</span> <span style="color: #990000">:=</span> <span style="color: #990000"><<</span><span style="color: #FF0000">"http"</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">302</span>, #{
- <span style="color: #990000"><<</span><span style="color: #FF0000">"location"</span><span style="color: #990000">>></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: #990000"><<</span><span style="color: #FF0000">"https"</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">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>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:scheme - URI scheme</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">scheme</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Scheme</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return the scheme of the effective request URI.</p></div> +<div class="paragraph"><p>The scheme can also be obtained using pattern matching:</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">scheme</span> <span style="color: #990000">:=</span> <span style="color: #009900">Scheme</span>} <span style="color: #990000">=</span> <span style="color: #009900">Req</span><span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The scheme is returned as a binary. It is case insensitive.</p></div> +<div class="paragraph"><p>Cowboy will only set the scheme to <code><<"http">></code> or <code><<"https">></code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Redirect HTTP to HTTPS</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="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">scheme</span> <span style="color: #990000">:=</span> <span style="color: #990000"><<</span><span style="color: #FF0000">"http"</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">302</span>, #{ + <span style="color: #990000"><<</span><span style="color: #FF0000">"location"</span><span style="color: #990000">>></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: #990000"><<</span><span style="color: #FF0000">"https"</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">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> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_body/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_body/index.html index 4720ee22..25b53626 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_body/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_body/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:set_resp_body(3)</title> @@ -67,138 +67,138 @@ <h1 class="lined-header"><span>cowboy_req:set_resp_body(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:set_resp_body - Set the response body</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">set_resp_body</span></span>(<span style="color: #009900">Body</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> <span style="color: #009900">Req</span>
-
-<span style="color: #009900">Body</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_body</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Set the response body.</p></div>
-<div class="paragraph"><p>The response body will be sent when a reply is initiated.
-Note that the functions <code>stream_reply/2,3</code> and <code>reply/4</code>
-will override the body set by this function.</p></div>
-<div class="paragraph"><p>This function can also be used to remove a response body
-that was set previously. To do so, simply call this function
-with an empty body.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Body
-</dt>
-<dd>
-<p>
-The body can be either a binary value, an iolist or a
-<code>sendfile</code> tuple telling Cowboy to send the contents of
-a file.
-</p>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A new Req object is returned.</p></div>
-<div class="paragraph"><p>The returned Req object must be used from that point onward,
-otherwise the body will not be sent in the response.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: The function now accepts a <code>sendfile</code> tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: The <code>set_resp_body_fun/2,3</code> functions were removed.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Set the response body</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_body</span></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: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Set the response body as an iolist</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_body</span></span>([
- <span style="color: #FF0000">"<html><head><title>"</span>,
- <span style="font-weight: bold"><span style="color: #000000">page_title</span></span>(),
- <span style="color: #FF0000">"</title></head><body>"</span>,
- <span style="font-weight: bold"><span style="color: #000000">page_body</span></span>(),
- <span style="color: #FF0000">"</body></html>"</span>
-], <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Tell Cowboy to send data from a file</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: #FF6600">ok</span>, <span style="color: #008080">#file_info</span>{<span style="font-weight: bold"><span style="color: #000080">size</span></span><span style="color: #990000">=</span><span style="color: #009900">Size</span>}} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:read_file_info</span></span>(<span style="color: #009900">Filename</span>),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_body</span></span>({<span style="color: #FF6600">sendfile</span>, <span style="color: #993399">0</span>, <span style="color: #009900">Size</span>, <span style="color: #009900">Filename</span>}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Clear any previously set response body</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_body</span></span>(<span style="color: #990000"><<>></span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>,
-<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>,
-<a href="../cowboy_req.reply">cowboy_req:reply(3)</a>,
-<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:set_resp_body - Set the response body</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">set_resp_body</span></span>(<span style="color: #009900">Body</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> <span style="color: #009900">Req</span> + +<span style="color: #009900">Body</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_body</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Set the response body.</p></div> +<div class="paragraph"><p>The response body will be sent when a reply is initiated. +Note that the functions <code>stream_reply/2,3</code> and <code>reply/4</code> +will override the body set by this function.</p></div> +<div class="paragraph"><p>This function can also be used to remove a response body +that was set previously. To do so, simply call this function +with an empty body.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Body +</dt> +<dd> +<p> +The body can be either a binary value, an iolist or a +<code>sendfile</code> tuple telling Cowboy to send the contents of +a file. +</p> +</dd> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A new Req object is returned.</p></div> +<div class="paragraph"><p>The returned Req object must be used from that point onward, +otherwise the body will not be sent in the response.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: The function now accepts a <code>sendfile</code> tuple. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: The <code>set_resp_body_fun/2,3</code> functions were removed. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Set the response body</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_body</span></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: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Set the response body as an iolist</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_body</span></span>([ + <span style="color: #FF0000">"<html><head><title>"</span>, + <span style="font-weight: bold"><span style="color: #000000">page_title</span></span>(), + <span style="color: #FF0000">"</title></head><body>"</span>, + <span style="font-weight: bold"><span style="color: #000000">page_body</span></span>(), + <span style="color: #FF0000">"</body></html>"</span> +], <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Tell Cowboy to send data from a file</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: #FF6600">ok</span>, <span style="color: #008080">#file_info</span>{<span style="font-weight: bold"><span style="color: #000080">size</span></span><span style="color: #990000">=</span><span style="color: #009900">Size</span>}} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:read_file_info</span></span>(<span style="color: #009900">Filename</span>), +<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_body</span></span>({<span style="color: #FF6600">sendfile</span>, <span style="color: #993399">0</span>, <span style="color: #009900">Size</span>, <span style="color: #009900">Filename</span>}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Clear any previously set response body</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_body</span></span>(<span style="color: #990000"><<>></span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>, +<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>, +<a href="../cowboy_req.reply">cowboy_req:reply(3)</a>, +<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_cookie/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_cookie/index.html index b080f69b..f77c91e3 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_cookie/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_cookie/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:set_resp_cookie(3)</title> @@ -67,167 +67,167 @@ <h1 class="lined-header"><span>cowboy_req:set_resp_cookie(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:set_resp_cookie - Set a cookie</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">set_resp_cookie</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">set_resp_cookie</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>, [], <span style="color: #009900">Req</span>)
-
-<span style="font-weight: bold"><span style="color: #000000">set_resp_cookie</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>)
- <span style="color: #990000">-></span> <span style="color: #009900">Req</span>
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
-<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
-<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cow_cookie:cookie_opts</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Set a cookie to be sent with the response.</p></div>
-<div class="paragraph"><p>Note that cookie names are case sensitive.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name
-</dt>
-<dd>
-<p>
-Cookie name.
-</p>
-</dd>
-<dt class="hdlist1">
-Value
-</dt>
-<dd>
-<p>
-Cookie value.
-</p>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-<dt class="hdlist1">
-Opts
-</dt>
-<dd>
-<p>
-Cookie options.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A new Req object is returned.</p></div>
-<div class="paragraph"><p>The returned Req object must be used from that point onward,
-otherwise the cookie will not be sent in the response.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: <code>set_resp_cookie/3</code> introduced as an alias to <code>set_resp_cookie/4</code> with no options.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: The first argument type is now <code>binary()</code> instead of <code>iodata()</code>.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Set a session cookie</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">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">base64:encode</span></span>(<span style="font-weight: bold"><span style="color: #000000">crypto:strong_rand_bytes</span></span>(<span style="color: #993399">32</span>)),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Set a cookie with an expiration time</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"lang"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"fr-FR"</span><span style="color: #990000">>></span>,
- <span style="color: #009900">Req0</span>, #{<span style="color: #0000FF">max_age</span> <span style="color: #990000">=></span> <span style="color: #993399">3600</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Delete a cookie</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<>></span>,
- <span style="color: #009900">Req0</span>, #{<span style="color: #0000FF">max_age</span> <span style="color: #990000">=></span> <span style="color: #993399">0</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Set a cookie for a specific domain and path</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"inaccount"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"1"</span><span style="color: #990000">>></span>,
- <span style="color: #009900">Req0</span>, #{<span style="color: #0000FF">domain</span> <span style="color: #990000">=></span> <span style="color: #FF0000">"my.example.org"</span>, <span style="color: #0000FF">path</span> <span style="color: #990000">=></span> <span style="color: #FF0000">"/account"</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Restrict a cookie to HTTPS</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">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">base64:encode</span></span>(<span style="font-weight: bold"><span style="color: #000000">crypto:strong_rand_bytes</span></span>(<span style="color: #993399">32</span>)),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>,
- <span style="color: #009900">Req0</span>, #{<span style="color: #0000FF">secure</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Restrict a cookie to HTTP</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">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">base64:encode</span></span>(<span style="font-weight: bold"><span style="color: #000000">crypto:strong_rand_bytes</span></span>(<span style="color: #993399">32</span>)),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>,
- <span style="color: #009900">Req0</span>, #{<span style="color: #0000FF">http_only</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>,
-<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>,
-<a href="../cowboy_req.reply">cowboy_req:reply(3)</a>,
-<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:set_resp_cookie - Set a cookie</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">set_resp_cookie</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">set_resp_cookie</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>, [], <span style="color: #009900">Req</span>) + +<span style="font-weight: bold"><span style="color: #000000">set_resp_cookie</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>) + <span style="color: #990000">-></span> <span style="color: #009900">Req</span> + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> +<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> +<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cow_cookie:cookie_opts</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Set a cookie to be sent with the response.</p></div> +<div class="paragraph"><p>Note that cookie names are case sensitive.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name +</dt> +<dd> +<p> +Cookie name. +</p> +</dd> +<dt class="hdlist1"> +Value +</dt> +<dd> +<p> +Cookie value. +</p> +</dd> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +<dt class="hdlist1"> +Opts +</dt> +<dd> +<p> +Cookie options. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A new Req object is returned.</p></div> +<div class="paragraph"><p>The returned Req object must be used from that point onward, +otherwise the cookie will not be sent in the response.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: <code>set_resp_cookie/3</code> introduced as an alias to <code>set_resp_cookie/4</code> with no options. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: The first argument type is now <code>binary()</code> instead of <code>iodata()</code>. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Set a session cookie</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">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">base64:encode</span></span>(<span style="font-weight: bold"><span style="color: #000000">crypto:strong_rand_bytes</span></span>(<span style="color: #993399">32</span>)), +<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Set a cookie with an expiration time</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"lang"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"fr-FR"</span><span style="color: #990000">>></span>, + <span style="color: #009900">Req0</span>, #{<span style="color: #0000FF">max_age</span> <span style="color: #990000">=></span> <span style="color: #993399">3600</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Delete a cookie</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<>></span>, + <span style="color: #009900">Req0</span>, #{<span style="color: #0000FF">max_age</span> <span style="color: #990000">=></span> <span style="color: #993399">0</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Set a cookie for a specific domain and path</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"inaccount"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"1"</span><span style="color: #990000">>></span>, + <span style="color: #009900">Req0</span>, #{<span style="color: #0000FF">domain</span> <span style="color: #990000">=></span> <span style="color: #FF0000">"my.example.org"</span>, <span style="color: #0000FF">path</span> <span style="color: #990000">=></span> <span style="color: #FF0000">"/account"</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Restrict a cookie to HTTPS</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">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">base64:encode</span></span>(<span style="font-weight: bold"><span style="color: #000000">crypto:strong_rand_bytes</span></span>(<span style="color: #993399">32</span>)), +<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, + <span style="color: #009900">Req0</span>, #{<span style="color: #0000FF">secure</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Restrict a cookie to HTTP</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">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">base64:encode</span></span>(<span style="font-weight: bold"><span style="color: #000000">crypto:strong_rand_bytes</span></span>(<span style="color: #993399">32</span>)), +<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">>></span>, <span style="color: #009900">SessionID</span>, + <span style="color: #009900">Req0</span>, #{<span style="color: #0000FF">http_only</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>})<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>, +<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>, +<a href="../cowboy_req.reply">cowboy_req:reply(3)</a>, +<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_header/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_header/index.html index 1fe9aa82..6f9d80cf 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_header/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_header/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:set_resp_header(3)</title> @@ -67,121 +67,121 @@ <h1 class="lined-header"><span>cowboy_req:set_resp_header(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:set_resp_header - Set a response header</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">set_resp_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> <span style="color: #009900">Req</span>
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span>
-<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case depends on header</span></span></tt></pre></div></div>
-<div class="paragraph"><p>Set a header to be sent with the response.</p></div>
-<div class="paragraph"><p>The header name must be given as a lowercase binary string.
-While header names are case insensitive, Cowboy requires them
-to be given as lowercase to function properly.</p></div>
-<div class="paragraph"><p>Cowboy does not allow duplicate header names. Headers set
-by this function may be overwritten by those set from the
-reply functions.</p></div>
-<div class="paragraph"><p>Use <a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a>
-instead of this function to set cookies.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name
-</dt>
-<dd>
-<p>
-Header name as a lowercase binary string.
-</p>
-</dd>
-<dt class="hdlist1">
-Value
-</dt>
-<dd>
-<p>
-Header value.
-</p>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A new Req object is returned.</p></div>
-<div class="paragraph"><p>The returned Req object must be used from that point onward,
-otherwise the header will not be sent in the response.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Set a header in the response</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">Req</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">"allow"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"GET"</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Construct a header using iolists</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">Req</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">"allow"</span><span style="color: #990000">>></span>,
- [<span style="font-weight: bold"><span style="color: #000000">allowed_methods</span></span>(), <span style="color: #FF0000">", OPTIONS"</span>], <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a>,
-<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>,
-<a href="../cowboy_req.has_resp_header">cowboy_req:has_resp_header(3)</a>,
-<a href="../cowboy_req.resp_header">cowboy_req:resp_header(3)</a>,
-<a href="../cowboy_req.resp_headers">cowboy_req:resp_headers(3)</a>,
-<a href="../cowboy_req.delete_resp_header">cowboy_req:delete_resp_header(3)</a>,
-<a href="../cowboy_req.reply">cowboy_req:reply(3)</a>,
-<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:set_resp_header - Set a response header</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">set_resp_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> <span style="color: #009900">Req</span> + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span> +<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case depends on header</span></span></tt></pre></div></div> +<div class="paragraph"><p>Set a header to be sent with the response.</p></div> +<div class="paragraph"><p>The header name must be given as a lowercase binary string. +While header names are case insensitive, Cowboy requires them +to be given as lowercase to function properly.</p></div> +<div class="paragraph"><p>Cowboy does not allow duplicate header names. Headers set +by this function may be overwritten by those set from the +reply functions.</p></div> +<div class="paragraph"><p>Use <a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a> +instead of this function to set cookies.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name +</dt> +<dd> +<p> +Header name as a lowercase binary string. +</p> +</dd> +<dt class="hdlist1"> +Value +</dt> +<dd> +<p> +Header value. +</p> +</dd> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A new Req object is returned.</p></div> +<div class="paragraph"><p>The returned Req object must be used from that point onward, +otherwise the header will not be sent in the response.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Set a header in the response</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">Req</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">"allow"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"GET"</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Construct a header using iolists</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">Req</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">"allow"</span><span style="color: #990000">>></span>, + [<span style="font-weight: bold"><span style="color: #000000">allowed_methods</span></span>(), <span style="color: #FF0000">", OPTIONS"</span>], <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a>, +<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>, +<a href="../cowboy_req.has_resp_header">cowboy_req:has_resp_header(3)</a>, +<a href="../cowboy_req.resp_header">cowboy_req:resp_header(3)</a>, +<a href="../cowboy_req.resp_headers">cowboy_req:resp_headers(3)</a>, +<a href="../cowboy_req.delete_resp_header">cowboy_req:delete_resp_header(3)</a>, +<a href="../cowboy_req.reply">cowboy_req:reply(3)</a>, +<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_headers/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_headers/index.html index e55c1223..5a60c156 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_headers/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_headers/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:set_resp_headers(3)</title> @@ -67,109 +67,109 @@ <h1 class="lined-header"><span>cowboy_req:set_resp_headers(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:set_resp_headers - Set several response headers</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">set_resp_headers</span></span>(<span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> <span style="color: #009900">Req</span>
-
-<span style="color: #009900">Headers</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Set several headers to be sent with the response.</p></div>
-<div class="paragraph"><p>The header name must be given as a lowercase binary string.
-While header names are case insensitive, Cowboy requires them
-to be given as lowercase to function properly.</p></div>
-<div class="paragraph"><p>Cowboy does not allow duplicate header names. Headers set
-by this function may be overwritten by those set from the
-reply functions. Likewise, headers set by this function may
-overwrite headers that were set previously.</p></div>
-<div class="paragraph"><p>Use <a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a>
-instead of this function to set cookies.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Headers
-</dt>
-<dd>
-<p>
-Headers as a map with keys being lowercase binary strings,
-and values as binary strings.
-</p>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A new Req object is returned.</p></div>
-<div class="paragraph"><p>The returned Req object must be used from that point onward,
-otherwise the headers will not be sent in the response.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Set several response headers</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_headers</span></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/html"</span><span style="color: #990000">>></span>,
- <span style="color: #990000"><<</span><span style="color: #FF0000">"content-encoding"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"gzip"</span><span style="color: #990000">>></span>
-}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a>,
-<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>,
-<a href="../cowboy_req.has_resp_header">cowboy_req:has_resp_header(3)</a>,
-<a href="../cowboy_req.resp_header">cowboy_req:resp_header(3)</a>,
-<a href="../cowboy_req.resp_headers">cowboy_req:resp_headers(3)</a>,
-<a href="../cowboy_req.delete_resp_header">cowboy_req:delete_resp_header(3)</a>,
-<a href="../cowboy_req.reply">cowboy_req:reply(3)</a>,
-<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:set_resp_headers - Set several response headers</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">set_resp_headers</span></span>(<span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> <span style="color: #009900">Req</span> + +<span style="color: #009900">Headers</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Set several headers to be sent with the response.</p></div> +<div class="paragraph"><p>The header name must be given as a lowercase binary string. +While header names are case insensitive, Cowboy requires them +to be given as lowercase to function properly.</p></div> +<div class="paragraph"><p>Cowboy does not allow duplicate header names. Headers set +by this function may be overwritten by those set from the +reply functions. Likewise, headers set by this function may +overwrite headers that were set previously.</p></div> +<div class="paragraph"><p>Use <a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a> +instead of this function to set cookies.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Headers +</dt> +<dd> +<p> +Headers as a map with keys being lowercase binary strings, +and values as binary strings. +</p> +</dd> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A new Req object is returned.</p></div> +<div class="paragraph"><p>The returned Req object must be used from that point onward, +otherwise the headers will not be sent in the response.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Set several response headers</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_headers</span></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/html"</span><span style="color: #990000">>></span>, + <span style="color: #990000"><<</span><span style="color: #FF0000">"content-encoding"</span><span style="color: #990000">>></span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"gzip"</span><span style="color: #990000">>></span> +}, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a>, +<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>, +<a href="../cowboy_req.has_resp_header">cowboy_req:has_resp_header(3)</a>, +<a href="../cowboy_req.resp_header">cowboy_req:resp_header(3)</a>, +<a href="../cowboy_req.resp_headers">cowboy_req:resp_headers(3)</a>, +<a href="../cowboy_req.delete_resp_header">cowboy_req:delete_resp_header(3)</a>, +<a href="../cowboy_req.reply">cowboy_req:reply(3)</a>, +<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.stream_body/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.stream_body/index.html index 2a8651cb..1753c362 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.stream_body/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.stream_body/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:stream_body(3)</title> @@ -67,116 +67,116 @@ <h1 class="lined-header"><span>cowboy_req:stream_body(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:stream_body - Stream the response body</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">stream_body</span></span>(<span style="color: #009900">Data</span>, <span style="color: #009900">IsFin</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span>
-
-<span style="color: #009900">Data</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()
-<span style="color: #009900">IsFin</span> <span style="color: #990000">::</span> <span style="color: #FF6600">fin</span> | <span style="color: #FF6600">nofin</span></tt></pre></div></div>
-<div class="paragraph"><p>Stream the response body.</p></div>
-<div class="paragraph"><p>This function may be called as many times as needed after
-initiating a response using the
-<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a>
-function.</p></div>
-<div class="paragraph"><p>The second argument indicates if this call is the final
-call. Use the <code>nofin</code> value until you know no more data
-will be sent. The final call should use <code>fin</code> (possibly
-with an empty data value).</p></div>
-<div class="paragraph"><p>Note that not using <code>fin</code> for the final call is not an
-error; Cowboy will take care of it when the request
-handler terminates if needed. Depending on the resource
-it may however be more efficient to do it as early as
-possible.</p></div>
-<div class="paragraph"><p>You do not need to handle HEAD requests specifically as
-Cowboy will ensure no data is sent when you call this function.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Data
-</dt>
-<dd>
-<p>
-The data to be sent.
-</p>
-</dd>
-<dt class="hdlist1">
-IsFin
-</dt>
-<dd>
-<p>
-A flag indicating whether this is the final piece of data
-to be sent.
-</p>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The atom <code>ok</code> is always returned. It can be safely ignored.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced. Replaces <code>chunk/2</code>.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Stream the response body</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_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: #009900">Req0</span>),
-<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"Hello\n"</span><span style="color: #990000">>></span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Req</span>),
-<span style="font-weight: bold"><span style="color: #000000">timer:sleep</span></span>(<span style="color: #993399">1000</span>),
-<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"World!\n"</span><span style="color: #990000">>></span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:stream_body - Stream the response body</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">stream_body</span></span>(<span style="color: #009900">Data</span>, <span style="color: #009900">IsFin</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span> + +<span style="color: #009900">Data</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() +<span style="color: #009900">IsFin</span> <span style="color: #990000">::</span> <span style="color: #FF6600">fin</span> | <span style="color: #FF6600">nofin</span></tt></pre></div></div> +<div class="paragraph"><p>Stream the response body.</p></div> +<div class="paragraph"><p>This function may be called as many times as needed after +initiating a response using the +<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a> +function.</p></div> +<div class="paragraph"><p>The second argument indicates if this call is the final +call. Use the <code>nofin</code> value until you know no more data +will be sent. The final call should use <code>fin</code> (possibly +with an empty data value).</p></div> +<div class="paragraph"><p>Note that not using <code>fin</code> for the final call is not an +error; Cowboy will take care of it when the request +handler terminates if needed. Depending on the resource +it may however be more efficient to do it as early as +possible.</p></div> +<div class="paragraph"><p>You do not need to handle HEAD requests specifically as +Cowboy will ensure no data is sent when you call this function.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Data +</dt> +<dd> +<p> +The data to be sent. +</p> +</dd> +<dt class="hdlist1"> +IsFin +</dt> +<dd> +<p> +A flag indicating whether this is the final piece of data +to be sent. +</p> +</dd> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The atom <code>ok</code> is always returned. It can be safely ignored.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Function introduced. Replaces <code>chunk/2</code>. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Stream the response body</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_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: #009900">Req0</span>), +<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"Hello\n"</span><span style="color: #990000">>></span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Req</span>), +<span style="font-weight: bold"><span style="color: #000000">timer:sleep</span></span>(<span style="color: #993399">1000</span>), +<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"World!\n"</span><span style="color: #990000">>></span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.stream_reply/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.stream_reply/index.html index 0c3dc711..a2b9bef1 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.stream_reply/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.stream_reply/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:stream_reply(3)</title> @@ -67,148 +67,148 @@ <h1 class="lined-header"><span>cowboy_req:stream_reply(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:stream_reply - Send the response headers</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">stream_reply</span></span>(<span style="color: #009900">Status</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">stream_reply</span></span>(<span style="color: #009900">StatusCode</span>, #{}, <span style="color: #009900">Req</span>)
-
-<span style="font-weight: bold"><span style="color: #000000">stream_reply</span></span>(<span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>())
- <span style="color: #990000">-></span> <span style="color: #009900">Req</span>
-
-<span style="color: #009900">Status</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_status</span></span>()
-<span style="color: #009900">Headers</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Send the response headers.</p></div>
-<div class="paragraph"><p>The header names must be given as lowercase binary strings.
-While header names are case insensitive, Cowboy requires them
-to be given as lowercase to function properly.</p></div>
-<div class="paragraph"><p>Cowboy does not allow duplicate header names. Headers set
-by this function may overwrite those set by <code>set_resp_header/3</code>.</p></div>
-<div class="paragraph"><p>Use <a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a>
-instead of this function to set cookies.</p></div>
-<div class="paragraph"><p>If a response body was set before calling this function,
-it will not be sent.</p></div>
-<div class="paragraph"><p>Use <a href="../cowboy_req.stream_body">cowboy_req:stream_body(3)</a>
-to stream the response body.</p></div>
-<div class="paragraph"><p>You may want to set the content-length header when using
-this function, if it is known in advance. This will allow
-clients using HTTP/2 and HTTP/1.0 to process the response
-more efficiently.</p></div>
-<div class="paragraph"><p>The streaming method varies depending on the protocol being
-used. HTTP/2 will use the usual DATA frames. HTTP/1.1 will
-use chunked transfer-encoding. HTTP/1.0 will send the body
-unmodified and close the connection at the end if no
-content-length was set.</p></div>
-<div class="paragraph"><p>It is not possible to push resources after this function
-returns. Any attempt will result in an error.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Status
-</dt>
-<dd>
-<p>
-The status code for the response.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers
-</dt>
-<dd>
-<p>
-The response headers.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Header names must be given as lowercase binary strings.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A new Req object is returned.</p></div>
-<div class="paragraph"><p>The returned Req object must be used from that point onward
-in order to be able to stream the response body.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the Req is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced. Replaces <code>chunked_reply/1,2</code>.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Initiate the response</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_reply</span></span>(<span style="color: #993399">200</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Stream the response with custom headers</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_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: #009900">Req0</span>),
-<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"Hello\n"</span><span style="color: #990000">>></span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Req</span>),
-<span style="font-weight: bold"><span style="color: #000000">timer:sleep</span></span>(<span style="color: #993399">1000</span>),
-<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"World!\n"</span><span style="color: #990000">>></span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a>,
-<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>,
-<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>,
-<a href="../cowboy_req.reply">cowboy_req:reply(3)</a>,
-<a href="../cowboy_req.stream_body">cowboy_req:stream_body(3)</a>,
-<a href="../cowboy_req.push">cowboy_req:push(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:stream_reply - Send the response headers</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">stream_reply</span></span>(<span style="color: #009900">Status</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">stream_reply</span></span>(<span style="color: #009900">StatusCode</span>, #{}, <span style="color: #009900">Req</span>) + +<span style="font-weight: bold"><span style="color: #000000">stream_reply</span></span>(<span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>, <span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) + <span style="color: #990000">-></span> <span style="color: #009900">Req</span> + +<span style="color: #009900">Status</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_status</span></span>() +<span style="color: #009900">Headers</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Send the response headers.</p></div> +<div class="paragraph"><p>The header names must be given as lowercase binary strings. +While header names are case insensitive, Cowboy requires them +to be given as lowercase to function properly.</p></div> +<div class="paragraph"><p>Cowboy does not allow duplicate header names. Headers set +by this function may overwrite those set by <code>set_resp_header/3</code>.</p></div> +<div class="paragraph"><p>Use <a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a> +instead of this function to set cookies.</p></div> +<div class="paragraph"><p>If a response body was set before calling this function, +it will not be sent.</p></div> +<div class="paragraph"><p>Use <a href="../cowboy_req.stream_body">cowboy_req:stream_body(3)</a> +to stream the response body.</p></div> +<div class="paragraph"><p>You may want to set the content-length header when using +this function, if it is known in advance. This will allow +clients using HTTP/2 and HTTP/1.0 to process the response +more efficiently.</p></div> +<div class="paragraph"><p>The streaming method varies depending on the protocol being +used. HTTP/2 will use the usual DATA frames. HTTP/1.1 will +use chunked transfer-encoding. HTTP/1.0 will send the body +unmodified and close the connection at the end if no +content-length was set.</p></div> +<div class="paragraph"><p>It is not possible to push resources after this function +returns. Any attempt will result in an error.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Status +</dt> +<dd> +<p> +The status code for the response. +</p> +</dd> +<dt class="hdlist1"> +Headers +</dt> +<dd> +<p> +The response headers. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Header names must be given as lowercase binary strings.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A new Req object is returned.</p></div> +<div class="paragraph"><p>The returned Req object must be used from that point onward +in order to be able to stream the response body.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the Req is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: Function introduced. Replaces <code>chunked_reply/1,2</code>. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Initiate the response</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_reply</span></span>(<span style="color: #993399">200</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Stream the response with custom headers</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">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_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: #009900">Req0</span>), +<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"Hello\n"</span><span style="color: #990000">>></span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Req</span>), +<span style="font-weight: bold"><span style="color: #000000">timer:sleep</span></span>(<span style="color: #993399">1000</span>), +<span style="font-weight: bold"><span style="color: #000000">cowboy_req:stream_body</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"World!\n"</span><span style="color: #990000">>></span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a>, +<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a>, +<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a>, +<a href="../cowboy_req.reply">cowboy_req:reply(3)</a>, +<a href="../cowboy_req.stream_body">cowboy_req:stream_body(3)</a>, +<a href="../cowboy_req.push">cowboy_req:push(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.uri/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.uri/index.html index dcfc1bd2..98e3e2b2 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.uri/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.uri/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:uri(3)</title> @@ -67,177 +67,177 @@ <h1 class="lined-header"><span>cowboy_req:uri(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:uri - Reconstructed URI</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">uri</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">uri</span></span>(<span style="color: #009900">Req</span>, #{})
-<span style="font-weight: bold"><span style="color: #000000">uri</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span> <span style="color: #009900">URI</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()
-
-<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> #{
- <span style="color: #0000FF">scheme</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() | <span style="color: #000080">undefined</span>,
- <span style="color: #0000FF">host</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() | <span style="color: #000080">undefined</span>,
- <span style="color: #0000FF">port</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>() | <span style="color: #000080">undefined</span>,
- <span style="color: #0000FF">path</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() | <span style="color: #000080">undefined</span>,
- <span style="color: #0000FF">qs</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() | <span style="color: #000080">undefined</span>,
- <span style="color: #0000FF">fragment</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() | <span style="color: #000080">undefined</span>
-}</tt></pre></div></div>
-<div class="paragraph"><p>Reconstruct the effective request URI, optionally modifying components.</p></div>
-<div class="paragraph"><p>By default Cowboy will build a URI using the components found
-in the request. Options allow disabling or replacing individual
-components.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-<dt class="hdlist1">
-Opts
-</dt>
-<dd>
-<p>
-Map for overriding individual components.
-</p>
-<div class="paragraph"><p>To replace a component, provide its new value as a binary
-string or an iolist. To disable a component, set its value
-to <code>undefined</code>.</p></div>
-<div class="paragraph"><p>As this function always returns a valid URI, there are some
-things to note:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Disabling the host also disables the scheme and port.
-</p>
-</li>
-<li>
-<p>
-There is no fragment component by default as these are
- not sent with the request.
-</p>
-</li>
-<li>
-<p>
-The port number may not appear in the resulting URI if
- it is the default port for the given scheme (http: 80; https: 443).
-</p>
-</li>
-</ul></div>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The reconstructed URI is returned as an iolist or a binary string.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Individual components can be replaced or disabled.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: Only the URI is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced. Replaces <code>host_url/1</code> and <code>url/1</code>.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>With an effective request URI <a href="http://example.org/path/to/res?edit=1">http://example.org/path/to/res?edit=1</a>
-we can have:</p></div>
-<div class="listingblock">
-<div class="title">Protocol relative form</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="font-style: italic"><span style="color: #9A1900">%% //example.org/path/to/res?edit=1</span></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="listingblock">
-<div class="title">Serialized origin for use in the origin header</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="font-style: italic"><span style="color: #9A1900">%% </span></span><span style="text-decoration: underline"><span style="color: #0000FF">http://example.org</span></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">path</span> <span style="color: #990000">=></span> <span style="color: #000080">undefined</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="listingblock">
-<div class="title">HTTP/1.1 origin form (path and query string only)</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="font-style: italic"><span style="color: #9A1900">%% /path/to/res?edit=1</span></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="listingblock">
-<div class="title">Add a fragment to the URI</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="font-style: italic"><span style="color: #9A1900">%% </span></span><span style="text-decoration: underline"><span style="color: #0000FF">http://example.org/path/to/res</span></span><span style="font-style: italic"><span style="color: #9A1900">?edit=1#errors</span></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">fragment</span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"errors"</span><span style="color: #990000">>></span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Ensure the scheme is HTTPS</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="font-style: italic"><span style="color: #9A1900">%% </span></span><span style="text-decoration: underline"><span style="color: #0000FF">https://example.org/path/to/res</span></span><span style="font-style: italic"><span style="color: #9A1900">?edit=1</span></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: #990000"><<</span><span style="color: #FF0000">"https"</span><span style="color: #990000">>></span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Convert the URI to a binary string</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="font-weight: bold"><span style="color: #000000">iolist_to_binary</span></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>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.scheme">cowboy_req:scheme(3)</a>,
-<a href="../cowboy_req.host">cowboy_req:host(3)</a>,
-<a href="../cowboy_req.port">cowboy_req:port(3)</a>,
-<a href="../cowboy_req.path">cowboy_req:path(3)</a>,
-<a href="../cowboy_req.qs">cowboy_req:qs(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:uri - Reconstructed URI</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">uri</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">uri</span></span>(<span style="color: #009900">Req</span>, #{}) +<span style="font-weight: bold"><span style="color: #000000">uri</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span> <span style="color: #009900">URI</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() + +<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> #{ + <span style="color: #0000FF">scheme</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() | <span style="color: #000080">undefined</span>, + <span style="color: #0000FF">host</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() | <span style="color: #000080">undefined</span>, + <span style="color: #0000FF">port</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>() | <span style="color: #000080">undefined</span>, + <span style="color: #0000FF">path</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() | <span style="color: #000080">undefined</span>, + <span style="color: #0000FF">qs</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() | <span style="color: #000080">undefined</span>, + <span style="color: #0000FF">fragment</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() | <span style="color: #000080">undefined</span> +}</tt></pre></div></div> +<div class="paragraph"><p>Reconstruct the effective request URI, optionally modifying components.</p></div> +<div class="paragraph"><p>By default Cowboy will build a URI using the components found +in the request. Options allow disabling or replacing individual +components.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +<dt class="hdlist1"> +Opts +</dt> +<dd> +<p> +Map for overriding individual components. +</p> +<div class="paragraph"><p>To replace a component, provide its new value as a binary +string or an iolist. To disable a component, set its value +to <code>undefined</code>.</p></div> +<div class="paragraph"><p>As this function always returns a valid URI, there are some +things to note:</p></div> +<div class="ulist"><ul> +<li> +<p> +Disabling the host also disables the scheme and port. +</p> +</li> +<li> +<p> +There is no fragment component by default as these are + not sent with the request. +</p> +</li> +<li> +<p> +The port number may not appear in the resulting URI if + it is the default port for the given scheme (http: 80; https: 443). +</p> +</li> +</ul></div> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The reconstructed URI is returned as an iolist or a binary string.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Individual components can be replaced or disabled. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: Only the URI is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: Function introduced. Replaces <code>host_url/1</code> and <code>url/1</code>. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="paragraph"><p>With an effective request URI <a href="http://example.org/path/to/res?edit=1">http://example.org/path/to/res?edit=1</a> +we can have:</p></div> +<div class="listingblock"> +<div class="title">Protocol relative form</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="font-style: italic"><span style="color: #9A1900">%% //example.org/path/to/res?edit=1</span></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="listingblock"> +<div class="title">Serialized origin for use in the origin header</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="font-style: italic"><span style="color: #9A1900">%% </span></span><span style="text-decoration: underline"><span style="color: #0000FF">http://example.org</span></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">path</span> <span style="color: #990000">=></span> <span style="color: #000080">undefined</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="listingblock"> +<div class="title">HTTP/1.1 origin form (path and query string only)</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="font-style: italic"><span style="color: #9A1900">%% /path/to/res?edit=1</span></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="listingblock"> +<div class="title">Add a fragment to the URI</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="font-style: italic"><span style="color: #9A1900">%% </span></span><span style="text-decoration: underline"><span style="color: #0000FF">http://example.org/path/to/res</span></span><span style="font-style: italic"><span style="color: #9A1900">?edit=1#errors</span></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">fragment</span> <span style="color: #990000">=></span> <span style="color: #990000"><<</span><span style="color: #FF0000">"errors"</span><span style="color: #990000">>></span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Ensure the scheme is HTTPS</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="font-style: italic"><span style="color: #9A1900">%% </span></span><span style="text-decoration: underline"><span style="color: #0000FF">https://example.org/path/to/res</span></span><span style="font-style: italic"><span style="color: #9A1900">?edit=1</span></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: #990000"><<</span><span style="color: #FF0000">"https"</span><span style="color: #990000">>></span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Convert the URI to a binary string</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="font-weight: bold"><span style="color: #000000">iolist_to_binary</span></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> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.scheme">cowboy_req:scheme(3)</a>, +<a href="../cowboy_req.host">cowboy_req:host(3)</a>, +<a href="../cowboy_req.port">cowboy_req:port(3)</a>, +<a href="../cowboy_req.path">cowboy_req:path(3)</a>, +<a href="../cowboy_req.qs">cowboy_req:qs(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.version/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.version/index.html index 4fb572fa..313b06af 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.version/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.version/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:version(3)</title> @@ -67,88 +67,88 @@ <h1 class="lined-header"><span>cowboy_req:version(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:version - HTTP version</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">version</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Version</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_version</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Return the HTTP version used for the request.</p></div>
-<div class="paragraph"><p>The version can also be obtained using pattern matching:</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">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>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The HTTP version used for the request is returned as an
-atom. It is provided for informative purposes only.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the version is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Get the HTTP version</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">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>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:version - HTTP version</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">version</span></span>(<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="color: #009900">Version</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_version</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Return the HTTP version used for the request.</p></div> +<div class="paragraph"><p>The version can also be obtained using pattern matching:</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">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> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The HTTP version used for the request is returned as an +atom. It is provided for informative purposes only.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the version is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Get the HTTP version</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">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> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_req/index.html b/docs/en/cowboy/2.0/manual/cowboy_req/index.html index a9965645..b04c65d5 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req(3)</title> @@ -67,389 +67,389 @@ <h1 class="lined-header"><span>cowboy_req(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req - HTTP request and response</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The module <code>cowboy_req</code> provides functions to access, manipulate
-and respond to requests.</p></div>
-<div class="paragraph"><p>There are four types of functions in this module. They can be
-differentiated by their name and their return type:</p></div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="border"
-cellspacing="0" cellpadding="4">
-<col width="33%" />
-<col width="33%" />
-<col width="33%" />
-<thead>
-<tr>
-<th align="left" valign="top"> Type </th>
-<th align="left" valign="top"> Name pattern </th>
-<th align="left" valign="top"> Return type</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table">access</p></td>
-<td align="left" valign="top"><p class="table">no verb, parse_*, match_*</p></td>
-<td align="left" valign="top"><p class="table"><code>Value</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">question</p></td>
-<td align="left" valign="top"><p class="table">has_*</p></td>
-<td align="left" valign="top"><p class="table"><code>boolean()</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">modification</p></td>
-<td align="left" valign="top"><p class="table">set_*</p></td>
-<td align="left" valign="top"><p class="table"><code>Req</code></p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">action</p></td>
-<td align="left" valign="top"><p class="table">any other verb</p></td>
-<td align="left" valign="top"><p class="table"><code>ok | {Result, Value, Req}</code></p></td>
-</tr>
-</tbody>
-</table>
-</div>
-<div class="paragraph"><p>Any <code>Req</code> returned must be used in place of the one passed as
-argument. Functions that perform an action in particular write
-state in the Req object to make sure you are using the function
-correctly. For example, it’s only possible to send one response,
-and to read the body once.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exports">Exports</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Raw request:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy_req.method">cowboy_req:method(3)</a> - HTTP method
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.version">cowboy_req:version(3)</a> - HTTP version
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.scheme">cowboy_req:scheme(3)</a> - URI scheme
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.host">cowboy_req:host(3)</a> - URI host name
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.port">cowboy_req:port(3)</a> - URI port number
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.path">cowboy_req:path(3)</a> - URI path
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.qs">cowboy_req:qs(3)</a> - URI query string
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.uri">cowboy_req:uri(3)</a> - Reconstructed URI
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.header">cowboy_req:header(3)</a> - HTTP header
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.headers">cowboy_req:headers(3)</a> - HTTP headers
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.peer">cowboy_req:peer(3)</a> - Peer address and port
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Processed request:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy_req.parse_qs">cowboy_req:parse_qs(3)</a> - Parse the query string
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.match_qs">cowboy_req:match_qs(3)</a> - Match the query string against constraints
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.parse_header">cowboy_req:parse_header(3)</a> - Parse the given HTTP header
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.parse_cookies">cowboy_req:parse_cookies(3)</a> - Parse cookie headers
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.match_cookies">cowboy_req:match_cookies(3)</a> - Match cookies against constraints
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.binding">cowboy_req:binding(3)</a> - Access a value bound from the route
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a> - Access all values bound from the route
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.host_info">cowboy_req:host_info(3)</a> - Access the route’s heading host segments
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a> - Access the route’s trailing path segments
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Request body:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy_req.has_body">cowboy_req:has_body(3)</a> - Is there a request body?
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.body_length">cowboy_req:body_length(3)</a> - Body length
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a> - Read the request body
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.read_urlencoded_body">cowboy_req:read_urlencoded_body(3)</a> - Read and parse a urlencoded request body
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.read_part">cowboy_req:read_part(3)</a> - Read the next multipart headers
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.read_part_body">cowboy_req:read_part_body(3)</a> - Read the current part’s body
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Response:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a> - Set a cookie
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a> - Set a response header
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a> - Set several response headers
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.has_resp_header">cowboy_req:has_resp_header(3)</a> - Is the given response header set?
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.resp_header">cowboy_req:resp_header(3)</a> - Response header
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.resp_headers">cowboy_req:resp_headers(3)</a> - Response headers
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.delete_resp_header">cowboy_req:delete_resp_header(3)</a> - Delete a response header
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.set_resp_body">cowboy_req:set_resp_body(3)</a> - Set the response body
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.has_resp_body">cowboy_req:has_resp_body(3)</a> - Is there a response body?
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.reply">cowboy_req:reply(3)</a> - Send the response
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a> - Send the response headers
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.stream_body">cowboy_req:stream_body(3)</a> - Stream the response body
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req.push">cowboy_req:push(3)</a> - Push a resource to the client
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_push_opts">push_opts()</h3>
-<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">push_opts</span></span>() <span style="color: #990000">::</span> #{
- <span style="color: #0000FF">method</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
- <span style="color: #0000FF">scheme</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span>
- <span style="color: #0000FF">host</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span>
- <span style="color: #0000FF">port</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>(),
- <span style="color: #0000FF">qs</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
-}</tt></pre></div></div>
-<div class="paragraph"><p>Push options.</p></div>
-<div class="paragraph"><p>By default, Cowboy will use the GET method, an empty query string,
-and take the scheme, host and port directly from the current
-request’s URI.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_read_body_opts">read_body_opts()</h3>
-<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">read_body_opts</span></span>() <span style="color: #990000">::</span> #{
- <span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(),
- <span style="color: #0000FF">period</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(),
- <span style="color: #0000FF">timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()
-}</tt></pre></div></div>
-<div class="paragraph"><p>Body reading options.</p></div>
-<div class="paragraph"><p>The defaults are function-specific.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_req">req()</h3>
-<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">req</span></span>() <span style="color: #990000">::</span> #{
- <span style="color: #FF6600">method</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
- <span style="color: #FF6600">version</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_version</span></span>() | <span style="font-weight: bold"><span style="color: #000080">atom</span></span>(),
- <span style="color: #FF6600">scheme</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span>
- <span style="color: #FF6600">host</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span>
- <span style="color: #FF6600">port</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>(),
- <span style="color: #FF6600">path</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
- <span style="color: #FF6600">qs</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
- <span style="color: #FF6600">headers</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>(),
- <span style="color: #FF6600">peer</span> <span style="color: #990000">:=</span> {<span style="font-weight: bold"><span style="color: #000000">inet:ip_address</span></span>(), <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>()}
-}</tt></pre></div></div>
-<div class="paragraph"><p>The Req object.</p></div>
-<div class="paragraph"><p>Contains information about the request and response. While
-some fields are publicly documented, others aren’t and shouldn’t
-be used.</p></div>
-<div class="paragraph"><p>You may add custom fields if required. Make sure to namespace
-them by prepending an underscore and the name of your application:</p></div>
-<div class="listingblock">
-<div class="title">Setting a custom field</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">Req</span>#{<span style="color: #009900">_myapp_auth_method</span> <span style="color: #990000">=></span> <span style="color: #FF6600">pubkey</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-<div class="sect2">
-<h3 id="_resp_body">resp_body()</h3>
-<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">resp_body</span></span>() <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()
- | {<span style="color: #FF6600">sendfile</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Length</span>, <span style="color: #009900">Filename</span>}
-
-<span style="color: #009900">Offset</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()
-<span style="color: #009900">Length</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">pos_integer</span></span>()
-<span style="color: #009900">Filename</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">file:name_all</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Response body.</p></div>
-<div class="paragraph"><p>It can take two forms: the actual data to be sent or a
-tuple indicating which file to send.</p></div>
-<div class="paragraph"><p>When sending data directly, the type is either a binary or
-an iolist. Iolists are an efficient way to build output.
-Instead of concatenating strings or binaries, you can simply
-build a list containing the fragments you want to send in the
-order they should be sent:</p></div>
-<div class="listingblock">
-<div class="title">Example iolists usage</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: #993399">1</span><span style="color: #990000">></span> <span style="color: #009900">RespBody</span> <span style="color: #990000">=</span> [<span style="color: #FF0000">"Hello "</span>, [<span style="color: #990000"><<</span><span style="color: #FF0000">"world"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">$!</span>]]<span style="color: #990000">.</span>
-[<span style="color: #FF0000">"Hello "</span>,[<span style="color: #990000"><<</span><span style="color: #FF0000">"world"</span><span style="color: #990000">>></span>,<span style="color: #993399">33</span>]]
-<span style="color: #993399">2</span><span style="color: #990000">></span> <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"~s~n"</span>, [<span style="color: #009900">RespBody</span>])<span style="color: #990000">.</span>
-<span style="color: #009900">Hello</span> <span style="color: #FF6600">world</span><span style="color: #990000">!</span></tt></pre></div></div>
-<div class="paragraph"><p>When using the sendfile tuple, the <code>Length</code> value is mandatory
-and must be higher than 0. It is sent with the response in the
-content-length header.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="..">cowboy(7)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req - HTTP request and response</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The module <code>cowboy_req</code> provides functions to access, manipulate +and respond to requests.</p></div> +<div class="paragraph"><p>There are four types of functions in this module. They can be +differentiated by their name and their return type:</p></div> +<div class="tableblock"> +<table rules="all" +width="100%" +frame="border" +cellspacing="0" cellpadding="4"> +<col width="33%" /> +<col width="33%" /> +<col width="33%" /> +<thead> +<tr> +<th align="left" valign="top"> Type </th> +<th align="left" valign="top"> Name pattern </th> +<th align="left" valign="top"> Return type</th> +</tr> +</thead> +<tbody> +<tr> +<td align="left" valign="top"><p class="table">access</p></td> +<td align="left" valign="top"><p class="table">no verb, parse_*, match_*</p></td> +<td align="left" valign="top"><p class="table"><code>Value</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">question</p></td> +<td align="left" valign="top"><p class="table">has_*</p></td> +<td align="left" valign="top"><p class="table"><code>boolean()</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">modification</p></td> +<td align="left" valign="top"><p class="table">set_*</p></td> +<td align="left" valign="top"><p class="table"><code>Req</code></p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">action</p></td> +<td align="left" valign="top"><p class="table">any other verb</p></td> +<td align="left" valign="top"><p class="table"><code>ok | {Result, Value, Req}</code></p></td> +</tr> +</tbody> +</table> +</div> +<div class="paragraph"><p>Any <code>Req</code> returned must be used in place of the one passed as +argument. Functions that perform an action in particular write +state in the Req object to make sure you are using the function +correctly. For example, it’s only possible to send one response, +and to read the body once.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Raw request:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="../cowboy_req.method">cowboy_req:method(3)</a> - HTTP method +</p> +</li> +<li> +<p> +<a href="../cowboy_req.version">cowboy_req:version(3)</a> - HTTP version +</p> +</li> +<li> +<p> +<a href="../cowboy_req.scheme">cowboy_req:scheme(3)</a> - URI scheme +</p> +</li> +<li> +<p> +<a href="../cowboy_req.host">cowboy_req:host(3)</a> - URI host name +</p> +</li> +<li> +<p> +<a href="../cowboy_req.port">cowboy_req:port(3)</a> - URI port number +</p> +</li> +<li> +<p> +<a href="../cowboy_req.path">cowboy_req:path(3)</a> - URI path +</p> +</li> +<li> +<p> +<a href="../cowboy_req.qs">cowboy_req:qs(3)</a> - URI query string +</p> +</li> +<li> +<p> +<a href="../cowboy_req.uri">cowboy_req:uri(3)</a> - Reconstructed URI +</p> +</li> +<li> +<p> +<a href="../cowboy_req.header">cowboy_req:header(3)</a> - HTTP header +</p> +</li> +<li> +<p> +<a href="../cowboy_req.headers">cowboy_req:headers(3)</a> - HTTP headers +</p> +</li> +<li> +<p> +<a href="../cowboy_req.peer">cowboy_req:peer(3)</a> - Peer address and port +</p> +</li> +</ul></div> +<div class="paragraph"><p>Processed request:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="../cowboy_req.parse_qs">cowboy_req:parse_qs(3)</a> - Parse the query string +</p> +</li> +<li> +<p> +<a href="../cowboy_req.match_qs">cowboy_req:match_qs(3)</a> - Match the query string against constraints +</p> +</li> +<li> +<p> +<a href="../cowboy_req.parse_header">cowboy_req:parse_header(3)</a> - Parse the given HTTP header +</p> +</li> +<li> +<p> +<a href="../cowboy_req.parse_cookies">cowboy_req:parse_cookies(3)</a> - Parse cookie headers +</p> +</li> +<li> +<p> +<a href="../cowboy_req.match_cookies">cowboy_req:match_cookies(3)</a> - Match cookies against constraints +</p> +</li> +<li> +<p> +<a href="../cowboy_req.binding">cowboy_req:binding(3)</a> - Access a value bound from the route +</p> +</li> +<li> +<p> +<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a> - Access all values bound from the route +</p> +</li> +<li> +<p> +<a href="../cowboy_req.host_info">cowboy_req:host_info(3)</a> - Access the route’s heading host segments +</p> +</li> +<li> +<p> +<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a> - Access the route’s trailing path segments +</p> +</li> +</ul></div> +<div class="paragraph"><p>Request body:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="../cowboy_req.has_body">cowboy_req:has_body(3)</a> - Is there a request body? +</p> +</li> +<li> +<p> +<a href="../cowboy_req.body_length">cowboy_req:body_length(3)</a> - Body length +</p> +</li> +<li> +<p> +<a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a> - Read the request body +</p> +</li> +<li> +<p> +<a href="../cowboy_req.read_urlencoded_body">cowboy_req:read_urlencoded_body(3)</a> - Read and parse a urlencoded request body +</p> +</li> +<li> +<p> +<a href="../cowboy_req.read_part">cowboy_req:read_part(3)</a> - Read the next multipart headers +</p> +</li> +<li> +<p> +<a href="../cowboy_req.read_part_body">cowboy_req:read_part_body(3)</a> - Read the current part’s body +</p> +</li> +</ul></div> +<div class="paragraph"><p>Response:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="../cowboy_req.set_resp_cookie">cowboy_req:set_resp_cookie(3)</a> - Set a cookie +</p> +</li> +<li> +<p> +<a href="../cowboy_req.set_resp_header">cowboy_req:set_resp_header(3)</a> - Set a response header +</p> +</li> +<li> +<p> +<a href="../cowboy_req.set_resp_headers">cowboy_req:set_resp_headers(3)</a> - Set several response headers +</p> +</li> +<li> +<p> +<a href="../cowboy_req.has_resp_header">cowboy_req:has_resp_header(3)</a> - Is the given response header set? +</p> +</li> +<li> +<p> +<a href="../cowboy_req.resp_header">cowboy_req:resp_header(3)</a> - Response header +</p> +</li> +<li> +<p> +<a href="../cowboy_req.resp_headers">cowboy_req:resp_headers(3)</a> - Response headers +</p> +</li> +<li> +<p> +<a href="../cowboy_req.delete_resp_header">cowboy_req:delete_resp_header(3)</a> - Delete a response header +</p> +</li> +<li> +<p> +<a href="../cowboy_req.set_resp_body">cowboy_req:set_resp_body(3)</a> - Set the response body +</p> +</li> +<li> +<p> +<a href="../cowboy_req.has_resp_body">cowboy_req:has_resp_body(3)</a> - Is there a response body? +</p> +</li> +<li> +<p> +<a href="../cowboy_req.reply">cowboy_req:reply(3)</a> - Send the response +</p> +</li> +<li> +<p> +<a href="../cowboy_req.stream_reply">cowboy_req:stream_reply(3)</a> - Send the response headers +</p> +</li> +<li> +<p> +<a href="../cowboy_req.stream_body">cowboy_req:stream_body(3)</a> - Stream the response body +</p> +</li> +<li> +<p> +<a href="../cowboy_req.push">cowboy_req:push(3)</a> - Push a resource to the client +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_push_opts">push_opts()</h3> +<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">push_opts</span></span>() <span style="color: #990000">::</span> #{ + <span style="color: #0000FF">method</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> + <span style="color: #0000FF">scheme</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span> + <span style="color: #0000FF">host</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span> + <span style="color: #0000FF">port</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>(), + <span style="color: #0000FF">qs</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> +}</tt></pre></div></div> +<div class="paragraph"><p>Push options.</p></div> +<div class="paragraph"><p>By default, Cowboy will use the GET method, an empty query string, +and take the scheme, host and port directly from the current +request’s URI.</p></div> +</div> +<div class="sect2"> +<h3 id="_read_body_opts">read_body_opts()</h3> +<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">read_body_opts</span></span>() <span style="color: #990000">::</span> #{ + <span style="font-weight: bold"><span style="color: #000080">length</span></span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), + <span style="color: #0000FF">period</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), + <span style="color: #0000FF">timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>() +}</tt></pre></div></div> +<div class="paragraph"><p>Body reading options.</p></div> +<div class="paragraph"><p>The defaults are function-specific.</p></div> +</div> +<div class="sect2"> +<h3 id="_req">req()</h3> +<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">req</span></span>() <span style="color: #990000">::</span> #{ + <span style="color: #FF6600">method</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> + <span style="color: #FF6600">version</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_version</span></span>() | <span style="font-weight: bold"><span style="color: #000080">atom</span></span>(), + <span style="color: #FF6600">scheme</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span> + <span style="color: #FF6600">host</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span> + <span style="color: #FF6600">port</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>(), + <span style="color: #FF6600">path</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> + <span style="color: #FF6600">qs</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> + <span style="color: #FF6600">headers</span> <span style="color: #990000">:=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>(), + <span style="color: #FF6600">peer</span> <span style="color: #990000">:=</span> {<span style="font-weight: bold"><span style="color: #000000">inet:ip_address</span></span>(), <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>()} +}</tt></pre></div></div> +<div class="paragraph"><p>The Req object.</p></div> +<div class="paragraph"><p>Contains information about the request and response. While +some fields are publicly documented, others aren’t and shouldn’t +be used.</p></div> +<div class="paragraph"><p>You may add custom fields if required. Make sure to namespace +them by prepending an underscore and the name of your application:</p></div> +<div class="listingblock"> +<div class="title">Setting a custom field</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">Req</span>#{<span style="color: #009900">_myapp_auth_method</span> <span style="color: #990000">=></span> <span style="color: #FF6600">pubkey</span>}<span style="color: #990000">.</span></tt></pre></div></div> +</div> +<div class="sect2"> +<h3 id="_resp_body">resp_body()</h3> +<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">resp_body</span></span>() <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() + | {<span style="color: #FF6600">sendfile</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Length</span>, <span style="color: #009900">Filename</span>} + +<span style="color: #009900">Offset</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>() +<span style="color: #009900">Length</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>() +<span style="color: #009900">Filename</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">file:name_all</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Response body.</p></div> +<div class="paragraph"><p>It can take two forms: the actual data to be sent or a +tuple indicating which file to send.</p></div> +<div class="paragraph"><p>When sending data directly, the type is either a binary or +an iolist. Iolists are an efficient way to build output. +Instead of concatenating strings or binaries, you can simply +build a list containing the fragments you want to send in the +order they should be sent:</p></div> +<div class="listingblock"> +<div class="title">Example iolists usage</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: #993399">1</span><span style="color: #990000">></span> <span style="color: #009900">RespBody</span> <span style="color: #990000">=</span> [<span style="color: #FF0000">"Hello "</span>, [<span style="color: #990000"><<</span><span style="color: #FF0000">"world"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">$!</span>]]<span style="color: #990000">.</span> +[<span style="color: #FF0000">"Hello "</span>,[<span style="color: #990000"><<</span><span style="color: #FF0000">"world"</span><span style="color: #990000">>></span>,<span style="color: #993399">33</span>]] +<span style="color: #993399">2</span><span style="color: #990000">></span> <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"~s~n"</span>, [<span style="color: #009900">RespBody</span>])<span style="color: #990000">.</span> +<span style="color: #009900">Hello</span> <span style="color: #FF6600">world</span><span style="color: #990000">!</span></tt></pre></div></div> +<div class="paragraph"><p>Note that the length must be greater than zero for any data +to be sent. Cowboy will send an empty body when the length +is zero.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="..">cowboy(7)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_rest/index.html b/docs/en/cowboy/2.0/manual/cowboy_rest/index.html index 174f8d53..cca510c5 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_rest/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_rest/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_rest(3)</title> @@ -67,641 +67,641 @@ <h1 class="lined-header"><span>cowboy_rest(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_rest - REST handlers</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The module <code>cowboy_rest</code> implements the HTTP state machine.</p></div>
-<div class="paragraph"><p>Implementing REST handlers is not enough to provide a REST
-interface; this interface must also follow the REST
-constraints including HATEOAS (hypermedia as the engine
-of application state).</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_callbacks">Callbacks</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>REST handlers implement the following interface:</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">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: #009900">Callback</span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>)
- <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</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">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="font-style: italic"><span style="color: #9A1900">%% optional</span></span>
-
-<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()
-<span style="color: #009900">State</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
-<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">normal</span></span>
- | {<span style="color: #FF6600">crash</span>, <span style="color: #FF6600">error</span> | <span style="font-weight: bold"><span style="color: #000080">exit</span></span> | <span style="font-weight: bold"><span style="color: #000080">throw</span></span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}
-
-<span style="color: #009900">Callback</span> <span style="color: #990000">-</span> <span style="color: #FF6600">see</span> <span style="color: #FF6600">below</span>
-<span style="color: #009900">Result</span> <span style="color: #990000">-</span> <span style="color: #FF6600">see</span> <span style="color: #FF6600">below</span>
-<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">see</span> <span style="color: #FF6600">below</span></tt></pre></div></div>
-<div class="paragraph"><p>The <code>init/2</code> callback is common to all handlers. To switch
-to the REST handler behavior, it must return <code>cowboy_rest</code>
-as the first element of the tuple.</p></div>
-<div class="paragraph"><p>The <code>Callback/2</code> above represents all the REST-specific
-callbacks. They are described in the following section
-of this manual. REST-specific callbacks differ by their
-name, semantics, result and default values. The default
-value is the one used when the callback has not been
-implemented. They otherwise all follow the same interface.</p></div>
-<div class="paragraph"><p>The <code>stop</code> tuple can be returned to stop REST processing.
-If no response was sent before then, Cowboy will send a
-<em>204 No Content</em>.</p></div>
-<div class="paragraph"><p>The optional <code>terminate/3</code> callback will ultimately be called
-with the reason for the termination of the handler.
-Cowboy will terminate the process right after this. There
-is no need to perform any cleanup in this callback.</p></div>
-<div class="paragraph"><p>The following terminate reasons are defined for loop handlers:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-normal
-</dt>
-<dd>
-<p>
- The handler terminated normally.
-</p>
-</dd>
-<dt class="hdlist1">
-{crash, Class, Reason}
-</dt>
-<dd>
-<p>
- A crash occurred in the handler. <code>Class</code> and <code>Reason</code> can be
- used to obtain more information about the crash. The function
- <code>erlang:get_stacktrace/0</code> can also be called to obtain the
- stacktrace of the process when the crash occurred.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_rest_callbacks">REST callbacks</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_acceptcallback">AcceptCallback</h3>
-<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">AcceptCallback</span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span> | {<span style="color: #000080">true</span>, <span style="color: #009900">URI</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()} | <span style="color: #000080">false</span>}
-<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">crash</span></tt></pre></div></div>
-<div class="paragraph"><p>Process the request body.</p></div>
-<div class="paragraph"><p>This function should create or update the resource using the
-request body.</p></div>
-<div class="paragraph"><p>For PUT requests, the body is a representation of the resource
-that is being created or replaced.</p></div>
-<div class="paragraph"><p>For POST requests, the body is typically application-specific
-instructions on how to process the request, but it may also
-be a representation of the resource. When creating a new
-resource with POST at a different location, return <code>{true, URI}</code>
-with <code>URI</code> the new location.</p></div>
-<div class="paragraph"><p>For PATCH requests, the body is a series of instructions on
-how to update the resource. Patch files or JSON Patch are
-examples of such media types.</p></div>
-<div class="paragraph"><p>A response body may be sent. The appropriate media type, charset
-and language for the response can be retrieved from the Req
-object using the <code>media_type</code>, <code>charset</code> and <code>language</code> keys,
-respectively. The body can be set using
-<a href="../cowboy_req.set_resp_body">cowboy_req:set_resp_body(3)</a>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_allowed_methods">allowed_methods</h3>
-<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">allowed_methods</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()] <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
-<span style="color: #009900">Default</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: #990000"><<</span><span style="color: #FF0000">"HEAD"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"OPTIONS"</span><span style="color: #990000">>></span>]</tt></pre></div></div>
-<div class="paragraph"><p>Return the list of allowed methods.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_allow_missing_post">allow_missing_post</h3>
-<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">allow_missing_post</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether POST is allowed when the resource doesn’t exist.</p></div>
-<div class="paragraph"><p>Returning <code>true</code> here means that a new resource will be
-created. The URI for the newly created resource should be
-returned from the <code>AcceptCallback</code> function.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_charsets_provided">charsets_provided</h3>
-<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">charsets_provided</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()] <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span>
-<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">skip</span> <span style="color: #FF6600">this</span> <span style="color: #FF6600">step</span></tt></pre></div></div>
-<div class="paragraph"><p>Return the list of charsets the resource provides in order
-of preference.</p></div>
-<div class="paragraph"><p>During content negotiation Cowboy will pick the most
-appropriate charset for the client. The client advertises
-charsets it prefers with the accept-charset header. When
-that header is missing, Cowboy picks the first charset
-from the resource.</p></div>
-<div class="paragraph"><p>Cowboy will add the negotiated <code>charset</code> to the Req object
-after this step completes:</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">req</span></span>() <span style="color: #990000">::</span> #{
- <span style="color: #0000FF">charset</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span>
-}</tt></pre></div></div>
-</div>
-<div class="sect2">
-<h3 id="_content_types_accepted">content_types_accepted</h3>
-<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">content_types_accepted</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> [{<span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #009900">ParsedMime</span>, <span style="color: #009900">AcceptCallback</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()}]
-<span style="color: #009900">ParsedMime</span> <span style="color: #990000">::</span> {<span style="color: #009900">Type</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">SubType</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #FF6600">'*'</span> | <span style="color: #009900">Params</span>}
-<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}]
-
-<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">crash</span></tt></pre></div></div>
-<div class="paragraph"><p>Return the list of media types the resource accepts in
-order of preference.</p></div>
-<div class="paragraph"><p>A media type is made of different parts. The media type
-<code>text/html;charset=utf-8</code> is of type <code>text</code>, subtype <code>html</code>
-and has a single parameter <code>charset</code> with value <code>utf-8</code>.</p></div>
-<div class="paragraph"><p>Cowboy will match the content-type request header against
-the media types the server accepts and select the appropriate
-callback. When that header is missing, or when the server does not
-accept this media type, the request fails and an error response
-is returned. Cowboy will execute the callback immediately otherwise.</p></div>
-<div class="paragraph"><p>An empty parameters list <code>[]</code> means that no parameters will be
-accepted. When any parameter is acceptable, the tuple form
-should be used with parameters as the atom <code>'*'</code>.</p></div>
-<div class="paragraph"><p>Cowboy treats all parameters as case sensitive, except for the
-<code>charset</code> parameter, which is known to be case insensitive. You
-should therefore always provide the charset as a lowercase
-binary string.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_content_types_provided">content_types_provided</h3>
-<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">content_types_provided</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> [{<span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #009900">ParsedMime</span>, <span style="color: #009900">ProvideCallback</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()}]
-<span style="color: #009900">ParsedMime</span> <span style="color: #990000">::</span> {<span style="color: #009900">Type</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">SubType</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #FF6600">'*'</span> | <span style="color: #009900">Params</span>}
-<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}]
-
-<span style="color: #009900">Default</span> <span style="color: #990000">-</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">"html"</span><span style="color: #990000">>></span>, <span style="color: #FF6600">'*'</span>}, <span style="color: #FF6600">to_html</span>}]</tt></pre></div></div>
-<div class="paragraph"><p>Return the list of media types the resource provides in
-order of preference.</p></div>
-<div class="paragraph"><p>A media type is made of different parts. The media type
-<code>text/html;charset=utf-8</code> is of type <code>text</code>, subtype <code>html</code>
-and has a single parameter <code>charset</code> with value <code>utf-8</code>.</p></div>
-<div class="paragraph"><p>During content negotiation Cowboy will pick the most appropriate
-media type for the client. The client advertises media types it
-prefers with the accept header. When that header is missing,
-the content negotiation fails and an error response is returned.</p></div>
-<div class="paragraph"><p>The callback given for the selected media type will be called
-at the end of the execution of GET and HEAD requests when a
-representation must be sent to the client.</p></div>
-<div class="paragraph"><p>An empty parameters list <code>[]</code> means that no parameters will be
-accepted. When any parameter is acceptable, the tuple form
-should be used with parameters as the atom <code>'*'</code>.</p></div>
-<div class="paragraph"><p>Cowboy treats all parameters as case sensitive, except for the
-<code>charset</code> parameter, which is known to be case insensitive. You
-should therefore always provide the charset as a lowercase
-binary string.</p></div>
-<div class="paragraph"><p>Cowboy will add the negotiated <code>media_type</code> to the Req object
-after this step completes:</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">req</span></span>() <span style="color: #990000">::</span> #{
- <span style="color: #0000FF">media_type</span> <span style="color: #990000">=></span> <span style="color: #009900">ParsedMime</span>
-}</tt></pre></div></div>
-</div>
-<div class="sect2">
-<h3 id="_delete_completed">delete_completed</h3>
-<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">delete_completed</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether the resource has been fully deleted from the
-system, including from any internal cache.</p></div>
-<div class="paragraph"><p>Returning <code>false</code> will result in a <em>202 Accepted</em> response
-being sent instead of a <em>200 OK</em> or <em>204 No Content</em>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_delete_resource">delete_resource</h3>
-<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">delete_resource</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div>
-<div class="paragraph"><p>Delete the resource.</p></div>
-<div class="paragraph"><p>Cowboy will send an error response when this function
-returns <code>false</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_expires">expires</h3>
-<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">expires</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">calendar:datetime</span></span>() | <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #000080">undefined</span>
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">undefined</span></tt></pre></div></div>
-<div class="paragraph"><p>Return the resource’s expiration date.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_forbidden">forbidden</h3>
-<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">forbidden</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether access to the resource is forbidden.</p></div>
-<div class="paragraph"><p>A <em>403 Forbidden</em> response will be sent if this
-function returns <code>true</code>. This status code means that
-access is forbidden regardless of authentication,
-and that the request shouldn’t be repeated.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_generate_etag">generate_etag</h3>
-<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">generate_etag</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | {<span style="color: #FF6600">weak</span> | <span style="color: #FF6600">strong</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}
-<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">no</span> <span style="color: #FF6600">etag</span> <span style="color: #FF6600">value</span></tt></pre></div></div>
-<div class="paragraph"><p>Return the entity tag of the resource.</p></div>
-<div class="paragraph"><p>When a binary is returned, the value is automatically
-parsed to a tuple. The binary must be in the same
-format as the etag header, including quotes.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_is_authorized">is_authorized</h3>
-<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">is_authorized</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span> | {<span style="color: #000080">false</span>, <span style="color: #009900">AuthHeader</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()}
-<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #000080">true</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether the user is authorized to perform the action.</p></div>
-<div class="paragraph"><p>This function should be used to perform any necessary
-authentication of the user before attempting to perform
-any action on the resource.</p></div>
-<div class="paragraph"><p>When authentication fails, the <code>AuthHeader</code> value will
-be sent in the www-authenticate header for the
-<em>401 Unauthorized</em> response.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_is_conflict">is_conflict</h3>
-<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">is_conflict</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether the PUT request results in a conflict.</p></div>
-<div class="paragraph"><p>A <em>409 Conflict</em> response is sent when <code>true</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_known_methods">known_methods</h3>
-<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">known_methods</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()] <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
-<span style="color: #009900">Default</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: #990000"><<</span><span style="color: #FF0000">"HEAD"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"POST"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"PUT"</span><span style="color: #990000">>></span>,
- <span style="color: #990000"><<</span><span style="color: #FF0000">"PATCH"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"DELETE"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"OPTIONS"</span><span style="color: #990000">>></span>]</tt></pre></div></div>
-<div class="paragraph"><p>Return the list of known methods.</p></div>
-<div class="paragraph"><p>The full list of methods known by the server should be
-returned, regardless of their use in the resource.</p></div>
-<div class="paragraph"><p>The default value lists the methods Cowboy knows and
-implement in <code>cowboy_rest</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_languages_provided">languages_provided</h3>
-<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">languages_provided</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()] <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span>
-<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">skip</span> <span style="color: #FF6600">this</span> <span style="color: #FF6600">step</span></tt></pre></div></div>
-<div class="paragraph"><p>Return the list of languages the resource provides in order
-of preference.</p></div>
-<div class="paragraph"><p>During content negotiation Cowboy will pick the most
-appropriate language for the client. The client advertises
-languages it prefers with the accept-language header. When
-that header is missing, Cowboy picks the first language
-from the resource.</p></div>
-<div class="paragraph"><p>Cowboy will add the negotiated <code>language</code> to the Req object
-after this step completes:</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">req</span></span>() <span style="color: #990000">::</span> #{
- <span style="color: #0000FF">language</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span>
-}</tt></pre></div></div>
-</div>
-<div class="sect2">
-<h3 id="_last_modified">last_modified</h3>
-<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">last_modified</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">calendar:datetime</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">no</span> <span style="color: #FF6600">last</span> <span style="color: #FF6600">modified</span> <span style="color: #FF6600">value</span></tt></pre></div></div>
-<div class="paragraph"><p>Return the resource’s last modification date.</p></div>
-<div class="paragraph"><p>This date will be used to test against the if-modified-since
-and if-unmodified-since headers, and sent as the last-modified
-header in the response to GET and HEAD requests.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_malformed_request">malformed_request</h3>
-<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">malformed_request</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether the request is malformed.</p></div>
-<div class="paragraph"><p>A request is malformed when a component required by the
-resource is invalid. This may include the query string
-or individual headers. They should be parsed and validated
-in this function. The body should not be read at this point.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_moved_permanently">moved_permanently</h3>
-<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">moved_permanently</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> {<span style="color: #000080">true</span>, <span style="color: #009900">URI</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()} | <span style="color: #000080">false</span>
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether the resource was permanently moved, and
-what its new location is.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_moved_temporarily">moved_temporarily</h3>
-<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">moved_temporarily</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> {<span style="color: #000080">true</span>, <span style="color: #009900">URI</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()} | <span style="color: #000080">false</span>
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether the resource was temporarily moved, and
-what its new location is.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_multiple_choices">multiple_choices</h3>
-<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">multiple_choices</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether the client should engage in reactive
-negotiation.</p></div>
-<div class="paragraph"><p>Return <code>true</code> when the server has multiple representations
-of a resource, each with their specific identifier, but is
-unable to determine which is best for the client. For
-example an image might have different sizes and the server
-is unable to determine the capabilities of the client.</p></div>
-<div class="paragraph"><p>When returning <code>true</code> the server should send a body with
-links to the different representations. If the server has
-a preferred representation it can send its link inside a
-location header.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_options">options</h3>
-<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">options</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>}</tt></pre></div></div>
-<div class="paragraph"><p>Respond to an OPTIONS request.</p></div>
-<div class="paragraph"><p>The response should inform the client the communication
-options available for this resource. By default Cowboy
-will send a <em>200 OK</em> response with the allow header set.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_previously_existed">previously_existed</h3>
-<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">previously_existed</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether the resource existed previously.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_providecallback">ProvideCallback</h3>
-<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">ProvideCallback</span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_body</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">crash</span></tt></pre></div></div>
-<div class="paragraph"><p>Return the response body.</p></div>
-<div class="paragraph"><p>The response body can be provided either as the actual data
-to be sent or a tuple indicating which file to send.</p></div>
-<div class="paragraph"><p>This function is called for both GET and HEAD requests. For
-the latter the body is not sent, however.</p></div>
-<div class="paragraph"><p>Note that there used to be a way to stream the response body.
-It was temporarily removed and will be added back in a later
-release.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_resource_exists">resource_exists</h3>
-<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">resource_exists</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether the resource exists.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_service_available">service_available</h3>
-<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">service_available</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether the service is available.</p></div>
-<div class="paragraph"><p>A <em>503 Service Unavailable</em> response will be sent when this
-function returns <code>false</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_uri_too_long">uri_too_long</h3>
-<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">uri_too_long</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether the requested URI is too long.</p></div>
-<div class="paragraph"><p>This function can be used to further restrict the length
-of the URI for this specific resource.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_valid_content_headers">valid_content_headers</h3>
-<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">valid_content_headers</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether the content headers are valid.</p></div>
-<div class="paragraph"><p>This callback can be used to reject requests that have
-invalid content header values, for example an unsupported
-content-encoding.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_valid_entity_length">valid_entity_length</h3>
-<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">valid_entity_length</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span></tt></pre></div></div>
-<div class="paragraph"><p>Return whether the request body length is within acceptable boundaries.</p></div>
-<div class="paragraph"><p>A <em>413 Request Entity Too Large</em> response will be sent if this
-function returns <code>false</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_variances">variances</h3>
-<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">variances</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Result</span> <span style="color: #990000">::</span> [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()] <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span>
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> []</tt></pre></div></div>
-<div class="paragraph"><p>Return the list of request headers that affect the
-representation of the resource.</p></div>
-<div class="paragraph"><p>Cowboy automatically adds the accept, accept-charset and
-accept-language headers when necessary.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="..">cowboy(7)</a>,
-<a href="../cowboy_handler">cowboy_handler(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_rest - REST handlers</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The module <code>cowboy_rest</code> implements the HTTP state machine.</p></div> +<div class="paragraph"><p>Implementing REST handlers is not enough to provide a REST +interface; this interface must also follow the REST +constraints including HATEOAS (hypermedia as the engine +of application state).</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_callbacks">Callbacks</h2> +<div class="sectionbody"> +<div class="paragraph"><p>REST handlers implement the following interface:</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">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: #009900">Callback</span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) + <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</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">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="font-style: italic"><span style="color: #9A1900">%% optional</span></span> + +<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>() +<span style="color: #009900">State</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() +<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">normal</span></span> + | {<span style="color: #FF6600">crash</span>, <span style="color: #FF6600">error</span> | <span style="font-weight: bold"><span style="color: #000080">exit</span></span> | <span style="font-weight: bold"><span style="color: #000080">throw</span></span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()} + +<span style="color: #009900">Callback</span> <span style="color: #990000">-</span> <span style="color: #FF6600">see</span> <span style="color: #FF6600">below</span> +<span style="color: #009900">Result</span> <span style="color: #990000">-</span> <span style="color: #FF6600">see</span> <span style="color: #FF6600">below</span> +<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">see</span> <span style="color: #FF6600">below</span></tt></pre></div></div> +<div class="paragraph"><p>The <code>init/2</code> callback is common to all handlers. To switch +to the REST handler behavior, it must return <code>cowboy_rest</code> +as the first element of the tuple.</p></div> +<div class="paragraph"><p>The <code>Callback/2</code> above represents all the REST-specific +callbacks. They are described in the following section +of this manual. REST-specific callbacks differ by their +name, semantics, result and default values. The default +value is the one used when the callback has not been +implemented. They otherwise all follow the same interface.</p></div> +<div class="paragraph"><p>The <code>stop</code> tuple can be returned to stop REST processing. +If no response was sent before then, Cowboy will send a +<em>204 No Content</em>.</p></div> +<div class="paragraph"><p>The optional <code>terminate/3</code> callback will ultimately be called +with the reason for the termination of the handler. +Cowboy will terminate the process right after this. There +is no need to perform any cleanup in this callback.</p></div> +<div class="paragraph"><p>The following terminate reasons are defined for loop handlers:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +normal +</dt> +<dd> +<p> + The handler terminated normally. +</p> +</dd> +<dt class="hdlist1"> +{crash, Class, Reason} +</dt> +<dd> +<p> + A crash occurred in the handler. <code>Class</code> and <code>Reason</code> can be + used to obtain more information about the crash. The function + <code>erlang:get_stacktrace/0</code> can also be called to obtain the + stacktrace of the process when the crash occurred. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_rest_callbacks">REST callbacks</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_acceptcallback">AcceptCallback</h3> +<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">AcceptCallback</span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span> | {<span style="color: #000080">true</span>, <span style="color: #009900">URI</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()} | <span style="color: #000080">false</span>} +<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">crash</span></tt></pre></div></div> +<div class="paragraph"><p>Process the request body.</p></div> +<div class="paragraph"><p>This function should create or update the resource using the +request body.</p></div> +<div class="paragraph"><p>For PUT requests, the body is a representation of the resource +that is being created or replaced.</p></div> +<div class="paragraph"><p>For POST requests, the body is typically application-specific +instructions on how to process the request, but it may also +be a representation of the resource. When creating a new +resource with POST at a different location, return <code>{true, URI}</code> +with <code>URI</code> the new location.</p></div> +<div class="paragraph"><p>For PATCH requests, the body is a series of instructions on +how to update the resource. Patch files or JSON Patch are +examples of such media types.</p></div> +<div class="paragraph"><p>A response body may be sent. The appropriate media type, charset +and language for the response can be retrieved from the Req +object using the <code>media_type</code>, <code>charset</code> and <code>language</code> keys, +respectively. The body can be set using +<a href="../cowboy_req.set_resp_body">cowboy_req:set_resp_body(3)</a>.</p></div> +</div> +<div class="sect2"> +<h3 id="_allowed_methods">allowed_methods</h3> +<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">allowed_methods</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()] <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> +<span style="color: #009900">Default</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: #990000"><<</span><span style="color: #FF0000">"HEAD"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"OPTIONS"</span><span style="color: #990000">>></span>]</tt></pre></div></div> +<div class="paragraph"><p>Return the list of allowed methods.</p></div> +</div> +<div class="sect2"> +<h3 id="_allow_missing_post">allow_missing_post</h3> +<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">allow_missing_post</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether POST is allowed when the resource doesn’t exist.</p></div> +<div class="paragraph"><p>Returning <code>true</code> here means that a new resource will be +created. The URI for the newly created resource should be +returned from the <code>AcceptCallback</code> function.</p></div> +</div> +<div class="sect2"> +<h3 id="_charsets_provided">charsets_provided</h3> +<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">charsets_provided</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()] <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span> +<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">skip</span> <span style="color: #FF6600">this</span> <span style="color: #FF6600">step</span></tt></pre></div></div> +<div class="paragraph"><p>Return the list of charsets the resource provides in order +of preference.</p></div> +<div class="paragraph"><p>During content negotiation Cowboy will pick the most +appropriate charset for the client. The client advertises +charsets it prefers with the accept-charset header. When +that header is missing, Cowboy picks the first charset +from the resource.</p></div> +<div class="paragraph"><p>Cowboy will add the negotiated <code>charset</code> to the Req object +after this step completes:</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">req</span></span>() <span style="color: #990000">::</span> #{ + <span style="color: #0000FF">charset</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span> +}</tt></pre></div></div> +</div> +<div class="sect2"> +<h3 id="_content_types_accepted">content_types_accepted</h3> +<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">content_types_accepted</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> [{<span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #009900">ParsedMime</span>, <span style="color: #009900">AcceptCallback</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()}] +<span style="color: #009900">ParsedMime</span> <span style="color: #990000">::</span> {<span style="color: #009900">Type</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">SubType</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #FF6600">'*'</span> | <span style="color: #009900">Params</span>} +<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}] + +<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">crash</span></tt></pre></div></div> +<div class="paragraph"><p>Return the list of media types the resource accepts in +order of preference.</p></div> +<div class="paragraph"><p>A media type is made of different parts. The media type +<code>text/html;charset=utf-8</code> is of type <code>text</code>, subtype <code>html</code> +and has a single parameter <code>charset</code> with value <code>utf-8</code>.</p></div> +<div class="paragraph"><p>Cowboy will match the content-type request header against +the media types the server accepts and select the appropriate +callback. When that header is missing, or when the server does not +accept this media type, the request fails and an error response +is returned. Cowboy will execute the callback immediately otherwise.</p></div> +<div class="paragraph"><p>An empty parameters list <code>[]</code> means that no parameters will be +accepted. When any parameter is acceptable, the tuple form +should be used with parameters as the atom <code>'*'</code>.</p></div> +<div class="paragraph"><p>Cowboy treats all parameters as case sensitive, except for the +<code>charset</code> parameter, which is known to be case insensitive. You +should therefore always provide the charset as a lowercase +binary string.</p></div> +</div> +<div class="sect2"> +<h3 id="_content_types_provided">content_types_provided</h3> +<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">content_types_provided</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> [{<span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #009900">ParsedMime</span>, <span style="color: #009900">ProvideCallback</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()}] +<span style="color: #009900">ParsedMime</span> <span style="color: #990000">::</span> {<span style="color: #009900">Type</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">SubType</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #FF6600">'*'</span> | <span style="color: #009900">Params</span>} +<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}] + +<span style="color: #009900">Default</span> <span style="color: #990000">-</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">"html"</span><span style="color: #990000">>></span>, <span style="color: #FF6600">'*'</span>}, <span style="color: #FF6600">to_html</span>}]</tt></pre></div></div> +<div class="paragraph"><p>Return the list of media types the resource provides in +order of preference.</p></div> +<div class="paragraph"><p>A media type is made of different parts. The media type +<code>text/html;charset=utf-8</code> is of type <code>text</code>, subtype <code>html</code> +and has a single parameter <code>charset</code> with value <code>utf-8</code>.</p></div> +<div class="paragraph"><p>During content negotiation Cowboy will pick the most appropriate +media type for the client. The client advertises media types it +prefers with the accept header. When that header is missing, +the content negotiation fails and an error response is returned.</p></div> +<div class="paragraph"><p>The callback given for the selected media type will be called +at the end of the execution of GET and HEAD requests when a +representation must be sent to the client.</p></div> +<div class="paragraph"><p>An empty parameters list <code>[]</code> means that no parameters will be +accepted. When any parameter is acceptable, the tuple form +should be used with parameters as the atom <code>'*'</code>.</p></div> +<div class="paragraph"><p>Cowboy treats all parameters as case sensitive, except for the +<code>charset</code> parameter, which is known to be case insensitive. You +should therefore always provide the charset as a lowercase +binary string.</p></div> +<div class="paragraph"><p>Cowboy will add the negotiated <code>media_type</code> to the Req object +after this step completes:</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">req</span></span>() <span style="color: #990000">::</span> #{ + <span style="color: #0000FF">media_type</span> <span style="color: #990000">=></span> <span style="color: #009900">ParsedMime</span> +}</tt></pre></div></div> +</div> +<div class="sect2"> +<h3 id="_delete_completed">delete_completed</h3> +<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">delete_completed</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether the resource has been fully deleted from the +system, including from any internal cache.</p></div> +<div class="paragraph"><p>Returning <code>false</code> will result in a <em>202 Accepted</em> response +being sent instead of a <em>200 OK</em> or <em>204 No Content</em>.</p></div> +</div> +<div class="sect2"> +<h3 id="_delete_resource">delete_resource</h3> +<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">delete_resource</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div> +<div class="paragraph"><p>Delete the resource.</p></div> +<div class="paragraph"><p>Cowboy will send an error response when this function +returns <code>false</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_expires">expires</h3> +<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">expires</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">calendar:datetime</span></span>() | <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #000080">undefined</span> +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">undefined</span></tt></pre></div></div> +<div class="paragraph"><p>Return the resource’s expiration date.</p></div> +</div> +<div class="sect2"> +<h3 id="_forbidden">forbidden</h3> +<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">forbidden</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether access to the resource is forbidden.</p></div> +<div class="paragraph"><p>A <em>403 Forbidden</em> response will be sent if this +function returns <code>true</code>. This status code means that +access is forbidden regardless of authentication, +and that the request shouldn’t be repeated.</p></div> +</div> +<div class="sect2"> +<h3 id="_generate_etag">generate_etag</h3> +<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">generate_etag</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | {<span style="color: #FF6600">weak</span> | <span style="color: #FF6600">strong</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()} +<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">no</span> <span style="color: #FF6600">etag</span> <span style="color: #FF6600">value</span></tt></pre></div></div> +<div class="paragraph"><p>Return the entity tag of the resource.</p></div> +<div class="paragraph"><p>When a binary is returned, the value is automatically +parsed to a tuple. The binary must be in the same +format as the etag header, including quotes.</p></div> +</div> +<div class="sect2"> +<h3 id="_is_authorized">is_authorized</h3> +<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">is_authorized</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span> | {<span style="color: #000080">false</span>, <span style="color: #009900">AuthHeader</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()} +<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #000080">true</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether the user is authorized to perform the action.</p></div> +<div class="paragraph"><p>This function should be used to perform any necessary +authentication of the user before attempting to perform +any action on the resource.</p></div> +<div class="paragraph"><p>When authentication fails, the <code>AuthHeader</code> value will +be sent in the www-authenticate header for the +<em>401 Unauthorized</em> response.</p></div> +</div> +<div class="sect2"> +<h3 id="_is_conflict">is_conflict</h3> +<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">is_conflict</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether the PUT request results in a conflict.</p></div> +<div class="paragraph"><p>A <em>409 Conflict</em> response is sent when <code>true</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_known_methods">known_methods</h3> +<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">known_methods</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()] <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> +<span style="color: #009900">Default</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: #990000"><<</span><span style="color: #FF0000">"HEAD"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"POST"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"PUT"</span><span style="color: #990000">>></span>, + <span style="color: #990000"><<</span><span style="color: #FF0000">"PATCH"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"DELETE"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"OPTIONS"</span><span style="color: #990000">>></span>]</tt></pre></div></div> +<div class="paragraph"><p>Return the list of known methods.</p></div> +<div class="paragraph"><p>The full list of methods known by the server should be +returned, regardless of their use in the resource.</p></div> +<div class="paragraph"><p>The default value lists the methods Cowboy knows and +implement in <code>cowboy_rest</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_languages_provided">languages_provided</h3> +<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">languages_provided</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()] <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span> +<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">skip</span> <span style="color: #FF6600">this</span> <span style="color: #FF6600">step</span></tt></pre></div></div> +<div class="paragraph"><p>Return the list of languages the resource provides in order +of preference.</p></div> +<div class="paragraph"><p>During content negotiation Cowboy will pick the most +appropriate language for the client. The client advertises +languages it prefers with the accept-language header. When +that header is missing, Cowboy picks the first language +from the resource.</p></div> +<div class="paragraph"><p>Cowboy will add the negotiated <code>language</code> to the Req object +after this step completes:</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">req</span></span>() <span style="color: #990000">::</span> #{ + <span style="color: #0000FF">language</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span> +}</tt></pre></div></div> +</div> +<div class="sect2"> +<h3 id="_last_modified">last_modified</h3> +<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">last_modified</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">calendar:datetime</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">no</span> <span style="color: #FF6600">last</span> <span style="color: #FF6600">modified</span> <span style="color: #FF6600">value</span></tt></pre></div></div> +<div class="paragraph"><p>Return the resource’s last modification date.</p></div> +<div class="paragraph"><p>This date will be used to test against the if-modified-since +and if-unmodified-since headers, and sent as the last-modified +header in the response to GET and HEAD requests.</p></div> +</div> +<div class="sect2"> +<h3 id="_malformed_request">malformed_request</h3> +<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">malformed_request</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether the request is malformed.</p></div> +<div class="paragraph"><p>A request is malformed when a component required by the +resource is invalid. This may include the query string +or individual headers. They should be parsed and validated +in this function. The body should not be read at this point.</p></div> +</div> +<div class="sect2"> +<h3 id="_moved_permanently">moved_permanently</h3> +<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">moved_permanently</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> {<span style="color: #000080">true</span>, <span style="color: #009900">URI</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()} | <span style="color: #000080">false</span> +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether the resource was permanently moved, and +what its new location is.</p></div> +</div> +<div class="sect2"> +<h3 id="_moved_temporarily">moved_temporarily</h3> +<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">moved_temporarily</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> {<span style="color: #000080">true</span>, <span style="color: #009900">URI</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()} | <span style="color: #000080">false</span> +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether the resource was temporarily moved, and +what its new location is.</p></div> +</div> +<div class="sect2"> +<h3 id="_multiple_choices">multiple_choices</h3> +<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">multiple_choices</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether the client should engage in reactive +negotiation.</p></div> +<div class="paragraph"><p>Return <code>true</code> when the server has multiple representations +of a resource, each with their specific identifier, but is +unable to determine which is best for the client. For +example an image might have different sizes and the server +is unable to determine the capabilities of the client.</p></div> +<div class="paragraph"><p>When returning <code>true</code> the server should send a body with +links to the different representations. If the server has +a preferred representation it can send its link inside a +location header.</p></div> +</div> +<div class="sect2"> +<h3 id="_options">options</h3> +<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">options</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>}</tt></pre></div></div> +<div class="paragraph"><p>Respond to an OPTIONS request.</p></div> +<div class="paragraph"><p>The response should inform the client the communication +options available for this resource. By default Cowboy +will send a <em>200 OK</em> response with the allow header set.</p></div> +</div> +<div class="sect2"> +<h3 id="_previously_existed">previously_existed</h3> +<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">previously_existed</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether the resource existed previously.</p></div> +</div> +<div class="sect2"> +<h3 id="_providecallback">ProvideCallback</h3> +<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">ProvideCallback</span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_body</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">-</span> <span style="color: #FF6600">crash</span></tt></pre></div></div> +<div class="paragraph"><p>Return the response body.</p></div> +<div class="paragraph"><p>The response body can be provided either as the actual data +to be sent or a tuple indicating which file to send.</p></div> +<div class="paragraph"><p>This function is called for both GET and HEAD requests. For +the latter the body is not sent, however.</p></div> +<div class="paragraph"><p>Note that there used to be a way to stream the response body. +It was temporarily removed and will be added back in a later +release.</p></div> +</div> +<div class="sect2"> +<h3 id="_resource_exists">resource_exists</h3> +<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">resource_exists</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether the resource exists.</p></div> +</div> +<div class="sect2"> +<h3 id="_service_available">service_available</h3> +<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">service_available</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether the service is available.</p></div> +<div class="paragraph"><p>A <em>503 Service Unavailable</em> response will be sent when this +function returns <code>false</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_uri_too_long">uri_too_long</h3> +<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">uri_too_long</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">false</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether the requested URI is too long.</p></div> +<div class="paragraph"><p>This function can be used to further restrict the length +of the URI for this specific resource.</p></div> +</div> +<div class="sect2"> +<h3 id="_valid_content_headers">valid_content_headers</h3> +<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">valid_content_headers</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether the content headers are valid.</p></div> +<div class="paragraph"><p>This callback can be used to reject requests that have +invalid content header values, for example an unsupported +content-encoding.</p></div> +</div> +<div class="sect2"> +<h3 id="_valid_entity_length">valid_entity_length</h3> +<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">valid_entity_length</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="color: #000080">true</span></tt></pre></div></div> +<div class="paragraph"><p>Return whether the request body length is within acceptable boundaries.</p></div> +<div class="paragraph"><p>A <em>413 Request Entity Too Large</em> response will be sent if this +function returns <code>false</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_variances">variances</h3> +<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">variances</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Result</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Result</span> <span style="color: #990000">::</span> [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()] <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span> +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> []</tt></pre></div></div> +<div class="paragraph"><p>Return the list of request headers that affect the +representation of the resource.</p></div> +<div class="paragraph"><p>Cowboy automatically adds the accept, accept-charset and +accept-language headers when necessary.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="..">cowboy(7)</a>, +<a href="../cowboy_handler">cowboy_handler(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_router.compile/index.html b/docs/en/cowboy/2.0/manual/cowboy_router.compile/index.html index 58e60685..7987500b 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_router.compile/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_router.compile/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_router:compile(3)</title> @@ -67,87 +67,87 @@ <h1 class="lined-header"><span>cowboy_router:compile(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_router:compile - Compile routes to the resources</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">compile</span></span>(<span style="font-weight: bold"><span style="color: #000000">cowboy_router:routes</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:dispatch_rules</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Compile routes to the resources.</p></div>
-<div class="paragraph"><p>Takes a human readable list of routes and transforms it
-into a form more efficient to process.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Routes
-</dt>
-<dd>
-<p>
-Human readable list of routes.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An opaque dispatch rules value is returned. This value
-must be given to Cowboy as a middleware environment value.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Compile routes and start a listener</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">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">toppage_h</span>, []},
- {<span style="color: #FF0000">"/[...], cowboy_static, {priv_dir, my_example_app, ""}}</span>
-<span style="color: #FF0000"> ]}</span>
-<span style="color: #FF0000">]),</span>
-
-<span style="color: #FF0000">{ok, _} = cowboy:start_clear(example, [{port, 8080}], #{</span>
-<span style="color: #FF0000"> env => #{dispatch => Dispatch}</span>
-<span style="color: #FF0000">}).</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_router">cowboy_router(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_router:compile - Compile routes to the resources</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<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">compile</span></span>(<span style="font-weight: bold"><span style="color: #000000">cowboy_router:routes</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">cowboy_router:dispatch_rules</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Compile routes to the resources.</p></div> +<div class="paragraph"><p>Takes a human readable list of routes and transforms it +into a form more efficient to process.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Routes +</dt> +<dd> +<p> +Human readable list of routes. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An opaque dispatch rules value is returned. This value +must be given to Cowboy as a middleware environment value.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Compile routes and start a listener</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">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">toppage_h</span>, []}, + {<span style="color: #FF0000">"/[...], cowboy_static, {priv_dir, my_example_app, ""}}</span> +<span style="color: #FF0000"> ]}</span> +<span style="color: #FF0000">]),</span> + +<span style="color: #FF0000">{ok, _} = cowboy:start_clear(example, [{port, 8080}], #{</span> +<span style="color: #FF0000"> env => #{dispatch => Dispatch}</span> +<span style="color: #FF0000">}).</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_router">cowboy_router(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_router/index.html b/docs/en/cowboy/2.0/manual/cowboy_router/index.html index 8121066c..3ebdb9e7 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_router/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_router/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_router(3)</title> @@ -67,110 +67,110 @@ <h1 class="lined-header"><span>cowboy_router(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_router - Router middleware</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>cowboy_router</code> middleware maps the requested host and
-path to the handler to be used for processing the request.</p></div>
-<div class="paragraph"><p>The router takes the <code>dispatch</code> rules as input from the
-middleware environment. Dispatch rules are generated by
-calling the
-<a href="../cowboy_router.compile">cowboy_router:compile(3)</a>
-function.</p></div>
-<div class="paragraph"><p>When a route matches, the router sets the <code>handler</code> and
-<code>handler_opts</code> middleware environment values containing
-the handler module and initial state, respectively.</p></div>
-<div class="paragraph"><p>The router will stop execution when no route matches.
-It will send a 400 response if no host was found, and
-a 404 response otherwise.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exports">Exports</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy_router.compile">cowboy_router:compile(3)</a> - Compile routes to the resources
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_bindings">bindings()</h3>
-<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">bindings</span></span>() <span style="color: #990000">::</span> #{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>() <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>Bindings found during routing.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_dispatch_rules">dispatch_rules()</h3>
-<div class="paragraph"><p>Opaque type containing the compiled routes.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_routes">routes()</h3>
-<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">routes</span></span>() <span style="color: #990000">=</span> [
- {<span style="color: #009900">Host</span>, <span style="color: #009900">PathList</span>} |
- {<span style="color: #009900">Host</span>, <span style="color: #009900">Fields</span>, <span style="color: #009900">PathList</span>}
-]
-
-<span style="color: #009900">PathList</span> <span style="color: #990000">::</span> [
- {<span style="color: #009900">Path</span>, <span style="color: #009900">Handler</span>, <span style="color: #009900">InitialState</span>} |
- {<span style="color: #009900">Path</span>, <span style="color: #009900">Fields</span>, <span style="color: #009900">Handler</span>, <span style="color: #009900">InitialState</span>}
-]
-
-<span style="color: #009900">Host</span> <span style="color: #990000">::</span> <span style="color: #FF6600">'_'</span> | <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()
-<span style="color: #009900">Path</span> <span style="color: #990000">::</span> <span style="color: #FF6600">'_'</span> | <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()
-<span style="color: #009900">Fields</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:fields</span></span>()
-<span style="color: #009900">Handler</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">module</span></span>()
-<span style="color: #009900">InitialState</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Human readable list of routes to handlers.</p></div>
-<div class="paragraph"><p>Cowboy uses this list to map hosts and paths, optionally
-augmented with constraints applied to the bindings, to
-handler modules.</p></div>
-<div class="paragraph"><p>The syntax for routes is currently defined in the user guide.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_tokens">tokens()</h3>
-<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">tokens</span></span>() <span style="color: #990000">::</span> [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()]</tt></pre></div></div>
-<div class="paragraph"><p>List of <code>host_info</code> and <code>path_info</code> tokens that were found
-using the <code>...</code> syntax.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="..">cowboy(7)</a>,
-<a href="../cowboy_req.binding">cowboy_req:binding(3)</a>,
-<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a>,
-<a href="../cowboy_req.host_info">cowboy_req:host_info(3)</a>,
-<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_router - Router middleware</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>cowboy_router</code> middleware maps the requested host and +path to the handler to be used for processing the request.</p></div> +<div class="paragraph"><p>The router takes the <code>dispatch</code> rules as input from the +middleware environment. Dispatch rules are generated by +calling the +<a href="../cowboy_router.compile">cowboy_router:compile(3)</a> +function.</p></div> +<div class="paragraph"><p>When a route matches, the router sets the <code>handler</code> and +<code>handler_opts</code> middleware environment values containing +the handler module and initial state, respectively.</p></div> +<div class="paragraph"><p>The router will stop execution when no route matches. +It will send a 400 response if no host was found, and +a 404 response otherwise.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="../cowboy_router.compile">cowboy_router:compile(3)</a> - Compile routes to the resources +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_bindings">bindings()</h3> +<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">bindings</span></span>() <span style="color: #990000">::</span> #{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>() <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Bindings found during routing.</p></div> +</div> +<div class="sect2"> +<h3 id="_dispatch_rules">dispatch_rules()</h3> +<div class="paragraph"><p>Opaque type containing the compiled routes.</p></div> +</div> +<div class="sect2"> +<h3 id="_routes">routes()</h3> +<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">routes</span></span>() <span style="color: #990000">=</span> [ + {<span style="color: #009900">Host</span>, <span style="color: #009900">PathList</span>} | + {<span style="color: #009900">Host</span>, <span style="color: #009900">Fields</span>, <span style="color: #009900">PathList</span>} +] + +<span style="color: #009900">PathList</span> <span style="color: #990000">::</span> [ + {<span style="color: #009900">Path</span>, <span style="color: #009900">Handler</span>, <span style="color: #009900">InitialState</span>} | + {<span style="color: #009900">Path</span>, <span style="color: #009900">Fields</span>, <span style="color: #009900">Handler</span>, <span style="color: #009900">InitialState</span>} +] + +<span style="color: #009900">Host</span> <span style="color: #990000">::</span> <span style="color: #FF6600">'_'</span> | <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() +<span style="color: #009900">Path</span> <span style="color: #990000">::</span> <span style="color: #FF6600">'_'</span> | <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>() +<span style="color: #009900">Fields</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:fields</span></span>() +<span style="color: #009900">Handler</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">module</span></span>() +<span style="color: #009900">InitialState</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Human readable list of routes to handlers.</p></div> +<div class="paragraph"><p>Cowboy uses this list to map hosts and paths, optionally +augmented with constraints applied to the bindings, to +handler modules.</p></div> +<div class="paragraph"><p>The syntax for routes is currently defined in the user guide.</p></div> +</div> +<div class="sect2"> +<h3 id="_tokens">tokens()</h3> +<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">tokens</span></span>() <span style="color: #990000">::</span> [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()]</tt></pre></div></div> +<div class="paragraph"><p>List of <code>host_info</code> and <code>path_info</code> tokens that were found +using the <code>...</code> syntax.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="..">cowboy(7)</a>, +<a href="../cowboy_req.binding">cowboy_req:binding(3)</a>, +<a href="../cowboy_req.bindings">cowboy_req:bindings(3)</a>, +<a href="../cowboy_req.host_info">cowboy_req:host_info(3)</a>, +<a href="../cowboy_req.path_info">cowboy_req:path_info(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_static/index.html b/docs/en/cowboy/2.0/manual/cowboy_static/index.html index b981578b..4630aa10 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_static/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_static/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_static(3)</title> @@ -67,175 +67,175 @@ <h1 class="lined-header"><span>cowboy_static(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_static - Static file handler</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The module <code>cowboy_static</code> implements file serving capabilities
-using the REST semantics provided by <code>cowboy_rest</code>.</p></div>
-<div class="paragraph"><p>The static file handler is a pre-written handler coming with
-Cowboy. To serve files, use it in your routes.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_options">Options</h2>
-<div class="sectionbody">
-<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">opts</span></span>() <span style="color: #990000">::</span> {<span style="color: #FF6600">priv_file</span>, <span style="color: #009900">App</span>, <span style="color: #009900">Path</span>}
- | {<span style="color: #FF6600">priv_file</span>, <span style="color: #009900">App</span>, <span style="color: #009900">Path</span>, <span style="color: #009900">Extra</span>}
- | {<span style="color: #FF6600">file</span>, <span style="color: #009900">Path</span>}
- | {<span style="color: #FF6600">file</span>, <span style="color: #009900">Path</span>, <span style="color: #009900">Extra</span>}
- | {<span style="color: #FF6600">priv_dir</span>, <span style="color: #009900">App</span>, <span style="color: #009900">Path</span>}
- | {<span style="color: #FF6600">priv_dir</span>, <span style="color: #009900">App</span>, <span style="color: #009900">Path</span>, <span style="color: #009900">Extra</span>}
- | {<span style="color: #FF6600">dir</span>, <span style="color: #009900">Path</span>}
- | {<span style="color: #FF6600">dir</span>, <span style="color: #009900">Path</span>, <span style="color: #009900">Extra</span>}
-
-<span style="color: #009900">App</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()
-<span style="color: #009900">Path</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="font-weight: bold"><span style="color: #000000">string</span></span>()
-<span style="color: #009900">Extra</span> <span style="color: #990000">::</span> [<span style="color: #009900">Etag</span> | <span style="color: #009900">Mimetypes</span>]
-
-<span style="color: #009900">Etag</span> <span style="color: #990000">::</span> {<span style="color: #FF6600">etag</span>, <span style="font-weight: bold"><span style="color: #000000">module</span></span>(), <span style="font-weight: bold"><span style="color: #000080">function</span></span>()}
- | {<span style="color: #FF6600">etag</span>, <span style="color: #000080">false</span>}
-
-<span style="color: #009900">Mimetypes</span> <span style="color: #990000">::</span> {<span style="color: #FF6600">mimetypes</span>, <span style="font-weight: bold"><span style="color: #000000">module</span></span>(), <span style="font-weight: bold"><span style="color: #000080">function</span></span>()}
- | {<span style="color: #FF6600">mimetypes</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #009900">ParsedMime</span>}
-
-<span style="color: #009900">ParsedMime</span> <span style="color: #990000">::</span> {<span style="color: #009900">Type</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">SubType</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Params</span>}
-<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}]</tt></pre></div></div>
-<div class="paragraph"><p>Static handler configuration.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-priv_file
-</dt>
-<dd>
-<p>
-Send a file.
-</p>
-<div class="paragraph"><p>The path is relative to the given application’s private
-directory.</p></div>
-</dd>
-<dt class="hdlist1">
-file
-</dt>
-<dd>
-<p>
-Send a file.
-</p>
-<div class="paragraph"><p>The path is either absolute or relative to the Erlang node’s
-current directory.</p></div>
-</dd>
-<dt class="hdlist1">
-priv_dir
-</dt>
-<dd>
-<p>
-Recursively serve files from a directory.
-</p>
-<div class="paragraph"><p>The path is relative to the given application’s private
-directory.</p></div>
-</dd>
-<dt class="hdlist1">
-dir
-</dt>
-<dd>
-<p>
-Recursively serve files from a directory.
-</p>
-<div class="paragraph"><p>The path is either absolute or relative to the Erlang node’s
-current directory.</p></div>
-</dd>
-</dl></div>
-<div class="paragraph"><p>The extra options allow you to define how the etag should be
-calculated and how the MIME type of files should be detected.</p></div>
-<div class="paragraph"><p>By default the static handler will generate an etag based
-on the size and modification time of the file. You may disable
-the etag entirely with <code>{etag, false}</code> or provide a module
-and function that will be called when needed:</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">generate_etag</span></span>(<span style="color: #009900">Path</span>, <span style="color: #009900">Size</span>, <span style="color: #009900">Mtime</span>) <span style="color: #990000">-></span> {<span style="color: #FF6600">strong</span> | <span style="color: #FF6600">weak</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}
-
-<span style="color: #009900">Path</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()
-<span style="color: #009900">Size</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()
-<span style="color: #009900">Mtime</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">file:date_time</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>By default the static handler will detect Web-related MIME types
-by looking at the file extension. You can provide a specific
-MIME type that will always be used, or a module and function that
-will be called when needed:</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">detect_mimetype</span></span>(<span style="color: #009900">Path</span>) <span style="color: #990000">-></span> <span style="color: #009900">ParsedMime</span>
-
-<span style="color: #009900">Path</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()
-<span style="color: #009900">ParsedMime</span> <span style="color: #990000">::</span> {<span style="color: #009900">Type</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">SubType</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Params</span>}
-<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}]</tt></pre></div></div>
-<div class="paragraph"><p>Cowboy comes with two such functions; the default function
-<code>cow_mimetypes:web/1</code>, and a second function generated from
-the Apache <em>mime.types</em> file, <code>cow_mimetypes:all/1</code>.</p></div>
-<div class="paragraph"><p>The MIME type function should return
-<code>{<<"application">>, <<"octet-stream">>, []}</code>
-when it fails to detect a file’s MIME type.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>1.0</strong>: Handler introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Custom etag function</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="font-weight: bold"><span style="color: #000000">generate_etag</span></span>(<span style="color: #009900">Path</span>, <span style="color: #009900">Size</span>, <span style="color: #009900">Mtime</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">strong</span>, <span style="font-weight: bold"><span style="color: #000000">integer_to_binary</span></span>(
- <span style="font-weight: bold"><span style="color: #000000">erlang:phash2</span></span>({<span style="color: #009900">Path</span>, <span style="color: #009900">Size</span>, <span style="color: #009900">Mtime</span>}, <span style="color: #993399">16#ffffffff</span>))}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Custom MIME type function</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="font-weight: bold"><span style="color: #000000">always_octet_stream</span></span>(<span style="color: #009900">_Path</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">filename:extension</span></span>(<span style="color: #009900">Path</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- <span style="color: #990000"><<</span><span style="color: #FF0000">".erl"</span><span style="color: #990000">>></span> <span style="color: #990000">-></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> <span style="color: #990000">-></span> {<span style="color: #990000"><<</span><span style="color: #FF0000">"application"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"octet-stream"</span><span style="color: #990000">>></span>, []}
- <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="..">cowboy(7)</a>,
-<a href="../cowboy_router">cowboy_router(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_static - Static file handler</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The module <code>cowboy_static</code> implements file serving capabilities +using the REST semantics provided by <code>cowboy_rest</code>.</p></div> +<div class="paragraph"><p>The static file handler is a pre-written handler coming with +Cowboy. To serve files, use it in your routes.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_options">Options</h2> +<div class="sectionbody"> +<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">opts</span></span>() <span style="color: #990000">::</span> {<span style="color: #FF6600">priv_file</span>, <span style="color: #009900">App</span>, <span style="color: #009900">Path</span>} + | {<span style="color: #FF6600">priv_file</span>, <span style="color: #009900">App</span>, <span style="color: #009900">Path</span>, <span style="color: #009900">Extra</span>} + | {<span style="color: #FF6600">file</span>, <span style="color: #009900">Path</span>} + | {<span style="color: #FF6600">file</span>, <span style="color: #009900">Path</span>, <span style="color: #009900">Extra</span>} + | {<span style="color: #FF6600">priv_dir</span>, <span style="color: #009900">App</span>, <span style="color: #009900">Path</span>} + | {<span style="color: #FF6600">priv_dir</span>, <span style="color: #009900">App</span>, <span style="color: #009900">Path</span>, <span style="color: #009900">Extra</span>} + | {<span style="color: #FF6600">dir</span>, <span style="color: #009900">Path</span>} + | {<span style="color: #FF6600">dir</span>, <span style="color: #009900">Path</span>, <span style="color: #009900">Extra</span>} + +<span style="color: #009900">App</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>() +<span style="color: #009900">Path</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="font-weight: bold"><span style="color: #000000">string</span></span>() +<span style="color: #009900">Extra</span> <span style="color: #990000">::</span> [<span style="color: #009900">Etag</span> | <span style="color: #009900">Mimetypes</span>] + +<span style="color: #009900">Etag</span> <span style="color: #990000">::</span> {<span style="color: #FF6600">etag</span>, <span style="font-weight: bold"><span style="color: #000000">module</span></span>(), <span style="font-weight: bold"><span style="color: #000080">function</span></span>()} + | {<span style="color: #FF6600">etag</span>, <span style="color: #000080">false</span>} + +<span style="color: #009900">Mimetypes</span> <span style="color: #990000">::</span> {<span style="color: #FF6600">mimetypes</span>, <span style="font-weight: bold"><span style="color: #000000">module</span></span>(), <span style="font-weight: bold"><span style="color: #000080">function</span></span>()} + | {<span style="color: #FF6600">mimetypes</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() | <span style="color: #009900">ParsedMime</span>} + +<span style="color: #009900">ParsedMime</span> <span style="color: #990000">::</span> {<span style="color: #009900">Type</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">SubType</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Params</span>} +<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}]</tt></pre></div></div> +<div class="paragraph"><p>Static handler configuration.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +priv_file +</dt> +<dd> +<p> +Send a file. +</p> +<div class="paragraph"><p>The path is relative to the given application’s private +directory.</p></div> +</dd> +<dt class="hdlist1"> +file +</dt> +<dd> +<p> +Send a file. +</p> +<div class="paragraph"><p>The path is either absolute or relative to the Erlang node’s +current directory.</p></div> +</dd> +<dt class="hdlist1"> +priv_dir +</dt> +<dd> +<p> +Recursively serve files from a directory. +</p> +<div class="paragraph"><p>The path is relative to the given application’s private +directory.</p></div> +</dd> +<dt class="hdlist1"> +dir +</dt> +<dd> +<p> +Recursively serve files from a directory. +</p> +<div class="paragraph"><p>The path is either absolute or relative to the Erlang node’s +current directory.</p></div> +</dd> +</dl></div> +<div class="paragraph"><p>The extra options allow you to define how the etag should be +calculated and how the MIME type of files should be detected.</p></div> +<div class="paragraph"><p>By default the static handler will generate an etag based +on the size and modification time of the file. You may disable +the etag entirely with <code>{etag, false}</code> or provide a module +and function that will be called when needed:</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">generate_etag</span></span>(<span style="color: #009900">Path</span>, <span style="color: #009900">Size</span>, <span style="color: #009900">Mtime</span>) <span style="color: #990000">-></span> {<span style="color: #FF6600">strong</span> | <span style="color: #FF6600">weak</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()} + +<span style="color: #009900">Path</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() +<span style="color: #009900">Size</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>() +<span style="color: #009900">Mtime</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">file:date_time</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>By default the static handler will detect Web-related MIME types +by looking at the file extension. You can provide a specific +MIME type that will always be used, or a module and function that +will be called when needed:</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">detect_mimetype</span></span>(<span style="color: #009900">Path</span>) <span style="color: #990000">-></span> <span style="color: #009900">ParsedMime</span> + +<span style="color: #009900">Path</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() +<span style="color: #009900">ParsedMime</span> <span style="color: #990000">::</span> {<span style="color: #009900">Type</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">SubType</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Params</span>} +<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}]</tt></pre></div></div> +<div class="paragraph"><p>Cowboy comes with two such functions; the default function +<code>cow_mimetypes:web/1</code>, and a second function generated from +the Apache <em>mime.types</em> file, <code>cow_mimetypes:all/1</code>.</p></div> +<div class="paragraph"><p>The MIME type function should return +<code>{<<"application">>, <<"octet-stream">>, []}</code> +when it fails to detect a file’s MIME type.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>1.0</strong>: Handler introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Custom etag function</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="font-weight: bold"><span style="color: #000000">generate_etag</span></span>(<span style="color: #009900">Path</span>, <span style="color: #009900">Size</span>, <span style="color: #009900">Mtime</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">strong</span>, <span style="font-weight: bold"><span style="color: #000000">integer_to_binary</span></span>( + <span style="font-weight: bold"><span style="color: #000000">erlang:phash2</span></span>({<span style="color: #009900">Path</span>, <span style="color: #009900">Size</span>, <span style="color: #009900">Mtime</span>}, <span style="color: #993399">16#ffffffff</span>))}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Custom MIME type function</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="font-weight: bold"><span style="color: #000000">always_octet_stream</span></span>(<span style="color: #009900">_Path</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">filename:extension</span></span>(<span style="color: #009900">Path</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + <span style="color: #990000"><<</span><span style="color: #FF0000">".erl"</span><span style="color: #990000">>></span> <span style="color: #990000">-></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> <span style="color: #990000">-></span> {<span style="color: #990000"><<</span><span style="color: #FF0000">"application"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"octet-stream"</span><span style="color: #990000">>></span>, []} + <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="..">cowboy(7)</a>, +<a href="../cowboy_router">cowboy_router(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_stream/index.html b/docs/en/cowboy/2.0/manual/cowboy_stream/index.html index a51a544e..40d11bcb 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_stream/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_stream/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_stream(3)</title> @@ -67,404 +67,411 @@ <h1 class="lined-header"><span>cowboy_stream(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_handler - Stream handlers</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The module <code>cowboy_stream</code> defines a callback interface
-and a protocol for handling HTTP streams.</p></div>
-<div class="paragraph"><p>An HTTP request and its associated response is called
-a stream. A connection may have many streams. In HTTP/1.1
-they are executed sequentially, while in HTTP/2 they are
-executed concurrently.</p></div>
-<div class="paragraph"><p>Cowboy calls the stream handler for nearly all events
-related to a stream. Exceptions vary depending on the
-protocol.</p></div>
-<div class="paragraph"><p>Extra care must be taken when implementing stream handlers
-to ensure compatibility. While some modification of the
-events and commands is allowed, it is generally not a good
-idea to completely omit them.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_callbacks">Callbacks</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Stream handlers must implement the following interface:</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">StreamID</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Commands</span>, <span style="color: #009900">State</span>}
-<span style="font-weight: bold"><span style="color: #000000">data</span></span>(<span style="color: #009900">StreamID</span>, <span style="color: #009900">IsFin</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Commands</span>, <span style="color: #009900">State</span>}
-<span style="font-weight: bold"><span style="color: #000000">info</span></span>(<span style="color: #009900">StreamID</span>, <span style="color: #009900">Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Commands</span>, <span style="color: #009900">State</span>}
-<span style="font-weight: bold"><span style="color: #000000">terminate</span></span>(<span style="color: #009900">StreamID</span>, <span style="color: #009900">Reason</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
-<span style="font-weight: bold"><span style="color: #000000">early_error</span></span>(<span style="color: #009900">StreamID</span>, <span style="color: #009900">Reason</span>, <span style="color: #009900">PartialReq</span>, <span style="color: #009900">Resp</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span> <span style="color: #009900">Resp</span>
-
-<span style="color: #009900">StreamID</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_stream:streamid</span></span>()
-<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()
-<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:opts</span></span>()
-<span style="color: #009900">Commands</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_stream:commands</span></span>()
-<span style="color: #009900">State</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
-<span style="color: #009900">IsFin</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_stream:fin</span></span>()
-<span style="color: #009900">Data</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()
-<span style="color: #009900">Info</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
-<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_stream:reason</span></span>()
-<span style="color: #009900">PartialReq</span> <span style="color: #990000">-</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #FF6600">except</span> <span style="color: #FF6600">all</span> <span style="color: #FF6600">fields</span> <span style="color: #FF6600">are</span> <span style="color: #FF6600">optional</span>
-<span style="color: #009900">Resp</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_stream:resp_command</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>HTTP/1.1 will initialize a stream only when the request-line
-and all headers have been received. When errors occur before
-that point Cowboy will call the callback <code>early_error/5</code>
-with a partial request, the error reason and the response
-Cowboy intends to send. All other events go throuh the
-stream handler using the normal callbacks.</p></div>
-<div class="paragraph"><p>HTTP/2 will initialize the stream when the <code>HEADERS</code> block has
-been fully received and decoded. Any protocol error occuring
-before that will not result in a response being sent and
-will therefore not go through the stream handler. In addition
-Cowboy may terminate streams without sending an HTTP response
-back.</p></div>
-<div class="paragraph"><p>The stream is initialized by calling <code>init/3</code>. All streams
-that are initialized will eventually be terminated by calling
-<code>terminate/3</code>.</p></div>
-<div class="paragraph"><p>When Cowboy receives data for the stream it will call <code>data/4</code>.
-The data given is the request body after any transfer decoding
-has been applied.</p></div>
-<div class="paragraph"><p>When Cowboy receives a message addressed to a stream, or when
-Cowboy needs to inform the stream handler that an internal
-event has occurred, it will call <code>info/3</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="commands">Commands</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Stream handlers can return a list of commands to be executed
-from the <code>init/3</code>, <code>data/4</code> and <code>info/3</code> callbacks. In addition,
-the <code>early_error/5</code> callback must return a response command.</p></div>
-<div class="paragraph"><p>The following commands are defined:</p></div>
-<div class="sect2">
-<h3 id="response_command">response</h3>
-<div class="paragraph"><p>Send a response to the client.</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">response</span>, <span style="font-weight: bold"><span style="color: #000000">cowboy:http_status</span></span>(), <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>(),
- <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_body</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>No more data can be sent after this command.</p></div>
-</div>
-<div class="sect2">
-<h3 id="headers_command">headers</h3>
-<div class="paragraph"><p>Initiate a response to the client.</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="font-weight: bold"><span style="color: #000000">cowboy:http_status</span></span>(), <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>This initiates a response to the client. The stream
-will end when a data command with the <code>fin</code> flag is
-returned.</p></div>
-</div>
-<div class="sect2">
-<h3 id="data_command">data</h3>
-<div class="paragraph"><p>Send data to the client.</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">data</span>, <span style="font-weight: bold"><span style="color: #000000">fin</span></span>(), <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()}</tt></pre></div></div>
-</div>
-<div class="sect2">
-<h3 id="push_command">push</h3>
-<div class="paragraph"><p>Push a resource to the client.</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">push</span>, <span style="color: #009900">Method</span>, <span style="color: #009900">Scheme</span>, <span style="color: #009900">Host</span>, <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>(),
- <span style="color: #009900">Path</span>, <span style="color: #009900">Qs</span>, <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>()}
-
-<span style="color: #009900">Method</span> <span style="color: #990000">=</span> <span style="color: #009900">Scheme</span> <span style="color: #990000">=</span> <span style="color: #009900">Host</span> <span style="color: #990000">=</span> <span style="color: #009900">Path</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: #000080">binary</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>The command will be ignored if the protocol does not provide
-any server push mechanism.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_flow">flow</h3>
-<div class="paragraph"><p>TODO</p></div>
-</div>
-<div class="sect2">
-<h3 id="_spawn">spawn</h3>
-<div class="paragraph"><p>Inform Cowboy that a process was spawned and should be
-supervised.</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: #000080">spawn</span></span>, <span style="font-weight: bold"><span style="color: #000080">pid</span></span>(), <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()}</tt></pre></div></div>
-</div>
-<div class="sect2">
-<h3 id="_error_response">error_response</h3>
-<div class="paragraph"><p>Send an error response if no response was sent previously.</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">error_response</span>, <span style="font-weight: bold"><span style="color: #000000">cowboy:http_status</span></span>(), <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>(), <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()}</tt></pre></div></div>
-</div>
-<div class="sect2">
-<h3 id="switch_protocol_command">switch_protocol</h3>
-<div class="paragraph"><p>Switch to a different protocol.</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">switch_protocol</span>, <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>(), <span style="font-weight: bold"><span style="color: #000000">module</span></span>(), <span style="font-weight: bold"><span style="color: #000000">state</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>Contains the headers that will be sent in the 101 response,
-along with the module implementing the protocol we are
-switching to and its initial state.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_stop">stop</h3>
-<div class="paragraph"><p>Stop the stream.</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">stop</span></tt></pre></div></div>
-<div class="paragraph"><p>While no more data can be sent after the <code>fin</code> flag was set,
-the stream is still tracked by Cowboy until it is stopped by
-the handler.</p></div>
-<div class="paragraph"><p>The behavior when stopping a stream for which no response
-has been sent will vary depending on the protocol. The stream
-will end successfully as far as the client is concerned.</p></div>
-<div class="paragraph"><p>To indicate that an error occurred, either use <code>error_response</code>
-before stopping, or use <code>internal_error</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_internal_error">internal_error</h3>
-<div class="paragraph"><p>Stop the stream with an error.</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">internal_error</span>, <span style="color: #009900">Reason</span>, <span style="color: #009900">HumanReadable</span>}
-
-<span style="color: #009900">Reason</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
-<span style="color: #009900">HumanReadable</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>This command should be used when the stream cannot continue
-because of an internal error. An <code>error_response</code> command
-may be sent before that to advertise to the client why the
-stream is dropped.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_predefined_events">Predefined events</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy will forward all messages sent to the stream to
-the <code>info/3</code> callback. To send a message to a stream,
-send a message to the connection process with the form
-<code>{{Pid, StreamID}, Msg}</code>. The connection process will
-then forward <code>Msg</code> to the stream handlers.</p></div>
-<div class="paragraph"><p>Cowboy will also forward the exit signals for the
-processes that the stream spawned.</p></div>
-<div class="sect2">
-<h3 id="_exit">EXIT</h3>
-<div class="paragraph"><p>A process spawned by this stream has exited.</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: #000080">'EXIT'</span>, <span style="font-weight: bold"><span style="color: #000080">pid</span></span>(), <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>This is the raw exit message without any modification.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_response">response</h3>
-<div class="paragraph"><p>Same as the <a href="../response_command">response command</a>.</p></div>
-<div class="paragraph"><p>Usually sent when the request process replies to the client.
-May also be sent by Cowboy internally.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_headers">headers</h3>
-<div class="paragraph"><p>Same as the <a href="../headers_command">headers command</a>.</p></div>
-<div class="paragraph"><p>Sent when the request process starts replying to the client.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_data">data</h3>
-<div class="paragraph"><p>Same as the <a href="../data_command">data command</a>.</p></div>
-<div class="paragraph"><p>Sent when the request process streams data to the client.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_push">push</h3>
-<div class="paragraph"><p>Same as the <a href="../push_command">push command</a>.</p></div>
-<div class="paragraph"><p>Sent when the request process pushes a resource to the client.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_switch_protocol">switch_protocol</h3>
-<div class="paragraph"><p>Same as the <a href="../switch_protocol_command">switch_protocol command</a>.</p></div>
-<div class="paragraph"><p>Sent when switching to the HTTP/2 or Websocket protocol.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exports">Exports</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The following function should be called by modules implementing
-stream handlers to execute the next stream handler in the list:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy_stream.init">cowboy_stream:init(3)</a> - Initialize a stream
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_stream.data">cowboy_stream:data(3)</a> - Handle data for a stream
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_stream.info">cowboy_stream:info(3)</a> - Handle a message for a stream
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_stream.terminate">cowboy_stream:terminate(3)</a> - Terminate a stream
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_stream.early_error">cowboy_stream:early_error(3)</a> - Handle an early error for a stream
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_commands">commands()</h3>
-<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">commands</span></span>() <span style="color: #990000">::</span> [<span style="color: #009900">Command</span>]</tt></pre></div></div>
-<div class="paragraph"><p>See the <a href="../commands">list of commands</a> for details.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_fin">fin()</h3>
-<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">fin</span></span>() <span style="color: #990000">::</span> <span style="color: #FF6600">fin</span> | <span style="color: #FF6600">nofin</span></tt></pre></div></div>
-<div class="paragraph"><p>Used in commands and events to indicate that this is
-the end of the stream.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_partial_req">partial_req()</h3>
-<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">req</span></span>() <span style="color: #990000">::</span> #{
- <span style="color: #0000FF">method</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
- <span style="color: #0000FF">version</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_version</span></span>() | <span style="font-weight: bold"><span style="color: #000080">atom</span></span>(),
- <span style="color: #0000FF">scheme</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span>
- <span style="color: #0000FF">host</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span>
- <span style="color: #0000FF">port</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>(),
- <span style="color: #0000FF">path</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
- <span style="color: #0000FF">qs</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
- <span style="color: #0000FF">headers</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>(),
- <span style="color: #0000FF">peer</span> <span style="color: #990000">=></span> {<span style="font-weight: bold"><span style="color: #000000">inet:ip_address</span></span>(), <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>()}
-}</tt></pre></div></div>
-<div class="paragraph"><p>Partial request information received when an early error is
-detected.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_reason">reason()</h3>
-<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">reason</span></span>() <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">normal</span></span>
- | {<span style="color: #FF6600">internal_error</span>, <span style="color: #FF6600">timeout</span> | {<span style="color: #FF6600">error</span> | <span style="font-weight: bold"><span style="color: #000080">exit</span></span> | <span style="font-weight: bold"><span style="color: #000080">throw</span></span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}, <span style="color: #009900">HumanReadable</span>}
- | {<span style="color: #FF6600">socket_error</span>, <span style="color: #FF6600">closed</span> | <span style="font-weight: bold"><span style="color: #000080">atom</span></span>(), <span style="color: #009900">HumanReadable</span>}
- | {<span style="color: #FF6600">stream_error</span>, <span style="color: #009900">Error</span>, <span style="color: #009900">HumanReadable</span>}
- | {<span style="color: #FF6600">connection_error</span>, <span style="color: #009900">Error</span>, <span style="color: #009900">HumanReadable</span>}
- | {<span style="color: #FF6600">stop</span>, <span style="font-weight: bold"><span style="color: #000000">cow_http2:frame</span></span>(), <span style="color: #009900">HumanReadable</span>}
-
-<span style="color: #009900">Error</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()
-<span style="color: #009900">HumanReadable</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Reason for the stream termination.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_resp_command">resp_command()</h3>
-<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">resp_command</span></span>() <span style="color: #990000">::</span> {<span style="color: #FF6600">response</span>, <span style="font-weight: bold"><span style="color: #000000">cowboy:http_status</span></span>(),
- <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>(), <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_body</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>See the <a href="../response_command">response command</a> for details.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_streamid">streamid()</h3>
-<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">streamid</span></span>() <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>The identifier for this stream.</p></div>
-<div class="paragraph"><p>The identifier is unique over the connection process.
-It is possible to form a unique identifier node-wide and
-cluster-wide by wrapping it in a <code>{self(), StreamID}</code>
-tuple.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Module introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="..">cowboy(7)</a>,
-<a href="../cowboy_http">cowboy_http(3)</a>,
-<a href="../cowboy_http2">cowboy_http2(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_handler - Stream handlers</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The module <code>cowboy_stream</code> defines a callback interface +and a protocol for handling HTTP streams.</p></div> +<div class="paragraph"><p>An HTTP request and its associated response is called +a stream. A connection may have many streams. In HTTP/1.1 +they are executed sequentially, while in HTTP/2 they are +executed concurrently.</p></div> +<div class="paragraph"><p>Cowboy calls the stream handler for nearly all events +related to a stream. Exceptions vary depending on the +protocol.</p></div> +<div class="paragraph"><p>Extra care must be taken when implementing stream handlers +to ensure compatibility. While some modification of the +events and commands is allowed, it is generally not a good +idea to completely omit them.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_callbacks">Callbacks</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Stream handlers must implement the following interface:</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">StreamID</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Commands</span>, <span style="color: #009900">State</span>} +<span style="font-weight: bold"><span style="color: #000000">data</span></span>(<span style="color: #009900">StreamID</span>, <span style="color: #009900">IsFin</span>, <span style="color: #009900">Data</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Commands</span>, <span style="color: #009900">State</span>} +<span style="font-weight: bold"><span style="color: #000000">info</span></span>(<span style="color: #009900">StreamID</span>, <span style="color: #009900">Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> {<span style="color: #009900">Commands</span>, <span style="color: #009900">State</span>} +<span style="font-weight: bold"><span style="color: #000000">terminate</span></span>(<span style="color: #009900">StreamID</span>, <span style="color: #009900">Reason</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() +<span style="font-weight: bold"><span style="color: #000000">early_error</span></span>(<span style="color: #009900">StreamID</span>, <span style="color: #009900">Reason</span>, <span style="color: #009900">PartialReq</span>, <span style="color: #009900">Resp</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span> <span style="color: #009900">Resp</span> + +<span style="color: #009900">StreamID</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_stream:streamid</span></span>() +<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>() +<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy:opts</span></span>() +<span style="color: #009900">Commands</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_stream:commands</span></span>() +<span style="color: #009900">State</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() +<span style="color: #009900">IsFin</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_stream:fin</span></span>() +<span style="color: #009900">Data</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() +<span style="color: #009900">Info</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() +<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_stream:reason</span></span>() +<span style="color: #009900">PartialReq</span> <span style="color: #990000">-</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>(), <span style="color: #FF6600">except</span> <span style="color: #FF6600">all</span> <span style="color: #FF6600">fields</span> <span style="color: #FF6600">are</span> <span style="color: #FF6600">optional</span> +<span style="color: #009900">Resp</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_stream:resp_command</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>HTTP/1.1 will initialize a stream only when the request-line +and all headers have been received. When errors occur before +that point Cowboy will call the callback <code>early_error/5</code> +with a partial request, the error reason and the response +Cowboy intends to send. All other events go throuh the +stream handler using the normal callbacks.</p></div> +<div class="paragraph"><p>HTTP/2 will initialize the stream when the <code>HEADERS</code> block has +been fully received and decoded. Any protocol error occuring +before that will not result in a response being sent and +will therefore not go through the stream handler. In addition +Cowboy may terminate streams without sending an HTTP response +back.</p></div> +<div class="paragraph"><p>The stream is initialized by calling <code>init/3</code>. All streams +that are initialized will eventually be terminated by calling +<code>terminate/3</code>.</p></div> +<div class="paragraph"><p>When Cowboy receives data for the stream it will call <code>data/4</code>. +The data given is the request body after any transfer decoding +has been applied.</p></div> +<div class="paragraph"><p>When Cowboy receives a message addressed to a stream, or when +Cowboy needs to inform the stream handler that an internal +event has occurred, it will call <code>info/3</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="commands">Commands</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Stream handlers can return a list of commands to be executed +from the <code>init/3</code>, <code>data/4</code> and <code>info/3</code> callbacks. In addition, +the <code>early_error/5</code> callback must return a response command.</p></div> +<div class="paragraph"><p>The following commands are defined:</p></div> +<div class="sect2"> +<h3 id="response_command">response</h3> +<div class="paragraph"><p>Send a response to the client.</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">response</span>, <span style="font-weight: bold"><span style="color: #000000">cowboy:http_status</span></span>(), <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>(), + <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_body</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>No more data can be sent after this command.</p></div> +</div> +<div class="sect2"> +<h3 id="headers_command">headers</h3> +<div class="paragraph"><p>Initiate a response to the client.</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="font-weight: bold"><span style="color: #000000">cowboy:http_status</span></span>(), <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>This initiates a response to the client. The stream +will end when a data command with the <code>fin</code> flag is +returned.</p></div> +</div> +<div class="sect2"> +<h3 id="data_command">data</h3> +<div class="paragraph"><p>Send data to the client.</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">data</span>, <span style="font-weight: bold"><span style="color: #000000">fin</span></span>(), <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()}</tt></pre></div></div> +</div> +<div class="sect2"> +<h3 id="push_command">push</h3> +<div class="paragraph"><p>Push a resource to the client.</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">push</span>, <span style="color: #009900">Method</span>, <span style="color: #009900">Scheme</span>, <span style="color: #009900">Host</span>, <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>(), + <span style="color: #009900">Path</span>, <span style="color: #009900">Qs</span>, <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>()} + +<span style="color: #009900">Method</span> <span style="color: #990000">=</span> <span style="color: #009900">Scheme</span> <span style="color: #990000">=</span> <span style="color: #009900">Host</span> <span style="color: #990000">=</span> <span style="color: #009900">Path</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: #000080">binary</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>The command will be ignored if the protocol does not provide +any server push mechanism.</p></div> +</div> +<div class="sect2"> +<h3 id="_flow">flow</h3> +<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">flow</span>, <span style="font-weight: bold"><span style="color: #000000">pos_integer</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Request more data to be read from the request body. The +exact behavior depends on the protocol.</p></div> +</div> +<div class="sect2"> +<h3 id="_spawn">spawn</h3> +<div class="paragraph"><p>Inform Cowboy that a process was spawned and should be +supervised.</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: #000080">spawn</span></span>, <span style="font-weight: bold"><span style="color: #000080">pid</span></span>(), <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()}</tt></pre></div></div> +</div> +<div class="sect2"> +<h3 id="_error_response">error_response</h3> +<div class="paragraph"><p>Send an error response if no response was sent previously.</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">error_response</span>, <span style="font-weight: bold"><span style="color: #000000">cowboy:http_status</span></span>(), <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>(), <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()}</tt></pre></div></div> +</div> +<div class="sect2"> +<h3 id="switch_protocol_command">switch_protocol</h3> +<div class="paragraph"><p>Switch to a different protocol.</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">switch_protocol</span>, <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>(), <span style="font-weight: bold"><span style="color: #000000">module</span></span>(), <span style="font-weight: bold"><span style="color: #000000">state</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Contains the headers that will be sent in the 101 response, +along with the module implementing the protocol we are +switching to and its initial state.</p></div> +</div> +<div class="sect2"> +<h3 id="_stop">stop</h3> +<div class="paragraph"><p>Stop the stream.</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">stop</span></tt></pre></div></div> +<div class="paragraph"><p>While no more data can be sent after the <code>fin</code> flag was set, +the stream is still tracked by Cowboy until it is stopped by +the handler.</p></div> +<div class="paragraph"><p>The behavior when stopping a stream for which no response +has been sent will vary depending on the protocol. The stream +will end successfully as far as the client is concerned.</p></div> +<div class="paragraph"><p>To indicate that an error occurred, either use <code>error_response</code> +before stopping, or use <code>internal_error</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_internal_error">internal_error</h3> +<div class="paragraph"><p>Stop the stream with an error.</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">internal_error</span>, <span style="color: #009900">Reason</span>, <span style="color: #009900">HumanReadable</span>} + +<span style="color: #009900">Reason</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() +<span style="color: #009900">HumanReadable</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>This command should be used when the stream cannot continue +because of an internal error. An <code>error_response</code> command +may be sent before that to advertise to the client why the +stream is dropped.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_predefined_events">Predefined events</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy will forward all messages sent to the stream to +the <code>info/3</code> callback. To send a message to a stream, +send a message to the connection process with the form +<code>{{Pid, StreamID}, Msg}</code>. The connection process will +then forward <code>Msg</code> to the stream handlers.</p></div> +<div class="paragraph"><p>Cowboy will also forward the exit signals for the +processes that the stream spawned.</p></div> +<div class="sect2"> +<h3 id="_exit">EXIT</h3> +<div class="paragraph"><p>A process spawned by this stream has exited.</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: #000080">'EXIT'</span>, <span style="font-weight: bold"><span style="color: #000080">pid</span></span>(), <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>This is the raw exit message without any modification.</p></div> +</div> +<div class="sect2"> +<h3 id="_response">response</h3> +<div class="paragraph"><p>Same as the <a href="../response_command">response command</a>.</p></div> +<div class="paragraph"><p>Usually sent when the request process replies to the client. +May also be sent by Cowboy internally.</p></div> +</div> +<div class="sect2"> +<h3 id="_headers">headers</h3> +<div class="paragraph"><p>Same as the <a href="../headers_command">headers command</a>.</p></div> +<div class="paragraph"><p>Sent when the request process starts replying to the client.</p></div> +</div> +<div class="sect2"> +<h3 id="_data">data</h3> +<div class="paragraph"><p>Same as the <a href="../data_command">data command</a>.</p></div> +<div class="paragraph"><p>Sent when the request process streams data to the client.</p></div> +</div> +<div class="sect2"> +<h3 id="_push">push</h3> +<div class="paragraph"><p>Same as the <a href="../push_command">push command</a>.</p></div> +<div class="paragraph"><p>Sent when the request process pushes a resource to the client.</p></div> +</div> +<div class="sect2"> +<h3 id="_switch_protocol">switch_protocol</h3> +<div class="paragraph"><p>Same as the <a href="../switch_protocol_command">switch_protocol command</a>.</p></div> +<div class="paragraph"><p>Sent when switching to the HTTP/2 or Websocket protocol.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The following function should be called by modules implementing +stream handlers to execute the next stream handler in the list:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="../cowboy_stream.init">cowboy_stream:init(3)</a> - Initialize a stream +</p> +</li> +<li> +<p> +<a href="../cowboy_stream.data">cowboy_stream:data(3)</a> - Handle data for a stream +</p> +</li> +<li> +<p> +<a href="../cowboy_stream.info">cowboy_stream:info(3)</a> - Handle a message for a stream +</p> +</li> +<li> +<p> +<a href="../cowboy_stream.terminate">cowboy_stream:terminate(3)</a> - Terminate a stream +</p> +</li> +<li> +<p> +<a href="../cowboy_stream.early_error">cowboy_stream:early_error(3)</a> - Handle an early error for a stream +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_commands">commands()</h3> +<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">commands</span></span>() <span style="color: #990000">::</span> [<span style="color: #009900">Command</span>]</tt></pre></div></div> +<div class="paragraph"><p>See the <a href="../commands">list of commands</a> for details.</p></div> +</div> +<div class="sect2"> +<h3 id="_fin">fin()</h3> +<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">fin</span></span>() <span style="color: #990000">::</span> <span style="color: #FF6600">fin</span> | <span style="color: #FF6600">nofin</span></tt></pre></div></div> +<div class="paragraph"><p>Used in commands and events to indicate that this is +the end of the stream.</p></div> +</div> +<div class="sect2"> +<h3 id="_partial_req">partial_req()</h3> +<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">req</span></span>() <span style="color: #990000">::</span> #{ + <span style="color: #0000FF">method</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> + <span style="color: #0000FF">version</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_version</span></span>() | <span style="font-weight: bold"><span style="color: #000080">atom</span></span>(), + <span style="color: #0000FF">scheme</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span> + <span style="color: #0000FF">host</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% lowercase; case insensitive</span></span> + <span style="color: #0000FF">port</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>(), + <span style="color: #0000FF">path</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> + <span style="color: #0000FF">qs</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> + <span style="color: #0000FF">headers</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>(), + <span style="color: #0000FF">peer</span> <span style="color: #990000">=></span> {<span style="font-weight: bold"><span style="color: #000000">inet:ip_address</span></span>(), <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>()} +}</tt></pre></div></div> +<div class="paragraph"><p>Partial request information received when an early error is +detected.</p></div> +</div> +<div class="sect2"> +<h3 id="_reason">reason()</h3> +<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">reason</span></span>() <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">normal</span></span> + | {<span style="color: #FF6600">internal_error</span>, <span style="color: #FF6600">timeout</span> | {<span style="color: #FF6600">error</span> | <span style="font-weight: bold"><span style="color: #000080">exit</span></span> | <span style="font-weight: bold"><span style="color: #000080">throw</span></span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}, <span style="color: #009900">HumanReadable</span>} + | {<span style="color: #FF6600">socket_error</span>, <span style="color: #FF6600">closed</span> | <span style="font-weight: bold"><span style="color: #000080">atom</span></span>(), <span style="color: #009900">HumanReadable</span>} + | {<span style="color: #FF6600">stream_error</span>, <span style="color: #009900">Error</span>, <span style="color: #009900">HumanReadable</span>} + | {<span style="color: #FF6600">connection_error</span>, <span style="color: #009900">Error</span>, <span style="color: #009900">HumanReadable</span>} + | {<span style="color: #FF6600">stop</span>, <span style="font-weight: bold"><span style="color: #000000">cow_http2:frame</span></span>(), <span style="color: #009900">HumanReadable</span>} + +<span style="color: #009900">Error</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>() +<span style="color: #009900">HumanReadable</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Reason for the stream termination.</p></div> +</div> +<div class="sect2"> +<h3 id="_resp_command">resp_command()</h3> +<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">resp_command</span></span>() <span style="color: #990000">::</span> {<span style="color: #FF6600">response</span>, <span style="font-weight: bold"><span style="color: #000000">cowboy:http_status</span></span>(), + <span style="font-weight: bold"><span style="color: #000000">cowboy:http_headers</span></span>(), <span style="font-weight: bold"><span style="color: #000000">cowboy_req:resp_body</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>See the <a href="../response_command">response command</a> for details.</p></div> +</div> +<div class="sect2"> +<h3 id="_streamid">streamid()</h3> +<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">streamid</span></span>() <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>The identifier for this stream.</p></div> +<div class="paragraph"><p>The identifier is unique over the connection process. +It is possible to form a unique identifier node-wide and +cluster-wide by wrapping it in a <code>{self(), StreamID}</code> +tuple.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Module introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="..">cowboy(7)</a>, +<a href="../cowboy_http">cowboy_http(3)</a>, +<a href="../cowboy_http2">cowboy_http2(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/cowboy_websocket/index.html b/docs/en/cowboy/2.0/manual/cowboy_websocket/index.html index f09890a8..8903a079 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_websocket/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_websocket/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_websocket(3)</title> @@ -67,277 +67,295 @@ <h1 class="lined-header"><span>cowboy_websocket(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_websocket - Websocket</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The module <code>cowboy_websocket</code> implements Websocket
-as a Ranch protocol. It also defines a callback interface
-for handling Websocket connections.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_callbacks">Callbacks</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Websocket handlers must implement the following callback
-interface:</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">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: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #009900">Opts</span>}
-
-<span style="font-weight: bold"><span style="color: #000000">websocket_init</span></span>(<span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #009900">CallResult</span> <span style="font-style: italic"><span style="color: #9A1900">%% optional</span></span>
-<span style="font-weight: bold"><span style="color: #000000">websocket_handle</span></span>(<span style="color: #009900">InFrame</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #009900">CallResult</span>
-<span style="font-weight: bold"><span style="color: #000000">websocket_info</span></span>(<span style="color: #009900">Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #009900">CallResult</span>
-
-<span style="font-weight: bold"><span style="color: #000000">terminate</span></span>(<span style="color: #009900">Reason</span>, <span style="color: #000080">undefined</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span> <span style="font-style: italic"><span style="color: #9A1900">%% optional</span></span>
-
-<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()
-<span style="color: #009900">State</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
-<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_websocket:opts</span></span>()
-<span style="color: #009900">InFrame</span> <span style="color: #990000">::</span> {<span style="color: #FF6600">text</span> | <span style="font-weight: bold"><span style="color: #000080">binary</span></span> | <span style="color: #FF6600">ping</span> | <span style="color: #FF6600">pong</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}
-<span style="color: #009900">OutFrame</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cow_ws:frame</span></span>()
-<span style="color: #009900">Info</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
-
-<span style="color: #009900">CallResult</span> <span style="color: #990000">::</span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>}
- | {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}
- | {<span style="color: #FF6600">reply</span>, <span style="color: #009900">OutFrame</span> | [<span style="color: #009900">OutFrame</span>], <span style="color: #009900">State</span>}
- | {<span style="color: #FF6600">reply</span>, <span style="color: #009900">OutFrame</span> | [<span style="color: #009900">OutFrame</span>], <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>}
- | {<span style="color: #FF6600">stop</span>, <span style="color: #009900">State</span>}
-
-<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">normal</span></span> | <span style="color: #FF6600">stop</span> | <span style="color: #FF6600">timeout</span>
- | <span style="color: #FF6600">remote</span> | {<span style="color: #FF6600">remote</span>, <span style="font-weight: bold"><span style="color: #000000">cow_ws:close_code</span></span>(), <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}
- | {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">badencoding</span> | <span style="color: #FF6600">badframe</span> | <span style="color: #FF6600">closed</span> | <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()}
- | {<span style="color: #FF6600">crash</span>, <span style="color: #FF6600">error</span> | <span style="font-weight: bold"><span style="color: #000080">exit</span></span> | <span style="font-weight: bold"><span style="color: #000080">throw</span></span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>The <code>init/2</code> callback is common to all handlers. To upgrade
-the connection to Websocket, it must return <code>cowboy_websocket</code>
-as the first element of the tuple.</p></div>
-<div class="paragraph"><p>Any operation requiring the HTTP request must be done in the
-<code>init/2</code> function, as the Req object will not be available
-after it returns. Websocket sub-protocol selection should
-therefore be done in this function.</p></div>
-<div class="paragraph"><p>The optional <code>websocket_init/1</code> callback will be called once
-the connection has been upgraded to Websocket. It can be used
-to perform any required initialization of the handler.</p></div>
-<div class="paragraph"><p>Note that the <code>init/2</code> function does not run in the same
-process as the Websocket callbacks. Any Websocket-specific
-initialization must be done in <code>websocket_init/1</code>.</p></div>
-<div class="paragraph"><p>The <code>websocket_handle/2</code> callback will be called for every
-frame received. The <code>websocket_info/2</code> callback will be
-called for every Erlang message received.</p></div>
-<div class="paragraph"><p>All three Websocket callbacks may send one or more frames
-back to the client (by returning a <code>reply</code> tuple) or terminate
-the connection (by sending a <code>close</code> frame or returning a <code>stop</code>
-tuple).</p></div>
-<div class="paragraph"><p>The optional <code>terminate/3</code> callback will ultimately be called
-with the reason for the termination of the connection. This
-callback is common to all handlers. Note that Websocket has
-no concept of requests so it sets the second argument to
-undefined.</p></div>
-<div class="paragraph"><p>Cowboy will terminate the process right after closing the
-Websocket connection. This means that there is no need to
-perform any cleanup in the <code>terminate/3</code> callback.</p></div>
-<div class="paragraph"><p>The following terminate reasons are defined for Websocket
-connections:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-normal
-</dt>
-<dd>
-<p>
- The connection was closed normally before establishing a Websocket
- connection. This typically happens if an <code>ok</code> tuple is returned
- from the <code>init/2</code> callback.
-</p>
-</dd>
-<dt class="hdlist1">
-remote
-</dt>
-<dd>
-<p>
- The remote endpoint closed the connection without giving any
- further details.
-</p>
-</dd>
-<dt class="hdlist1">
-{remote, Code, Payload}
-</dt>
-<dd>
-<p>
- The remote endpoint closed the connection with the given
- <code>Code</code> and <code>Payload</code> as the reason.
-</p>
-</dd>
-<dt class="hdlist1">
-stop
-</dt>
-<dd>
-<p>
- The handler requested to close the connection, either by returning
- a <code>stop</code> tuple or by sending a <code>close</code> frame.
-</p>
-</dd>
-<dt class="hdlist1">
-timeout
-</dt>
-<dd>
-<p>
- The connection has been closed due to inactivity. The timeout
- value can be configured from <code>init/2</code>.
-</p>
-</dd>
-<dt class="hdlist1">
-{crash, Class, Reason}
-</dt>
-<dd>
-<p>
- A crash occurred in the handler. <code>Class</code> and <code>Reason</code> can be
- used to obtain more information about the crash. The function
- <code>erlang:get_stacktrace/0</code> can also be called to obtain the
- stacktrace of the process when the crash occurred.
-</p>
-</dd>
-<dt class="hdlist1">
-{error, badencoding}
-</dt>
-<dd>
-<p>
- A text frame was sent by the client with invalid encoding. All
- text frames must be valid UTF-8.
-</p>
-</dd>
-<dt class="hdlist1">
-{error, badframe}
-</dt>
-<dd>
-<p>
- A protocol error has been detected.
-</p>
-</dd>
-<dt class="hdlist1">
-{error, closed}
-</dt>
-<dd>
-<p>
- The socket has been closed brutally without a close frame being
- received first.
-</p>
-</dd>
-<dt class="hdlist1">
-{error, Reason}
-</dt>
-<dd>
-<p>
- A socket error ocurred.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_opts">opts()</h3>
-<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">opts</span></span>() <span style="color: #990000">::</span> #{
- <span style="color: #0000FF">compress</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>(),
- <span style="color: #0000FF">idle_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(),
- <span style="color: #0000FF">req_filter</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>((<span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">map</span></span>())
-}</tt></pre></div></div>
-<div class="paragraph"><p>Websocket handler options.</p></div>
-<div class="paragraph"><p>This configuration is passed to Cowboy from the <code>init/2</code>
-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">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span>
- <span style="color: #009900">Opts</span> <span style="color: #990000">=</span> #{<span style="color: #0000FF">compress</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>},
- {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #009900">Opts</span>}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The default value is given next to the option name:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-compress (false)
-</dt>
-<dd>
-<p>
- Whether to enable the Websocket frame compression
- extension. Frames will only be compressed for the
- clients that support this extension.
-</p>
-</dd>
-<dt class="hdlist1">
-idle_timeout (60000)
-</dt>
-<dd>
-<p>
- Time in milliseconds that Cowboy will keep the
- connection open without receiving anything from
- the client.
-</p>
-</dd>
-<dt class="hdlist1">
-req_filter
-</dt>
-<dd>
-<p>
- A function applied to the Req to compact it and
- only keep required information. The Req is only
- given back in the <code>terminate/3</code> callback. By default
- it keeps the method, version, URI components and peer
- information.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: The Req object is no longer passed to Websocket callbacks.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: The callback <code>websocket_terminate/3</code> was removed in favor of <code>terminate/3</code>.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Protocol introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="..">cowboy(7)</a>,
-<a href="../cowboy_handler">cowboy_handler(3)</a>,
-<a href="../cowboy_http">cowboy_http(3)</a>,
-<a href="../cowboy_http2">cowboy_http2(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_websocket - Websocket</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The module <code>cowboy_websocket</code> implements Websocket +as a Ranch protocol. It also defines a callback interface +for handling Websocket connections.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_callbacks">Callbacks</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Websocket handlers must implement the following callback +interface:</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">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: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #009900">Opts</span>} + +<span style="font-weight: bold"><span style="color: #000000">websocket_init</span></span>(<span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #009900">CallResult</span> <span style="font-style: italic"><span style="color: #9A1900">%% optional</span></span> +<span style="font-weight: bold"><span style="color: #000000">websocket_handle</span></span>(<span style="color: #009900">InFrame</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #009900">CallResult</span> +<span style="font-weight: bold"><span style="color: #000000">websocket_info</span></span>(<span style="color: #009900">Info</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #009900">CallResult</span> + +<span style="font-weight: bold"><span style="color: #000000">terminate</span></span>(<span style="color: #009900">Reason</span>, <span style="color: #009900">PartialReq</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> <span style="color: #FF6600">ok</span> <span style="font-style: italic"><span style="color: #9A1900">%% optional</span></span> + +<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>() +<span style="color: #009900">PartialReq</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">map</span></span>() +<span style="color: #009900">State</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() +<span style="color: #009900">Opts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_websocket:opts</span></span>() +<span style="color: #009900">InFrame</span> <span style="color: #990000">::</span> {<span style="color: #FF6600">text</span> | <span style="font-weight: bold"><span style="color: #000080">binary</span></span> | <span style="color: #FF6600">ping</span> | <span style="color: #FF6600">pong</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()} +<span style="color: #009900">OutFrame</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cow_ws:frame</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% see types below</span></span> +<span style="color: #009900">Info</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() + +<span style="color: #009900">CallResult</span> <span style="color: #990000">::</span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>} + | {<span style="color: #FF6600">ok</span>, <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>} + | {<span style="color: #FF6600">reply</span>, <span style="color: #009900">OutFrame</span> | [<span style="color: #009900">OutFrame</span>], <span style="color: #009900">State</span>} + | {<span style="color: #FF6600">reply</span>, <span style="color: #009900">OutFrame</span> | [<span style="color: #009900">OutFrame</span>], <span style="color: #009900">State</span>, <span style="color: #FF6600">hibernate</span>} + | {<span style="color: #FF6600">stop</span>, <span style="color: #009900">State</span>} + +<span style="color: #009900">Reason</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">normal</span></span> | <span style="color: #FF6600">stop</span> | <span style="color: #FF6600">timeout</span> + | <span style="color: #FF6600">remote</span> | {<span style="color: #FF6600">remote</span>, <span style="font-weight: bold"><span style="color: #000000">cow_ws:close_code</span></span>(), <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()} + | {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">badencoding</span> | <span style="color: #FF6600">badframe</span> | <span style="color: #FF6600">closed</span> | <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()} + | {<span style="color: #FF6600">crash</span>, <span style="color: #FF6600">error</span> | <span style="font-weight: bold"><span style="color: #000080">exit</span></span> | <span style="font-weight: bold"><span style="color: #000080">throw</span></span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>The <code>init/2</code> callback is common to all handlers. To upgrade +the connection to Websocket, it must return <code>cowboy_websocket</code> +as the first element of the tuple.</p></div> +<div class="paragraph"><p>Any operation requiring the HTTP request must be done in the +<code>init/2</code> function, as the Req object will not be available +after it returns. Websocket sub-protocol selection should +therefore be done in this function.</p></div> +<div class="paragraph"><p>The optional <code>websocket_init/1</code> callback will be called once +the connection has been upgraded to Websocket. It can be used +to perform any required initialization of the handler.</p></div> +<div class="paragraph"><p>Note that the <code>init/2</code> function does not run in the same +process as the Websocket callbacks. Any Websocket-specific +initialization must be done in <code>websocket_init/1</code>.</p></div> +<div class="paragraph"><p>The <code>websocket_handle/2</code> callback will be called for every +frame received. The <code>websocket_info/2</code> callback will be +called for every Erlang message received.</p></div> +<div class="paragraph"><p>All three Websocket callbacks may send one or more frames +back to the client (by returning a <code>reply</code> tuple) or terminate +the connection (by sending a <code>close</code> frame or returning a <code>stop</code> +tuple).</p></div> +<div class="paragraph"><p>The optional <code>terminate/3</code> callback will ultimately be called +with the reason for the termination of the connection. This +callback is common to all handlers. Note that Websocket will +not provide the full Req object by default, to save memory.</p></div> +<div class="paragraph"><p>Cowboy will terminate the process right after closing the +Websocket connection. This means that there is no need to +perform any cleanup in the <code>terminate/3</code> callback.</p></div> +<div class="paragraph"><p>The following terminate reasons are defined for Websocket +connections:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +normal +</dt> +<dd> +<p> + The connection was closed normally before establishing a Websocket + connection. This typically happens if an <code>ok</code> tuple is returned + from the <code>init/2</code> callback. +</p> +</dd> +<dt class="hdlist1"> +remote +</dt> +<dd> +<p> + The remote endpoint closed the connection without giving any + further details. +</p> +</dd> +<dt class="hdlist1"> +{remote, Code, Payload} +</dt> +<dd> +<p> + The remote endpoint closed the connection with the given + <code>Code</code> and <code>Payload</code> as the reason. +</p> +</dd> +<dt class="hdlist1"> +stop +</dt> +<dd> +<p> + The handler requested to close the connection, either by returning + a <code>stop</code> tuple or by sending a <code>close</code> frame. +</p> +</dd> +<dt class="hdlist1"> +timeout +</dt> +<dd> +<p> + The connection has been closed due to inactivity. The timeout + value can be configured from <code>init/2</code>. +</p> +</dd> +<dt class="hdlist1"> +{crash, Class, Reason} +</dt> +<dd> +<p> + A crash occurred in the handler. <code>Class</code> and <code>Reason</code> can be + used to obtain more information about the crash. The function + <code>erlang:get_stacktrace/0</code> can also be called to obtain the + stacktrace of the process when the crash occurred. +</p> +</dd> +<dt class="hdlist1"> +{error, badencoding} +</dt> +<dd> +<p> + A text frame was sent by the client with invalid encoding. All + text frames must be valid UTF-8. +</p> +</dd> +<dt class="hdlist1"> +{error, badframe} +</dt> +<dd> +<p> + A protocol error has been detected. +</p> +</dd> +<dt class="hdlist1"> +{error, closed} +</dt> +<dd> +<p> + The socket has been closed brutally without a close frame being + received first. +</p> +</dd> +<dt class="hdlist1"> +{error, Reason} +</dt> +<dd> +<p> + A socket error ocurred. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect3"> +<h4 id="_cow_ws_frame">cow_ws:frame()</h4> +<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">frame</span></span>() <span style="color: #990000">::</span> {<span style="color: #FF6600">text</span>, <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()} + | {<span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()} + | <span style="color: #FF6600">ping</span> | {<span style="color: #FF6600">ping</span>, <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()} + | <span style="color: #FF6600">pong</span> | {<span style="color: #FF6600">pong</span>, <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()} + | <span style="color: #FF6600">close</span> | {<span style="color: #FF6600">close</span>, <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()} | {<span style="color: #FF6600">close</span>, <span style="font-weight: bold"><span style="color: #000000">close_code</span></span>(), <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()} + +<span style="font-weight: bold"><span style="color: #000000">close_code</span></span>() <span style="color: #990000">::</span> <span style="color: #993399">1000</span><span style="color: #990000">..</span><span style="color: #993399">1003</span> | <span style="color: #993399">1006</span><span style="color: #990000">..</span><span style="color: #993399">1011</span> | <span style="color: #993399">3000</span><span style="color: #990000">..</span><span style="color: #993399">4999</span></tt></pre></div></div> +<div class="paragraph"><p>Websocket frames that can be sent as a response.</p></div> +<div class="paragraph"><p>Note that there is no need to send pong frames back as +Cowboy does it automatically for you.</p></div> +</div> +<div class="sect2"> +<h3 id="_opts">opts()</h3> +<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">opts</span></span>() <span style="color: #990000">::</span> #{ + <span style="color: #0000FF">compress</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>(), + <span style="color: #0000FF">idle_timeout</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>(), + <span style="color: #0000FF">req_filter</span> <span style="color: #990000">=></span> <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>((<span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">map</span></span>()) +}</tt></pre></div></div> +<div class="paragraph"><p>Websocket handler options.</p></div> +<div class="paragraph"><p>This configuration is passed to Cowboy from the <code>init/2</code> +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">init</span></span>(<span style="color: #009900">Req</span>, <span style="color: #009900">State</span>) <span style="color: #990000">-></span> + <span style="color: #009900">Opts</span> <span style="color: #990000">=</span> #{<span style="color: #0000FF">compress</span> <span style="color: #990000">=></span> <span style="color: #000080">true</span>}, + {<span style="color: #FF6600">cowboy_websocket</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">State</span>, <span style="color: #009900">Opts</span>}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The default value is given next to the option name:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +compress (false) +</dt> +<dd> +<p> + Whether to enable the Websocket frame compression + extension. Frames will only be compressed for the + clients that support this extension. +</p> +</dd> +<dt class="hdlist1"> +idle_timeout (60000) +</dt> +<dd> +<p> + Time in milliseconds that Cowboy will keep the + connection open without receiving anything from + the client. +</p> +</dd> +<dt class="hdlist1"> +req_filter +</dt> +<dd> +<p> + A function applied to the Req to compact it and + only keep required information. The Req is only + given back in the <code>terminate/3</code> callback. By default + it keeps the method, version, URI components and peer + information. +</p> +</dd> +</dl></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: The Req object is no longer passed to Websocket callbacks. +</p> +</li> +<li> +<p> +<strong>2.0</strong>: The callback <code>websocket_terminate/3</code> was removed in favor of <code>terminate/3</code>. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Protocol introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="..">cowboy(7)</a>, +<a href="../cowboy_handler">cowboy_handler(3)</a>, +<a href="../cowboy_http">cowboy_http(3)</a>, +<a href="../cowboy_http2">cowboy_http2(3)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/http_status_codes/index.html b/docs/en/cowboy/2.0/manual/http_status_codes/index.html index 7f94b815..31b3296d 100644 --- a/docs/en/cowboy/2.0/manual/http_status_codes/index.html +++ b/docs/en/cowboy/2.0/manual/http_status_codes/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: HTTP status codes(7)</title> @@ -67,271 +67,271 @@ <h1 class="lined-header"><span>HTTP status codes(7)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>HTTP status codes - status codes used by Cowboy</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This chapter aims to list all HTTP status codes that Cowboy
-may return, with details on the reasons why. The list given
-here only includes the replies that Cowboy sends, not user
-replies.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_100_continue">100 Continue</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>When the client sends an <code>expect: 100-continue</code> header,
-Cowboy automatically sends a this status code before
-trying to read the request body. This behavior can be
-disabled using the appropriate body option.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_101_switching_protocols">101 Switching Protocols</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This is the status code sent when switching to the
-Websocket protocol.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_200_ok">200 OK</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_201_created">201 Created</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_202_accepted">202 Accepted</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_204_no_content">204 No Content</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent when the processing of a request
-ends without any reply having been sent. It may also be
-sent by <code>cowboy_rest</code> under normal conditions.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_300_multiple_choices">300 Multiple Choices</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_301_moved_permanently">301 Moved Permanently</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_303_see_other">303 See Other</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_304_not_modified">304 Not Modified</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_307_temporary_redirect">307 Temporary Redirect</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_400_bad_request">400 Bad Request</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy will send this status code for any of the
-following reasons:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Too many empty lines were sent before the request.
-</p>
-</li>
-<li>
-<p>
-The request-line could not be parsed.
-</p>
-</li>
-<li>
-<p>
-Too many headers were sent.
-</p>
-</li>
-<li>
-<p>
-A header name was too long.
-</p>
-</li>
-<li>
-<p>
-A header value was too long.
-</p>
-</li>
-<li>
-<p>
-The host header was missing from an HTTP/1.1 request.
-</p>
-</li>
-<li>
-<p>
-The host header could not be parsed.
-</p>
-</li>
-<li>
-<p>
-The requested host was not found.
-</p>
-</li>
-<li>
-<p>
-The requested path could not be parsed.
-</p>
-</li>
-<li>
-<p>
-The accept header could not be parsed when using REST.
-</p>
-</li>
-<li>
-<p>
-REST under normal conditions.
-</p>
-</li>
-<li>
-<p>
-A Websocket upgrade failed.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_401_unauthorized">401 Unauthorized</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_403_forbidden">403 Forbidden</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_404_not_found">404 Not Found</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent when the router successfully
-resolved the host but didn’t find a matching path for
-the request. It may also be sent by <code>cowboy_rest</code> under
-normal conditions.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_405_method_not_allowed">405 Method Not Allowed</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_406_not_acceptable">406 Not Acceptable</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_408_request_timeout">408 Request Timeout</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy will send this status code to the client if the
-client started to send a request, indicated by the
-request-line being received fully, but failed to send
-all headers in a reasonable time.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_409_conflict">409 Conflict</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_410_gone">410 Gone</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_412_precondition_failed">412 Precondition Failed</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_413_request_entity_too_large">413 Request Entity Too Large</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_414_request_uri_too_long">414 Request-URI Too Long</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy will send this status code to the client if the
-request-line is too long. It may also be sent by
-<code>cowboy_rest</code> under normal conditions.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_415_unsupported_media_type">415 Unsupported Media Type</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_500_internal_server_error">500 Internal Server Error</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent when a crash occurs in HTTP, loop
-or REST handlers, or when an invalid return value is
-returned. It may also be sent by <code>cowboy_rest</code> under
-normal conditions.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_501_not_implemented">501 Not Implemented</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_503_service_unavailable">503 Service Unavailable</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_505_http_version_not_supported">505 HTTP Version Not Supported</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy only supports the versions 1.0 and 1.1 of HTTP.
-In all other cases this status code is sent back to the
-client and the connection is closed.</p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>HTTP status codes - status codes used by Cowboy</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This chapter aims to list all HTTP status codes that Cowboy +may return, with details on the reasons why. The list given +here only includes the replies that Cowboy sends, not user +replies.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_100_continue">100 Continue</h2> +<div class="sectionbody"> +<div class="paragraph"><p>When the client sends an <code>expect: 100-continue</code> header, +Cowboy automatically sends a this status code before +trying to read the request body. This behavior can be +disabled using the appropriate body option.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_101_switching_protocols">101 Switching Protocols</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This is the status code sent when switching to the +Websocket protocol.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_200_ok">200 OK</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_201_created">201 Created</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_202_accepted">202 Accepted</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_204_no_content">204 No Content</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent when the processing of a request +ends without any reply having been sent. It may also be +sent by <code>cowboy_rest</code> under normal conditions.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_300_multiple_choices">300 Multiple Choices</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_301_moved_permanently">301 Moved Permanently</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_303_see_other">303 See Other</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_304_not_modified">304 Not Modified</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_307_temporary_redirect">307 Temporary Redirect</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_400_bad_request">400 Bad Request</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy will send this status code for any of the +following reasons:</p></div> +<div class="ulist"><ul> +<li> +<p> +Too many empty lines were sent before the request. +</p> +</li> +<li> +<p> +The request-line could not be parsed. +</p> +</li> +<li> +<p> +Too many headers were sent. +</p> +</li> +<li> +<p> +A header name was too long. +</p> +</li> +<li> +<p> +A header value was too long. +</p> +</li> +<li> +<p> +The host header was missing from an HTTP/1.1 request. +</p> +</li> +<li> +<p> +The host header could not be parsed. +</p> +</li> +<li> +<p> +The requested host was not found. +</p> +</li> +<li> +<p> +The requested path could not be parsed. +</p> +</li> +<li> +<p> +The accept header could not be parsed when using REST. +</p> +</li> +<li> +<p> +REST under normal conditions. +</p> +</li> +<li> +<p> +A Websocket upgrade failed. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_401_unauthorized">401 Unauthorized</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_403_forbidden">403 Forbidden</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_404_not_found">404 Not Found</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent when the router successfully +resolved the host but didn’t find a matching path for +the request. It may also be sent by <code>cowboy_rest</code> under +normal conditions.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_405_method_not_allowed">405 Method Not Allowed</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_406_not_acceptable">406 Not Acceptable</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_408_request_timeout">408 Request Timeout</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy will send this status code to the client if the +client started to send a request, indicated by the +request-line being received fully, but failed to send +all headers in a reasonable time.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_409_conflict">409 Conflict</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_410_gone">410 Gone</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_412_precondition_failed">412 Precondition Failed</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_413_request_entity_too_large">413 Request Entity Too Large</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_414_request_uri_too_long">414 Request-URI Too Long</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy will send this status code to the client if the +request-line is too long. It may also be sent by +<code>cowboy_rest</code> under normal conditions.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_415_unsupported_media_type">415 Unsupported Media Type</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_500_internal_server_error">500 Internal Server Error</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent when a crash occurs in HTTP, loop +or REST handlers, or when an invalid return value is +returned. It may also be sent by <code>cowboy_rest</code> under +normal conditions.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_501_not_implemented">501 Not Implemented</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_503_service_unavailable">503 Service Unavailable</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_505_http_version_not_supported">505 HTTP Version Not Supported</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy only supports the versions 1.0 and 1.1 of HTTP. +In all other cases this status code is sent back to the +client and the connection is closed.</p></div> +</div> +</div> diff --git a/docs/en/cowboy/2.0/manual/index.html b/docs/en/cowboy/2.0/manual/index.html index 24286315..aec2688c 100644 --- a/docs/en/cowboy/2.0/manual/index.html +++ b/docs/en/cowboy/2.0/manual/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Cowboy Function Reference</title> @@ -67,166 +67,171 @@ <h1 class="lined-header"><span>Cowboy Function Reference</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy - Small, fast, modern HTTP server for Erlang/OTP</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy is an HTTP server for Erlang/OTP with support for the
-HTTP/1.1, HTTP/2 and Websocket protocols.</p></div>
-<div class="paragraph"><p>Cowboy aims to provide a complete HTTP stack. This includes
-the implementation of the HTTP RFCs but also any directly
-related standards, like Websocket or Server-Sent Events.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_modules">Modules</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Functions:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="cowboy">cowboy(3)</a> - Listener management
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_req">cowboy_req(3)</a> - Request and response
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_router">cowboy_router(3)</a> - Router
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Protocols:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="cowboy_http">cowboy_http(3)</a> - HTTP/1.1
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_http2">cowboy_http2(3)</a> - HTTP/2
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_websocket">cowboy_websocket(3)</a> - Websocket
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Handlers:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="cowboy_static">cowboy_static(3)</a> - Static file handler
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Behaviors:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="cowboy_handler">cowboy_handler(3)</a> - Plain HTTP handlers
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_loop">cowboy_loop(3)</a> - Loop handlers
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_middleware">cowboy_middleware(3)</a> - Middlewares
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_rest">cowboy_rest(3)</a> - REST handlers
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_stream">cowboy_stream(3)</a> - Stream handlers
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_websocket">cowboy_websocket(3)</a> - Websocket handlers
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Middlewares:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="cowboy_router">cowboy_router(3)</a> - Router middleware
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_handler">cowboy_handler(3)</a> - Handler middleware
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_dependencies">Dependencies</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="/docs">ranch(7)</a> - Socket acceptor pool for TCP protocols
-</p>
-</li>
-<li>
-<p>
-<a href="/docs">cowlib(7)</a> - Support library for manipulating Web protocols
-</p>
-</li>
-<li>
-<p>
-ssl - Secure communication over sockets
-</p>
-</li>
-<li>
-<p>
-crypto - Crypto functions
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>All these applications must be started before the <code>cowboy</code>
-application. To start Cowboy and all dependencies at once:</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: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">application:ensure_all_started</span></span>(<span style="color: #FF6600">cowboy</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_environment">Environment</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>cowboy</code> application does not define any application
-environment configuration parameters.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="/docs">ranch(7)</a>,
-<a href="/docs">cowlib(7)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy - Small, fast, modern HTTP server for Erlang/OTP</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Cowboy is an HTTP server for Erlang/OTP with support for the +HTTP/1.1, HTTP/2 and Websocket protocols.</p></div> +<div class="paragraph"><p>Cowboy aims to provide a complete HTTP stack. This includes +the implementation of the HTTP RFCs but also any directly +related standards, like Websocket or Server-Sent Events.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_modules">Modules</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Functions:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="cowboy">cowboy(3)</a> - Listener management +</p> +</li> +<li> +<p> +<a href="cowboy_req">cowboy_req(3)</a> - Request and response +</p> +</li> +<li> +<p> +<a href="cowboy_router">cowboy_router(3)</a> - Router +</p> +</li> +<li> +<p> +<a href="cowboy_constraints">cowboy_constraints(3)</a> - Constraints +</p> +</li> +</ul></div> +<div class="paragraph"><p>Protocols:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="cowboy_http">cowboy_http(3)</a> - HTTP/1.1 +</p> +</li> +<li> +<p> +<a href="cowboy_http2">cowboy_http2(3)</a> - HTTP/2 +</p> +</li> +<li> +<p> +<a href="cowboy_websocket">cowboy_websocket(3)</a> - Websocket +</p> +</li> +</ul></div> +<div class="paragraph"><p>Handlers:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="cowboy_static">cowboy_static(3)</a> - Static file handler +</p> +</li> +</ul></div> +<div class="paragraph"><p>Behaviors:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="cowboy_handler">cowboy_handler(3)</a> - Plain HTTP handlers +</p> +</li> +<li> +<p> +<a href="cowboy_loop">cowboy_loop(3)</a> - Loop handlers +</p> +</li> +<li> +<p> +<a href="cowboy_middleware">cowboy_middleware(3)</a> - Middlewares +</p> +</li> +<li> +<p> +<a href="cowboy_rest">cowboy_rest(3)</a> - REST handlers +</p> +</li> +<li> +<p> +<a href="cowboy_stream">cowboy_stream(3)</a> - Stream handlers +</p> +</li> +<li> +<p> +<a href="cowboy_websocket">cowboy_websocket(3)</a> - Websocket handlers +</p> +</li> +</ul></div> +<div class="paragraph"><p>Middlewares:</p></div> +<div class="ulist"><ul> +<li> +<p> +<a href="cowboy_router">cowboy_router(3)</a> - Router middleware +</p> +</li> +<li> +<p> +<a href="cowboy_handler">cowboy_handler(3)</a> - Handler middleware +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_dependencies">Dependencies</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="/docs">ranch(7)</a> - Socket acceptor pool for TCP protocols +</p> +</li> +<li> +<p> +<a href="/docs">cowlib(7)</a> - Support library for manipulating Web protocols +</p> +</li> +<li> +<p> +ssl - Secure communication over sockets +</p> +</li> +<li> +<p> +crypto - Crypto functions +</p> +</li> +</ul></div> +<div class="paragraph"><p>All these applications must be started before the <code>cowboy</code> +application. To start Cowboy and all dependencies at once:</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: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">application:ensure_all_started</span></span>(<span style="color: #FF6600">cowboy</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_environment">Environment</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>cowboy</code> application does not define any application +environment configuration parameters.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="/docs">ranch(7)</a>, +<a href="/docs">cowlib(7)</a></p></div> +</div> +</div> diff --git a/docs/en/cowboy/HEAD/guide/index.html b/docs/en/cowboy/HEAD/guide/index.html index d87c4243..0194031a 100644 --- a/docs/en/cowboy/HEAD/guide/index.html +++ b/docs/en/cowboy/HEAD/guide/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file diff --git a/docs/en/cowboy/HEAD/index.html b/docs/en/cowboy/HEAD/index.html index d87c4243..0194031a 100644 --- a/docs/en/cowboy/HEAD/index.html +++ b/docs/en/cowboy/HEAD/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file diff --git a/docs/en/cowboy/HEAD/manual/index.html b/docs/en/cowboy/HEAD/manual/index.html index d87c4243..0194031a 100644 --- a/docs/en/cowboy/HEAD/manual/index.html +++ b/docs/en/cowboy/HEAD/manual/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file diff --git a/docs/en/cowboy/index.html b/docs/en/cowboy/index.html index d87c4243..0194031a 100644 --- a/docs/en/cowboy/index.html +++ b/docs/en/cowboy/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file diff --git a/docs/en/erlang.mk/1/guide/app/index.html b/docs/en/erlang.mk/1/guide/app/index.html index 49f9c1f4..c4fa21f7 100644 --- a/docs/en/erlang.mk/1/guide/app/index.html +++ b/docs/en/erlang.mk/1/guide/app/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Building</title> @@ -67,555 +67,614 @@ <h1 class="lined-header"><span>Building</span></h1> -<div class="paragraph"><p>Erlang.mk can do a lot of things, but it is, first and
-foremost, a build tool. In this chapter we will cover
-the basics of building a project with Erlang.mk.</p></div>
-<div class="paragraph"><p>For most of this chapter, we will assume that you are
-using a project <a href="../getting_started">generated by Erlang.mk</a>.</p></div>
-<div class="sect1">
-<h2 id="_how_to_build">How to build</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To build a project, all you have to do is type <code>make</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>$ make</tt></pre></div></div>
-<div class="paragraph"><p>It will work regardless of your project: OTP applications,
-library applications, NIFs, port drivers or even releases.
-Erlang.mk also automatically downloads and compiles the
-dependencies for your project.</p></div>
-<div class="paragraph"><p>All this is possible thanks to a combination of configuration
-and conventions. Most of the conventions come from Erlang/OTP
-itself so any seasoned Erlang developers should feel right at
-home.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_what_to_build">What to build</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk gives you control over three steps of the build
-process, allowing you to do a partial build if needed.</p></div>
-<div class="paragraph"><p>A build has three phases: first any dependency is fetched
-and built, then the project itself is built and finally a
-release may be generated when applicable. A release is only
-generated for projects specifically configured to do so.</p></div>
-<div class="paragraph"><p>Erlang.mk handles those three phases automatically when you
-type <code>make</code>. But sometimes you just want to repeat one or
-two of them.</p></div>
-<div class="paragraph"><p>The commands detailed in this section are most useful after
-you have a successful build as they allow you to quickly
-redo a step instead of going through everything. This is
-especially useful for large projects or projects that end
-up generating releases.</p></div>
-<div class="sect3">
-<h4 id="_application">Application</h4>
-<div class="paragraph"><p>You can build your application and dependencies without
-generating a release by running the following 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>$ make app</tt></pre></div></div>
-<div class="paragraph"><p>To build your application without touching dependencies
-at all, you can use the <code>SKIP_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>$ make app <span style="color: #009900">SKIP_DEPS</span><span style="color: #990000">=</span><span style="color: #993399">1</span></tt></pre></div></div>
-<div class="paragraph"><p>This command is very useful if you have a lot of dependencies
-and develop on a machine with slow file access, like the
-Raspberry Pi and many other embedded devices.</p></div>
-<div class="paragraph"><p>Note that this command may fail if a required dependency
-is missing.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_dependencies">Dependencies</h4>
-<div class="paragraph"><p>You can build all dependencies, and nothing else, by
-running the following 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>$ make deps</tt></pre></div></div>
-<div class="paragraph"><p>This will fetch and compile all dependencies and their
-dependencies, recursively.</p></div>
-<div class="paragraph"><p><a href="../deps">Packages and dependencies</a> are covered
-in the next chapter.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_release">Release</h4>
-<div class="paragraph"><p>It is not possible to build the release without at least
-building the application itself, unless of course if there’s
-no application to begin with.</p></div>
-<div class="paragraph"><p>To generate the release, <code>make</code> will generally suffice with
-a normal Erlang.mk. A separate target is however available,
-and will take care of building the release, after building
-the application and all dependencies:</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 rel</tt></pre></div></div>
-<div class="paragraph"><p>Consult the <a href="../relx">Releases</a> chapter for more
-information about what releases are and how they are generated.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_application_resource_file">Application resource file</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>When building your application, Erlang.mk will generate the
-<a href="http://www.erlang.org/doc/man/app.html">application resource file</a>.
-This file is mandatory for all Erlang applications and is
-found in <em>ebin/$(PROJECT).app</em>.</p></div>
-<div class="paragraph"><p><code>PROJECT</code> is a variable defined in your Makefile and taken
-from the name of the directory when Erlang.mk bootstraps
-your project.</p></div>
-<div class="paragraph"><p>Erlang.mk can build the <em>ebin/$(PROJECT).app</em> in two different
-ways: from the configuration found in the Makefile, or from
-the <em>src/$(PROJECT).app.src</em> file.</p></div>
-<div class="sect3">
-<h4 id="_application_configuration">Application configuration</h4>
-<div class="paragraph"><p>Erlang.mk automatically fills the <code>PROJECT</code> variable when
-bootstrapping a new project, but everything else is up to
-you. None of the values are required to build your project,
-although it is recommended to fill everything relevant to
-your situation.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>PROJECT</code>
-</dt>
-<dd>
-<p>
- The name of the OTP application or library.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>PROJECT_DESCRIPTION</code>
-</dt>
-<dd>
-<p>
- Short description of the project.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>PROJECT_VERSION</code>
-</dt>
-<dd>
-<p>
- Current version of the project.
-</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>
-<p>
- List of the names of all registered processes.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>PROJECT_ENV</code>
-</dt>
-<dd>
-<p>
- Configuration parameters used by the application.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>PROJECT_APP_EXTRA_KEYS</code>
-</dt>
-<dd>
-<p>
- Other keys you want to add to the application <code>.app</code> file.
- The variable content is written as-is to the <code>.app</code> file,
- so be sure to format valid Erlang terms. For example:
- <code>PROJECT_APP_EXTRA_KEYS = {maxT, 10000}, {start_phases, [...]}</code>.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>LOCAL_DEPS</code>
-</dt>
-<dd>
-<p>
- List of Erlang/OTP applications this project depends on,
- excluding <code>erts</code>, <code>kernel</code> and <code>stdlib</code>, or list of
- dependencies local to this repository (in <code>APPS_DIR</code>).
-</p>
-</dd>
-<dt class="hdlist1">
-<code>DEPS</code>
-</dt>
-<dd>
-<p>
- List of applications this project depends on that need
- to be fetched by Erlang.mk.
-</p>
-</dd>
-</dl></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"></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>
-</div>
-<div class="sect3">
-<h4 id="_legacy_method">Legacy method</h4>
-<div class="paragraph"><p>The <em>src/$(PROJECT).app.src</em> file is a legacy method of
-building Erlang applications. It was introduced by the original
-<code>rebar</code> build tool, of which Erlang.mk owes a great deal as it
-is its main inspiration.</p></div>
-<div class="paragraph"><p>The <em>.app.src</em> file serves as a template to generate the <em>.app</em>
-file. Erlang.mk will take it, fill in the <code>modules</code> value
-dynamically, and save the result in <em>ebin/$(PROJECT).app</em>.</p></div>
-<div class="paragraph"><p>When using this method, Erlang.mk cannot fill the <code>applications</code>
-key from dependencies automatically, which means you need to
-add them to Erlang.mk and to the <em>.app.src</em> at the same time,
-duplicating the work.</p></div>
-<div class="paragraph"><p>If you really can’t live without the legacy method, for one
-reason or another, worry not; Erlang.mk will support it. And
-if you need to create a new project that uses this method, you
-just have to say so when bootstrapping:</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 -f erlang<span style="color: #990000">.</span>mk bootstrap-lib <span style="color: #009900">LEGACY</span><span style="color: #990000">=</span><span style="color: #993399">1</span></tt></pre></div></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_automatic_application_resource_file_values">Automatic application resource file values</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>When building the application resource file, Erlang.mk may
-automatically add an <code>id</code> key with information about the
-Git commit (if using Git), or an empty string otherwise.
-It will only do this under specific conditions:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-The application was built as a dependency of another, or
-</p>
-</li>
-<li>
-<p>
-The legacy method was used, and the <em>.app.src</em> file contained <code>{id, "git"}</code>
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>This value is most useful when you need to help your users,
-as it allows you to know which version they run exactly by
-asking them to look in the file, or by running a simple
-command on their production server:</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: #993399">1</span><span style="color: #990000">></span> <span style="font-weight: bold"><span style="color: #000000">application:get_all_key</span></span>(<span style="color: #FF6600">cowboy</span>)<span style="color: #990000">.</span>
-{<span style="color: #FF6600">ok</span>,[{<span style="color: #FF6600">description</span>,<span style="color: #FF0000">"Small, fast, modular HTTP server."</span>},
- {<span style="color: #FF6600">id</span>,<span style="color: #FF0000">"2.0.0-pre.2-25-g0ffde50-dirty"</span>},</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_file_formats">File formats</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk supports a variety of different source file formats.
-The following formats are supported natively:</p></div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="border"
-cellspacing="0" cellpadding="4">
-<col width="25%" />
-<col width="25%" />
-<col width="25%" />
-<col width="25%" />
-<thead>
-<tr>
-<th align="left" valign="top"> Extension </th>
-<th align="center" valign="top"> Location </th>
-<th align="center" valign="top"> Description </th>
-<th align="center" valign="top"> Output</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table">.erl</p></td>
-<td align="center" valign="top"><p class="table">src/</p></td>
-<td align="center" valign="top"><p class="table">Erlang source</p></td>
-<td align="center" valign="top"><p class="table">ebin/*.beam</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">.core</p></td>
-<td align="center" valign="top"><p class="table">src/</p></td>
-<td align="center" valign="top"><p class="table">Core Erlang source</p></td>
-<td align="center" valign="top"><p class="table">ebin/*.beam</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">.xrl</p></td>
-<td align="center" valign="top"><p class="table">src/</p></td>
-<td align="center" valign="top"><p class="table">Leex source</p></td>
-<td align="center" valign="top"><p class="table">src/*.erl</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">.yrl</p></td>
-<td align="center" valign="top"><p class="table">src/</p></td>
-<td align="center" valign="top"><p class="table">Yecc source</p></td>
-<td align="center" valign="top"><p class="table">src/*.erl</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">.asn1</p></td>
-<td align="center" valign="top"><p class="table">asn1/</p></td>
-<td align="center" valign="top"><p class="table">ASN.1 files</p></td>
-<td align="center" valign="top"><p class="table">include/<strong>.hrl include/</strong>.asn1db src/*.erl</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">.mib</p></td>
-<td align="center" valign="top"><p class="table">mibs/</p></td>
-<td align="center" valign="top"><p class="table">SNMP MIB files</p></td>
-<td align="center" valign="top"><p class="table">include/<strong>.hrl priv/mibs/</strong>.bin</p></td>
-</tr>
-</tbody>
-</table>
-</div>
-<div class="paragraph"><p>Files are always searched recursively.</p></div>
-<div class="paragraph"><p>The build is ordered, so that files that generate Erlang source
-files are run before, and the resulting Erlang source files are
-then built normally.</p></div>
-<div class="paragraph"><p>In addition, Erlang.mk keeps track of header files (<code>.hrl</code>)
-as described at the end of this chapter. It can also compile
-C code, as described in the <a href="../ports">NIFs and port drivers</a>
-chapter.</p></div>
-<div class="paragraph"><p>Erlang.mk also comes with plugins for the following formats:</p></div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="border"
-cellspacing="0" cellpadding="4">
-<col width="25%" />
-<col width="25%" />
-<col width="25%" />
-<col width="25%" />
-<thead>
-<tr>
-<th align="left" valign="top"> Extension </th>
-<th align="center" valign="top"> Location </th>
-<th align="center" valign="top"> Description </th>
-<th align="center" valign="top"> Output</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table">.dtl</p></td>
-<td align="center" valign="top"><p class="table">templates/</p></td>
-<td align="center" valign="top"><p class="table">Django templates</p></td>
-<td align="center" valign="top"><p class="table">ebin/*.beam</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">.proto</p></td>
-<td align="center" valign="top"><p class="table">src/</p></td>
-<td align="center" valign="top"><p class="table">Protocol buffers</p></td>
-<td align="center" valign="top"><p class="table">ebin/*.beam</p></td>
-</tr>
-</tbody>
-</table>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_compilation_options">Compilation options</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk provides a few variables that you can use to customize
-the build process and the resulting files.</p></div>
-<div class="sect3">
-<h4 id="_erlc_opts">ERLC_OPTS</h4>
-<div class="paragraph"><p><code>ERLC_OPTS</code> can be used to pass some options to <code>erlc</code>, the Erlang
-compiler. Erlang.mk does not restrict any option. Please refer to
-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"></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"></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"></div></div>
-</div>
-<div class="sect3">
-<h4 id="_erlc_asn1_opts">ERLC_ASN1_OPTS</h4>
-<div class="paragraph"><p><code>ERLC_ASN1_OPTS</code> can be used to pass compiler options when compiling
-ASN.1 files. Please refer to the
-<a href="http://erlang.org/doc/man/asn1ct.html">asn1ct manual</a> for the full list.</p></div>
-<div class="paragraph"><p>By default, Erlang.mk will leave this empty.</p></div>
-<div class="paragraph"><p>You can redefine this variable in your Makefile.
-Please see the <code>ERLC_OPTS</code> section for instructions.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_erlc_exclude">ERLC_EXCLUDE</h4>
-<div class="paragraph"><p><code>ERLC_EXCLUDE</code> can be used to exclude some modules from the
-compilation. It’s there for handling special cases, you should
-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"></div></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_cold_and_hot_builds">Cold and hot builds</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The first time you run <code>make</code>, Erlang.mk will build everything.</p></div>
-<div class="paragraph"><p>The second time you run <code>make</code>, and all subsequent times, Erlang.mk
-will only rebuild what changed. Erlang.mk has been optimized for
-this use case, as it is the most common during development.</p></div>
-<div class="paragraph"><p>Erlang.mk figures out what changed by using the dependency tracking
-feature of Make. Make automatically rebuilds a target if one of its
-dependency has changed (for example if a header file has changed,
-all the source files that include it will be rebuilt), and Erlang.mk
-leverages this feature to cut down on rebuild times.</p></div>
-<div class="paragraph"><p>Note that this applies only to building; some other features of
-Erlang.mk will run every time they are called regardless of files
-changed.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_dependency_tracking">Dependency tracking</h2>
-<div class="sectionbody">
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<div class="title">Note</div>
-</td>
-<td class="content">This section is about the dependency tracking between files
-inside your project, not application dependencies.</td>
-</tr></table>
-</div>
-<div class="paragraph"><p>Erlang.mk keeps track of the dependencies between the different
-files in your project. This information is kept in the <em>$(PROJECT).d</em>
-file in your directory. It is generated if missing, and will be
-generated again after every file change, by default.</p></div>
-<div class="paragraph"><p>Dependency tracking is what allows Erlang.mk to know when to
-rebuild Erlang files when header files, behaviors or parse
-transforms have changed. Erlang.mk also automatically keeps
-track of which files should be compiled first, for example
-when you have behaviors used by other modules in your project.</p></div>
-<div class="paragraph"><p>If your project is stable, you may want to disable generating
-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"></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
-(including a new header file, new module with dependencies, etc.)
-and want to rebuild the dependency tracking file. You’ll be
-able to use the following 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">NO_MAKEDEP</span><span style="color: #990000">=</span> make</tt></pre></div></div>
-<div class="paragraph"><p>Otherwise, <code>make clean app</code> will of course force the
-recompilation of your project.</p></div>
-<div class="paragraph"><p>Erlang.mk can also keep track of the source files generated
-by other means, for example if you generate code from a data
-file in your repository.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_generating_erlang_source">Generating Erlang source</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk provides hooks at different stages of the build process.
-When your goal is to generate Erlang source files, you can
-add your own rules before or after the dependency tracking
-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"></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>
-<div class="paragraph"><p>When using an external script to generate the Erlang source
-file, it is recommended to depend on that script, so that
-the source file gets generated again when the script gets
-modified.</p></div>
-<div class="paragraph"><p>If for whatever reason you prefer to hook before including
-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"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_cleaning">Cleaning</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Building typically involves creating a lot of new files. Some
-are reused in rebuilds, some are simply replaced. All can be
-removed safely.</p></div>
-<div class="paragraph"><p>Erlang.mk provides two commands to remove them: <code>clean</code> and
-<code>distclean</code>. <code>clean</code> removes all the intermediate files that
-were created as a result of building, including the BEAM files,
-the dependency tracking file and the generated documentation.
-<code>distclean</code> removes these and more, including the downloaded
-dependencies, Dialyzer’s PLT file and the generated release,
-putting your directory back to the state it was before you
-started working on it.</p></div>
-<div class="paragraph"><p>To clean:</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 clean</tt></pre></div></div>
-<div class="paragraph"><p>Or distclean:</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 distclean</tt></pre></div></div>
-<div class="paragraph"><p>That is the question.</p></div>
-<div class="paragraph"><p>Note that Erlang.mk will automatically clean some files as
-part of other targets, but it will never run <code>distclean</code> if
-you don’t explicitly use it.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Erlang.mk can do a lot of things, but it is, first and +foremost, a build tool. In this chapter we will cover +the basics of building a project with Erlang.mk.</p></div> +<div class="paragraph"><p>For most of this chapter, we will assume that you are +using a project <a href="../getting_started">generated by Erlang.mk</a>.</p></div> +<div class="sect1"> +<h2 id="_how_to_build">How to build</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To build a project, all you have to do is type <code>make</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>$ make</tt></pre></div></div> +<div class="paragraph"><p>It will work regardless of your project: OTP applications, +library applications, NIFs, port drivers or even releases. +Erlang.mk also automatically downloads and compiles the +dependencies for your project.</p></div> +<div class="paragraph"><p>All this is possible thanks to a combination of configuration +and conventions. Most of the conventions come from Erlang/OTP +itself so any seasoned Erlang developers should feel right at +home.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_what_to_build">What to build</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk gives you control over three steps of the build +process, allowing you to do a partial build if needed.</p></div> +<div class="paragraph"><p>A build has three phases: first any dependency is fetched +and built, then the project itself is built and finally a +release may be generated when applicable. A release is only +generated for projects specifically configured to do so.</p></div> +<div class="paragraph"><p>Erlang.mk handles those three phases automatically when you +type <code>make</code>. But sometimes you just want to repeat one or +two of them.</p></div> +<div class="paragraph"><p>The commands detailed in this section are most useful after +you have a successful build as they allow you to quickly +redo a step instead of going through everything. This is +especially useful for large projects or projects that end +up generating releases.</p></div> +<div class="sect3"> +<h4 id="_application">Application</h4> +<div class="paragraph"><p>You can build your application and dependencies without +generating a release by running the following 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>$ make app</tt></pre></div></div> +<div class="paragraph"><p>To build your application without touching dependencies +at all, you can use the <code>SKIP_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>$ make app <span style="color: #009900">SKIP_DEPS</span><span style="color: #990000">=</span><span style="color: #993399">1</span></tt></pre></div></div> +<div class="paragraph"><p>This command is very useful if you have a lot of dependencies +and develop on a machine with slow file access, like the +Raspberry Pi and many other embedded devices.</p></div> +<div class="paragraph"><p>Note that this command may fail if a required dependency +is missing.</p></div> +</div> +<div class="sect3"> +<h4 id="_dependencies">Dependencies</h4> +<div class="paragraph"><p>You can build all dependencies, and nothing else, by +running the following 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>$ make deps</tt></pre></div></div> +<div class="paragraph"><p>This will fetch and compile all dependencies and their +dependencies, recursively.</p></div> +<div class="paragraph"><p><a href="../deps">Packages and dependencies</a> are covered +in the next chapter.</p></div> +</div> +<div class="sect3"> +<h4 id="_release">Release</h4> +<div class="paragraph"><p>It is not possible to build the release without at least +building the application itself, unless of course if there’s +no application to begin with.</p></div> +<div class="paragraph"><p>To generate the release, <code>make</code> will generally suffice with +a normal Erlang.mk. A separate target is however available, +and will take care of building the release, after building +the application and all dependencies:</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 rel</tt></pre></div></div> +<div class="paragraph"><p>Consult the <a href="../relx">Releases</a> chapter for more +information about what releases are and how they are generated.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_application_resource_file">Application resource file</h2> +<div class="sectionbody"> +<div class="paragraph"><p>When building your application, Erlang.mk will generate the +<a href="http://www.erlang.org/doc/man/app.html">application resource file</a>. +This file is mandatory for all Erlang applications and is +found in <em>ebin/$(PROJECT).app</em>.</p></div> +<div class="paragraph"><p><code>PROJECT</code> is a variable defined in your Makefile and taken +from the name of the directory when Erlang.mk bootstraps +your project.</p></div> +<div class="paragraph"><p>Erlang.mk can build the <em>ebin/$(PROJECT).app</em> in two different +ways: from the configuration found in the Makefile, or from +the <em>src/$(PROJECT).app.src</em> file.</p></div> +<div class="sect3"> +<h4 id="_application_configuration">Application configuration</h4> +<div class="paragraph"><p>Erlang.mk automatically fills the <code>PROJECT</code> variable when +bootstrapping a new project, but everything else is up to +you. None of the values are required to build your project, +although it is recommended to fill everything relevant to +your situation.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +<code>PROJECT</code> +</dt> +<dd> +<p> + The name of the OTP application or library. +</p> +</dd> +<dt class="hdlist1"> +<code>PROJECT_DESCRIPTION</code> +</dt> +<dd> +<p> + Short description of the project. +</p> +</dd> +<dt class="hdlist1"> +<code>PROJECT_VERSION</code> +</dt> +<dd> +<p> + Current version of the project. +</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> +<p> + List of the names of all registered processes. +</p> +</dd> +<dt class="hdlist1"> +<code>PROJECT_ENV</code> +</dt> +<dd> +<p> + Configuration parameters used by the application. +</p> +</dd> +<dt class="hdlist1"> +<code>PROJECT_APP_EXTRA_KEYS</code> +</dt> +<dd> +<p> + Other keys you want to add to the application <code>.app</code> file. + The variable content is written as-is to the <code>.app</code> file, + so be sure to format valid Erlang terms. For example: + <code>PROJECT_APP_EXTRA_KEYS = {maxT, 10000}, {start_phases, [...]}</code>. +</p> +</dd> +<dt class="hdlist1"> +<code>LOCAL_DEPS</code> +</dt> +<dd> +<p> + List of Erlang/OTP applications this project depends on, + excluding <code>erts</code>, <code>kernel</code> and <code>stdlib</code>, or list of + dependencies local to this repository (in <code>APPS_DIR</code>). +</p> +</dd> +<dt class="hdlist1"> +<code>DEPS</code> +</dt> +<dd> +<p> + List of applications this project depends on that need + to be fetched by Erlang.mk. +</p> +</dd> +</dl></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="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> +</div> +<div class="sect3"> +<h4 id="_legacy_method">Legacy method</h4> +<div class="paragraph"><p>The <em>src/$(PROJECT).app.src</em> file is a legacy method of +building Erlang applications. It was introduced by the original +<code>rebar</code> build tool, of which Erlang.mk owes a great deal as it +is its main inspiration.</p></div> +<div class="paragraph"><p>The <em>.app.src</em> file serves as a template to generate the <em>.app</em> +file. Erlang.mk will take it, fill in the <code>modules</code> value +dynamically, and save the result in <em>ebin/$(PROJECT).app</em>.</p></div> +<div class="paragraph"><p>When using this method, Erlang.mk cannot fill the <code>applications</code> +key from dependencies automatically, which means you need to +add them to Erlang.mk and to the <em>.app.src</em> at the same time, +duplicating the work.</p></div> +<div class="paragraph"><p>If you really can’t live without the legacy method, for one +reason or another, worry not; Erlang.mk will support it. And +if you need to create a new project that uses this method, you +just have to say so when bootstrapping:</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 -f erlang<span style="color: #990000">.</span>mk bootstrap-lib <span style="color: #009900">LEGACY</span><span style="color: #990000">=</span><span style="color: #993399">1</span></tt></pre></div></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_automatic_application_resource_file_values">Automatic application resource file values</h2> +<div class="sectionbody"> +<div class="paragraph"><p>When building the application resource file, Erlang.mk may +automatically add an <code>id</code> key with information about the +Git commit (if using Git), or an empty string otherwise. +It will only do this under specific conditions:</p></div> +<div class="ulist"><ul> +<li> +<p> +The application was built as a dependency of another, or +</p> +</li> +<li> +<p> +The legacy method was used, and the <em>.app.src</em> file contained <code>{id, "git"}</code> +</p> +</li> +</ul></div> +<div class="paragraph"><p>This value is most useful when you need to help your users, +as it allows you to know which version they run exactly by +asking them to look in the file, or by running a simple +command on their production server:</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: #993399">1</span><span style="color: #990000">></span> <span style="font-weight: bold"><span style="color: #000000">application:get_all_key</span></span>(<span style="color: #FF6600">cowboy</span>)<span style="color: #990000">.</span> +{<span style="color: #FF6600">ok</span>,[{<span style="color: #FF6600">description</span>,<span style="color: #FF0000">"Small, fast, modular HTTP server."</span>}, + {<span style="color: #FF6600">id</span>,<span style="color: #FF0000">"2.0.0-pre.2-25-g0ffde50-dirty"</span>},</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_file_formats">File formats</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk supports a variety of different source file formats. +The following formats are supported natively:</p></div> +<div class="tableblock"> +<table rules="all" +width="100%" +frame="border" +cellspacing="0" cellpadding="4"> +<col width="25%" /> +<col width="25%" /> +<col width="25%" /> +<col width="25%" /> +<thead> +<tr> +<th align="left" valign="top"> Extension </th> +<th align="center" valign="top"> Location </th> +<th align="center" valign="top"> Description </th> +<th align="center" valign="top"> Output</th> +</tr> +</thead> +<tbody> +<tr> +<td align="left" valign="top"><p class="table">.erl</p></td> +<td align="center" valign="top"><p class="table">src/</p></td> +<td align="center" valign="top"><p class="table">Erlang source</p></td> +<td align="center" valign="top"><p class="table">ebin/*.beam</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">.core</p></td> +<td align="center" valign="top"><p class="table">src/</p></td> +<td align="center" valign="top"><p class="table">Core Erlang source</p></td> +<td align="center" valign="top"><p class="table">ebin/*.beam</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">.xrl</p></td> +<td align="center" valign="top"><p class="table">src/</p></td> +<td align="center" valign="top"><p class="table">Leex source</p></td> +<td align="center" valign="top"><p class="table">src/*.erl</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">.yrl</p></td> +<td align="center" valign="top"><p class="table">src/</p></td> +<td align="center" valign="top"><p class="table">Yecc source</p></td> +<td align="center" valign="top"><p class="table">src/*.erl</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">.asn1</p></td> +<td align="center" valign="top"><p class="table">asn1/</p></td> +<td align="center" valign="top"><p class="table">ASN.1 files</p></td> +<td align="center" valign="top"><p class="table">include/<strong>.hrl include/</strong>.asn1db src/*.erl</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">.mib</p></td> +<td align="center" valign="top"><p class="table">mibs/</p></td> +<td align="center" valign="top"><p class="table">SNMP MIB files</p></td> +<td align="center" valign="top"><p class="table">include/<strong>.hrl priv/mibs/</strong>.bin</p></td> +</tr> +</tbody> +</table> +</div> +<div class="paragraph"><p>Files are always searched recursively.</p></div> +<div class="paragraph"><p>The build is ordered, so that files that generate Erlang source +files are run before, and the resulting Erlang source files are +then built normally.</p></div> +<div class="paragraph"><p>In addition, Erlang.mk keeps track of header files (<code>.hrl</code>) +as described at the end of this chapter. It can also compile +C code, as described in the <a href="../ports">NIFs and port drivers</a> +chapter.</p></div> +<div class="paragraph"><p>Erlang.mk also comes with plugins for the following formats:</p></div> +<div class="tableblock"> +<table rules="all" +width="100%" +frame="border" +cellspacing="0" cellpadding="4"> +<col width="25%" /> +<col width="25%" /> +<col width="25%" /> +<col width="25%" /> +<thead> +<tr> +<th align="left" valign="top"> Extension </th> +<th align="center" valign="top"> Location </th> +<th align="center" valign="top"> Description </th> +<th align="center" valign="top"> Output</th> +</tr> +</thead> +<tbody> +<tr> +<td align="left" valign="top"><p class="table">.dtl</p></td> +<td align="center" valign="top"><p class="table">templates/</p></td> +<td align="center" valign="top"><p class="table">Django templates</p></td> +<td align="center" valign="top"><p class="table">ebin/*.beam</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">.proto</p></td> +<td align="center" valign="top"><p class="table">src/</p></td> +<td align="center" valign="top"><p class="table">Protocol buffers</p></td> +<td align="center" valign="top"><p class="table">ebin/*.beam</p></td> +</tr> +</tbody> +</table> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_compilation_options">Compilation options</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk provides a few variables that you can use to customize +the build process and the resulting files.</p></div> +<div class="sect3"> +<h4 id="_erlc_opts">ERLC_OPTS</h4> +<div class="paragraph"><p><code>ERLC_OPTS</code> can be used to pass some options to <code>erlc</code>, the Erlang +compiler. Erlang.mk does not restrict any option. Please refer to +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="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="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> +<div class="sect3"> +<h4 id="_erlc_asn1_opts">ERLC_ASN1_OPTS</h4> +<div class="paragraph"><p><code>ERLC_ASN1_OPTS</code> can be used to pass compiler options when compiling +ASN.1 files. Please refer to the +<a href="http://erlang.org/doc/man/asn1ct.html">asn1ct manual</a> for the full list.</p></div> +<div class="paragraph"><p>By default, Erlang.mk will leave this empty.</p></div> +<div class="paragraph"><p>You can redefine this variable in your Makefile. +Please see the <code>ERLC_OPTS</code> section for instructions.</p></div> +</div> +<div class="sect3"> +<h4 id="_erlc_exclude">ERLC_EXCLUDE</h4> +<div class="paragraph"><p><code>ERLC_EXCLUDE</code> can be used to exclude some modules from the +compilation. It’s there for handling special cases, you should +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> +</div> +</div> +<div class="sect1"> +<h2 id="_cold_and_hot_builds">Cold and hot builds</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The first time you run <code>make</code>, Erlang.mk will build everything.</p></div> +<div class="paragraph"><p>The second time you run <code>make</code>, and all subsequent times, Erlang.mk +will only rebuild what changed. Erlang.mk has been optimized for +this use case, as it is the most common during development.</p></div> +<div class="paragraph"><p>Erlang.mk figures out what changed by using the dependency tracking +feature of Make. Make automatically rebuilds a target if one of its +dependency has changed (for example if a header file has changed, +all the source files that include it will be rebuilt), and Erlang.mk +leverages this feature to cut down on rebuild times.</p></div> +<div class="paragraph"><p>Note that this applies only to building; some other features of +Erlang.mk will run every time they are called regardless of files +changed.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_dependency_tracking">Dependency tracking</h2> +<div class="sectionbody"> +<div class="admonitionblock"> +<table><tr> +<td class="icon"> +<div class="title">Note</div> +</td> +<td class="content">This section is about the dependency tracking between files +inside your project, not application dependencies.</td> +</tr></table> +</div> +<div class="paragraph"><p>Erlang.mk keeps track of the dependencies between the different +files in your project. This information is kept in the <em>$(PROJECT).d</em> +file in your directory. It is generated if missing, and will be +generated again after every file change, by default.</p></div> +<div class="paragraph"><p>Dependency tracking is what allows Erlang.mk to know when to +rebuild Erlang files when header files, behaviors or parse +transforms have changed. Erlang.mk also automatically keeps +track of which files should be compiled first, for example +when you have behaviors used by other modules in your project.</p></div> +<div class="paragraph"><p>If your project is stable, you may want to disable generating +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="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 +(including a new header file, new module with dependencies, etc.) +and want to rebuild the dependency tracking file. You’ll be +able to use the following 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">NO_MAKEDEP</span><span style="color: #990000">=</span> make</tt></pre></div></div> +<div class="paragraph"><p>Otherwise, <code>make clean app</code> will of course force the +recompilation of your project.</p></div> +<div class="paragraph"><p>Erlang.mk can also keep track of the source files generated +by other means, for example if you generate code from a data +file in your repository.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_generating_erlang_source">Generating Erlang source</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk provides hooks at different stages of the build process. +When your goal is to generate Erlang source files, you can +add your own rules before or after the dependency tracking +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="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> +<div class="paragraph"><p>When using an external script to generate the Erlang source +file, it is recommended to depend on that script, so that +the source file gets generated again when the script gets +modified.</p></div> +<div class="paragraph"><p>If for whatever reason you prefer to hook before including +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> +</div> +<div class="sect1"> +<h2 id="_cleaning">Cleaning</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Building typically involves creating a lot of new files. Some +are reused in rebuilds, some are simply replaced. All can be +removed safely.</p></div> +<div class="paragraph"><p>Erlang.mk provides two commands to remove them: <code>clean</code> and +<code>distclean</code>. <code>clean</code> removes all the intermediate files that +were created as a result of building, including the BEAM files, +the dependency tracking file and the generated documentation. +<code>distclean</code> removes these and more, including the downloaded +dependencies, Dialyzer’s PLT file and the generated release, +putting your directory back to the state it was before you +started working on it.</p></div> +<div class="paragraph"><p>To clean:</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 clean</tt></pre></div></div> +<div class="paragraph"><p>Or distclean:</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 distclean</tt></pre></div></div> +<div class="paragraph"><p>That is the question.</p></div> +<div class="paragraph"><p>Note that Erlang.mk will automatically clean some files as +part of other targets, but it will never run <code>distclean</code> if +you don’t explicitly use it.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/asciidoc/index.html b/docs/en/erlang.mk/1/guide/asciidoc/index.html index f188ff6f..e0a10d20 100644 --- a/docs/en/erlang.mk/1/guide/asciidoc/index.html +++ b/docs/en/erlang.mk/1/guide/asciidoc/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: AsciiDoc documentation</title> @@ -67,106 +67,109 @@ <h1 class="lined-header"><span>AsciiDoc documentation</span></h1> -<div class="paragraph"><p>Erlang.mk provides rules for generating documentation from
-AsciiDoc files. It can automatically build a user guide PDF,
-chunked HTML documentation and Unix manual pages.</p></div>
-<div class="sect1">
-<h2 id="_requirements">Requirements</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>It is necessary to have <a href="http://asciidoc.org/">AsciiDoc</a>,
-<a href="http://xmlsoft.org/XSLT/xsltproc2.html">xsltproc</a> and
-<a href="http://dblatex.sourceforge.net/">dblatex</a> installed on your
-system for Erlang.mk to generate documentation from AsciiDoc sources.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_writing_asciidoc_documentation">Writing AsciiDoc documentation</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="http://asciidoc.org/">AsciiDoc</a> is a text document format for
-writing notes, documentation, articles, books, ebooks, slideshows,
-web pages, man pages and blogs. AsciiDoc files can be translated
-to many formats including HTML, PDF, EPUB, man page.</p></div>
-<div class="paragraph"><p>The <a href="http://asciidoc.org/userguide.html">AsciiDoc user guide</a>
-describes the AsciiDoc syntax.</p></div>
-<div class="paragraph"><p>The <a href="https://github.com/ninenines/erlang.mk/tree/master/doc/src/guide">Erlang.mk user guide</a>
-is written in AsciiDoc and can be used as an example. The entry
-file is <a href="https://github.com/ninenines/erlang.mk/blob/master/doc/src/guide/book.asciidoc">book.asciidoc</a>.</p></div>
-<div class="paragraph"><p>Erlang.mk expects you to put your documentation in a specific
-location. This is <em>doc/src/guide/</em> for the user guide, and
-<em>doc/src/manual/</em> for the function reference. In the case of
-the user guide, the entry point is always <em>doc/src/guide/book.asciidoc</em>.</p></div>
-<div class="paragraph"><p>For manual pages, it is good practice to use section 3 for
-modules, and section 7 for the application itself.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_configuration">Configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>All of the AsciiDoc related configuration can be done directly
-inside the files themselves.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_usage">Usage</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To build all 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>$ make docs</tt></pre></div></div>
-<div class="paragraph"><p>To build only the AsciiDoc 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>$ make asciidoc</tt></pre></div></div>
-<div class="paragraph"><p>To build only the user guide:</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 asciidoc-guide</tt></pre></div></div>
-<div class="paragraph"><p>To build only the manual:</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 asciidoc-manual</tt></pre></div></div>
-<div class="paragraph"><p>To install man pages on Unix:</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 install-docs</tt></pre></div></div>
-<div class="paragraph"><p>Erlang.mk allows customizing the installation path and sections
-of the man pages to be installed. The <code>MAN_INSTALL_PATH</code> variable
-defines where man pages will be installed. It defaults to
-<em>/usr/local/share/man</em>. The <code>MAN_SECTIONS</code> variable defines
-which manual sections are to be installed. It defaults to <code>3 7</code>.</p></div>
-<div class="paragraph"><p>To install man pages to a custom location:</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 install-docs <span style="color: #009900">MAN_INSTALL_PATH</span><span style="color: #990000">=</span>/opt/share/man</tt></pre></div></div>
-<div class="paragraph"><p>Note that you may need to run the install commands using
-<code>sudo</code> or equivalent if the location is not writeable by
-your user.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Erlang.mk provides rules for generating documentation from +AsciiDoc files. It can automatically build a user guide PDF, +chunked HTML documentation and Unix manual pages.</p></div> +<div class="sect1"> +<h2 id="_requirements">Requirements</h2> +<div class="sectionbody"> +<div class="paragraph"><p>It is necessary to have <a href="http://asciidoc.org/">AsciiDoc</a>, +<a href="http://xmlsoft.org/XSLT/xsltproc2.html">xsltproc</a> and +<a href="http://dblatex.sourceforge.net/">dblatex</a> installed on your +system for Erlang.mk to generate documentation from AsciiDoc sources.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_writing_asciidoc_documentation">Writing AsciiDoc documentation</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="http://asciidoc.org/">AsciiDoc</a> is a text document format for +writing notes, documentation, articles, books, ebooks, slideshows, +web pages, man pages and blogs. AsciiDoc files can be translated +to many formats including HTML, PDF, EPUB, man page.</p></div> +<div class="paragraph"><p>The <a href="http://asciidoc.org/userguide.html">AsciiDoc user guide</a> +describes the AsciiDoc syntax.</p></div> +<div class="paragraph"><p>The <a href="https://github.com/ninenines/erlang.mk/tree/master/doc/src/guide">Erlang.mk user guide</a> +is written in AsciiDoc and can be used as an example. The entry +file is <a href="https://github.com/ninenines/erlang.mk/blob/master/doc/src/guide/book.asciidoc">book.asciidoc</a>.</p></div> +<div class="paragraph"><p>Erlang.mk expects you to put your documentation in a specific +location. This is <em>doc/src/guide/</em> for the user guide, and +<em>doc/src/manual/</em> for the function reference. In the case of +the user guide, the entry point is always <em>doc/src/guide/book.asciidoc</em>.</p></div> +<div class="paragraph"><p>For manual pages, it is good practice to use section 3 for +modules, and section 7 for the application itself.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>All of the AsciiDoc related configuration can be done directly +inside the files themselves.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_usage">Usage</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To build all 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>$ make docs</tt></pre></div></div> +<div class="paragraph"><p>To build only the AsciiDoc 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>$ make asciidoc</tt></pre></div></div> +<div class="paragraph"><p>To build only the user guide:</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 asciidoc-guide</tt></pre></div></div> +<div class="paragraph"><p>To build only the manual:</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 asciidoc-manual</tt></pre></div></div> +<div class="paragraph"><p>To install man pages on Unix:</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 install-docs</tt></pre></div></div> +<div class="paragraph"><p>Erlang.mk allows customizing the installation path and sections +of the man pages to be installed. The <code>MAN_INSTALL_PATH</code> variable +defines where man pages will be installed. It defaults to +<em>/usr/local/share/man</em>. The <code>MAN_SECTIONS</code> variable defines +which manual sections are to be installed. It defaults to <code>3 7</code>.</p></div> +<div class="paragraph"><p>To install man pages to a custom location:</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 install-docs <span style="color: #009900">MAN_INSTALL_PATH</span><span style="color: #990000">=</span>/opt/share/man</tt></pre></div></div> +<div class="paragraph"><p>Note that you may need to run the install commands using +<code>sudo</code> or equivalent if the location is not writeable by +your user.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/ci.asciidoc b/docs/en/erlang.mk/1/guide/ci.asciidoc index 24cfc053..2b69e282 100644 --- a/docs/en/erlang.mk/1/guide/ci.asciidoc +++ b/docs/en/erlang.mk/1/guide/ci.asciidoc @@ -1,6 +1,66 @@ [[ci]] == Continuous integration -// @todo Write it. +Erlang.mk comes with some support for continuous integration, +aimed at open source projects that need to support more than +one specific Erlang/OTP release. (If you target one specific +release, check the xref:otp_version_pinning[OTP version pinning] +section of the xref:kerl[OTP version management] chapter.) -Placeholder chapter. +=== Configuring Erlang/OTP versions to test + +To use the CI plugin you must first configure which versions +of Erlang/OTP will be used. Erlang.mk provides three separate +configuration variables depending on whether you need a normal +OTP release, a HiPE-enabled release or an ErLLVM-enabled release. + +At the time of writing, this is how you would test against all +the most recent patch releases of Erlang/OTP 19 and above: + +[source,make] +CI_OTP = OTP-19.0.7 OTP-19.1.6 OTP-19.2.3 OTP-19.3.6.2 OTP-20.0.4 + +If you want to test against HiPE and ErLLVM but only with the +latest version of Erlang/OTP, the following could work: + +[source,make] +CI_HIPE = $(lastword $(CI_OTP)) +CI_ERLLVM = $(CI_HIPE) + +Consult the xref:kerl[OTP version management] chapter for more +information about Erlang/OTP versions and customization of the +Erlang/OTP builds. + +=== Running tests across all configured versions + +The recommended way to run the `ci` target is with the option +`-k`. It will ensure that tests are run for all configured +Erlang/OTP versions, even if there are errors: + +[source,bash] +$ make ci -k + +=== Extending the CI targets + +The `ci` target can be extended. For example to run Dialyzer +at the end of CI: + +[source,make] +---- +ci:: dialyze +---- + +Additional setup can be done by extending the `ci-setup` +target. This target is ran before testing each individual +Erlang/OTP version. + +For example, to ensure dependencies are re-fetched/built +before testing individual Erlang/OTP releases: + +[source,make] +---- +ci-setup:: distclean +---- + +Similarly, the `ci-extra` target can be extended to run +extra commands after an Erlang/OTP version has been tested. diff --git a/docs/en/erlang.mk/1/guide/ci/index.html b/docs/en/erlang.mk/1/guide/ci/index.html index e4db9a8a..e73333f6 100644 --- a/docs/en/erlang.mk/1/guide/ci/index.html +++ b/docs/en/erlang.mk/1/guide/ci/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Continuous integration</title> @@ -67,13 +67,89 @@ <h1 class="lined-header"><span>Continuous integration</span></h1> -<div class="paragraph"><p>Placeholder chapter.</p></div>
+<div class="paragraph"><p>Erlang.mk comes with some support for continuous integration, +aimed at open source projects that need to support more than +one specific Erlang/OTP release. (If you target one specific +release, check the <a href="../otp_version_pinning">OTP version pinning</a> +section of the <a href="../kerl">OTP version management</a> chapter.)</p></div> +<div class="sect1"> +<h2 id="_configuring_erlang_otp_versions_to_test">Configuring Erlang/OTP versions to test</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To use the CI plugin you must first configure which versions +of Erlang/OTP will be used. Erlang.mk provides three separate +configuration variables depending on whether you need a normal +OTP release, a HiPE-enabled release or an ErLLVM-enabled release.</p></div> +<div class="paragraph"><p>At the time of writing, this is how you would test against all +the most recent patch releases of Erlang/OTP 19 and above:</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">CI_OTP =</span> OTP-19.0.7 OTP-19.1.6 OTP-19.2.3 OTP-19.3.6.2 OTP-20.0.4</tt></pre></div></div> +<div class="paragraph"><p>If you want to test against HiPE and ErLLVM but only with the +latest version of Erlang/OTP, the following could work:</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">CI_HIPE =</span> <span style="color: #009900">$(</span>lastword <span style="color: #009900">$(CI_OTP))</span> +<span style="color: #009900">CI_ERLLVM =</span> <span style="color: #009900">$(CI_HIPE)</span></tt></pre></div></div> +<div class="paragraph"><p>Consult the <a href="../kerl">OTP version management</a> chapter for more +information about Erlang/OTP versions and customization of the +Erlang/OTP builds.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_running_tests_across_all_configured_versions">Running tests across all configured versions</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The recommended way to run the <code>ci</code> target is with the option +<code>-k</code>. It will ensure that tests are run for all configured +Erlang/OTP versions, even if there are errors:</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 ci -k</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_extending_the_ci_targets">Extending the CI targets</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ci</code> target can be extended. For example to run Dialyzer +at the end of CI:</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">ci::</span> dialyze</tt></pre></div></div> +<div class="paragraph"><p>Additional setup can be done by extending the <code>ci-setup</code> +target. This target is ran before testing each individual +Erlang/OTP version.</p></div> +<div class="paragraph"><p>For example, to ensure dependencies are re-fetched/built +before testing individual Erlang/OTP releases:</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">ci-setup::</span> distclean</tt></pre></div></div> +<div class="paragraph"><p>Similarly, the <code>ci-extra</code> target can be extended to run +extra commands after an Erlang/OTP version has been tested.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> 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 74e9c912..7933d41a 100644 --- a/docs/en/erlang.mk/1/guide/common_test/index.html +++ b/docs/en/erlang.mk/1/guide/common_test/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Common Test</title> @@ -67,121 +67,136 @@ <h1 class="lined-header"><span>Common Test</span></h1> -<div class="paragraph"><p>Common Test is Erlang’s functional testing framework.
-Erlang.mk automates the discovery and running of Common
-Test suites.</p></div>
-<div class="sect1">
-<h2 id="_writing_tests">Writing tests</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <a href="http://www.erlang.org/doc/apps/common_test/write_test_chapter.html">Common Test user guide</a>
-is the best place to learn how to write tests. Erlang.mk
-requires that file names for test suites end with <em>_SUITE.erl</em>
-and that the files be located in the <em>$(TEST_DIR)</em> directory.
-This defaults to <em>test/</em>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_configuration">Configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>CT_OPTS</code> variable allows you to set extra Common Test
-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"></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
-test suites automatically.</p></div>
-<div class="paragraph"><p>The name of the suite is the part before <code>_SUITE.erl</code>.
-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"></div></div>
-<div class="paragraph"><p>The <code>CT_LOGS_DIR</code> variable can be used to set where HTML
-log files are to be written. This defaults to <em>logs/</em>.</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_usage">Usage</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To run all tests (including Common Test):</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 tests</tt></pre></div></div>
-<div class="paragraph"><p>To run all tests and static checks (including Common Test):</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 check</tt></pre></div></div>
-<div class="paragraph"><p>You can also run Common Test separately:</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 ct</tt></pre></div></div>
-<div class="paragraph"><p>Erlang.mk will create targets for all test suites it finds.
-If you have a file named <em>test/http_SUITE.erl</em>, then the
-target <code>ct-http</code> will run that specific test suite:</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 ct-http</tt></pre></div></div>
-<div class="paragraph"><p>Erlang.mk provides a convenient way to run a specific
-group or a specific test case within a specific group,
-using the variable <code>t</code>. Note that this only applies to
-suite-specific targets, like the <code>ct-http</code> example above.</p></div>
-<div class="paragraph"><p>To run all tests from the <code>http_compress</code> group in the
-<code>http_SUITE</code> test suite, 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>$ make ct-http <span style="color: #009900">t</span><span style="color: #990000">=</span>http_compress</tt></pre></div></div>
-<div class="paragraph"><p>Similarly, to run a specific test case in that group:</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 ct-http <span style="color: #009900">t</span><span style="color: #990000">=</span>http_compress<span style="color: #990000">:</span>headers_dupe</tt></pre></div></div>
-<div class="paragraph"><p>To do the same against a multi-application repository,
-you can use the <code>-C</code> option:</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 -C apps/my_app ct-http <span style="color: #009900">t</span><span style="color: #990000">=</span>my_group<span style="color: #990000">:</span>my_case</tt></pre></div></div>
-<div class="paragraph"><p>Note that this also applies to dependencies. When using Cowboy
-as a dependency, you can run the following 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>$ make -C deps/cowboy ct-http <span style="color: #009900">t</span><span style="color: #990000">=</span>http_compress</tt></pre></div></div>
-<div class="paragraph"><p>Finally, <a href="../coverage">code coverage</a> is available,
-but covered in its own chapter.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Common Test is Erlang’s functional testing framework. +Erlang.mk automates the discovery and running of Common +Test suites.</p></div> +<div class="sect1"> +<h2 id="_writing_tests">Writing tests</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <a href="http://www.erlang.org/doc/apps/common_test/write_test_chapter.html">Common Test user guide</a> +is the best place to learn how to write tests. Erlang.mk +requires that file names for test suites end with <em>_SUITE.erl</em> +and that the files be located in the <em>$(TEST_DIR)</em> directory. +This defaults to <em>test/</em>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>CT_OPTS</code> variable allows you to set extra Common Test +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="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 +test suites automatically.</p></div> +<div class="paragraph"><p>The name of the suite is the part before <code>_SUITE.erl</code>. +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="paragraph"><p>The <code>CT_LOGS_DIR</code> variable can be used to set where HTML +log files are to be written. This defaults to <em>logs/</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><span style="color: #009900">CT_LOGS_DIR =</span> ct_output_log_dir</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_usage">Usage</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To run all tests (including Common Test):</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 tests</tt></pre></div></div> +<div class="paragraph"><p>To run all tests and static checks (including Common Test):</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 check</tt></pre></div></div> +<div class="paragraph"><p>You can also run Common Test separately:</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 ct</tt></pre></div></div> +<div class="paragraph"><p>Erlang.mk will create targets for all test suites it finds. +If you have a file named <em>test/http_SUITE.erl</em>, then the +target <code>ct-http</code> will run that specific test suite:</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 ct-http</tt></pre></div></div> +<div class="paragraph"><p>Erlang.mk provides a convenient way to run a specific +group or a specific test case within a specific group, +using the variable <code>t</code>. Note that this only applies to +suite-specific targets, like the <code>ct-http</code> example above.</p></div> +<div class="paragraph"><p>To run all tests from the <code>http_compress</code> group in the +<code>http_SUITE</code> test suite, 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>$ make ct-http <span style="color: #009900">t</span><span style="color: #990000">=</span>http_compress</tt></pre></div></div> +<div class="paragraph"><p>Similarly, to run a specific test case in that group:</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 ct-http <span style="color: #009900">t</span><span style="color: #990000">=</span>http_compress<span style="color: #990000">:</span>headers_dupe</tt></pre></div></div> +<div class="paragraph"><p>To do the same against a multi-application repository, +you can use the <code>-C</code> option:</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 -C apps/my_app ct-http <span style="color: #009900">t</span><span style="color: #990000">=</span>my_group<span style="color: #990000">:</span>my_case</tt></pre></div></div> +<div class="paragraph"><p>Note that this also applies to dependencies. When using Cowboy +as a dependency, you can run the following 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>$ make -C deps/cowboy ct-http <span style="color: #009900">t</span><span style="color: #990000">=</span>http_compress</tt></pre></div></div> +<div class="paragraph"><p>Finally, <a href="../coverage">code coverage</a> is available, +but covered in its own chapter.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/compat/index.html b/docs/en/erlang.mk/1/guide/compat/index.html index da880762..d257d9ee 100644 --- a/docs/en/erlang.mk/1/guide/compat/index.html +++ b/docs/en/erlang.mk/1/guide/compat/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Compatibility with other build tools</title> @@ -67,97 +67,104 @@ <h1 class="lined-header"><span>Compatibility with other build tools</span></h1> -<div class="paragraph"><p>Erlang.mk tries its best to be compatible with the other Erlang
-build tools. It can use dependencies written with other build
-tools in mind, and can also make your projects usable by those
-build tools as well. Erlang.mk is like the cool kid that gets
-along with everybody.</p></div>
-<div class="paragraph"><p>In this chapter I will use the term <em>Rebar project</em> to refer
-to a project built using Rebar 2, Rebar 3 or Mad. These three
-build tools are very similar and share the same configuration
-file.</p></div>
-<div class="sect1">
-<h2 id="_rebar_projects_as_erlang_mk_dependencies">Rebar projects as Erlang.mk dependencies</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk comes with a feature called <em>Autoload</em> which will
-use Rebar 2 to patch any Rebar project and make it compatible
-with Erlang.mk. This feature essentially patches Rebar out
-and adds a Makefile to the project that Erlang.mk can then
-use for building:</p></div>
-<div class="paragraph"><p><em>Autoload</em> is documented in more details in the
-<a href="../deps">Packages and dependencies</a> chapter.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_erlang_mk_projects_as_rebar_dependencies">Erlang.mk projects as Rebar dependencies</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk projects can be made compatible with the Rebar family
-of build tools pretty easily, as Erlang.mk will generate
-all the files they require for building.</p></div>
-<div class="paragraph"><p>The Rebar family requires two files: a <em>rebar.config</em> file
-containing compilation options and the list of dependencies,
-and the application resource file, found either at
-<em>ebin/$(PROJECT).app</em> or at <em>src/$(PROJECT).app.src</em>.</p></div>
-<div class="sect3">
-<h4 id="_rebar_configuration">Rebar configuration</h4>
-<div class="paragraph"><p>Erlang.mk comes with a target that generates a <em>rebar.config</em>
-file when invoked:</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 rebar<span style="color: #990000">.</span>config</tt></pre></div></div>
-<div class="paragraph"><p>Careful! This will build the file even if it already existed
-before.</p></div>
-<div class="paragraph"><p>To build this file, Erlang.mk uses information it finds in
-the <code>DEPS</code> and <code>ERLC_OPTS</code> variables, among others. This
-means that the Rebar family builds your project much the
-same way as Erlang.mk.</p></div>
-<div class="paragraph"><p>Careful though! Different build tools have different fetching
-strategies. If some applications provide differing dependencies,
-they might be fetched differently by other build tools. Check
-the upcoming Sanity check chapter to find out how to detect such
-issues.</p></div>
-<div class="paragraph"><p>You can automatically generate this file when you build
-your application, by making it a dependency of the <code>app</code>
-target:</p></div>
-<div class="listingblock">
-<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.
-It could also be that we forgot to handle something! Sorry.
-We are of course interested to hear about any compatibility
-problems you may have, just open a ticket!</p></div>
-</div>
-<div class="sect3">
-<h4 id="_application_resource_file">Application resource file</h4>
-<div class="paragraph"><p>Erlang.mk has two ways to generate an application resource
-file: from the information found in the Makefile, or from
-the information found in the <em>src/$(PROJECT).app.src</em> file.
-Needless to say, if you have this file in your repository,
-then you don’t need to worry about compatibility with other
-build tools.</p></div>
-<div class="paragraph"><p>If you don’t, however, it’s not much harder. Every time
-Erlang.mk will compile your application, it will produce
-a new <em>ebin/$(PROJECT).app</em> file. Simply commit this file
-when it changes. It will only change when you modify the
-configuration, add or remove modules.</p></div>
-</div>
-</div>
-</div>
+<div class="paragraph"><p>Erlang.mk tries its best to be compatible with the other Erlang +build tools. It can use dependencies written with other build +tools in mind, and can also make your projects usable by those +build tools as well. Erlang.mk is like the cool kid that gets +along with everybody.</p></div> +<div class="paragraph"><p>In this chapter I will use the term <em>Rebar project</em> to refer +to a project built using Rebar 2, Rebar 3 or Mad. These three +build tools are very similar and share the same configuration +file.</p></div> +<div class="sect1"> +<h2 id="_rebar_projects_as_erlang_mk_dependencies">Rebar projects as Erlang.mk dependencies</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk comes with a feature called <em>Autoload</em> which will +use Rebar 2 to patch any Rebar project and make it compatible +with Erlang.mk. This feature essentially patches Rebar out +and adds a Makefile to the project that Erlang.mk can then +use for building:</p></div> +<div class="paragraph"><p><em>Autoload</em> is documented in more details in the +<a href="../deps">Packages and dependencies</a> chapter.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_erlang_mk_projects_as_rebar_dependencies">Erlang.mk projects as Rebar dependencies</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk projects can be made compatible with the Rebar family +of build tools pretty easily, as Erlang.mk will generate +all the files they require for building.</p></div> +<div class="paragraph"><p>The Rebar family requires two files: a <em>rebar.config</em> file +containing compilation options and the list of dependencies, +and the application resource file, found either at +<em>ebin/$(PROJECT).app</em> or at <em>src/$(PROJECT).app.src</em>.</p></div> +<div class="sect3"> +<h4 id="_rebar_configuration">Rebar configuration</h4> +<div class="paragraph"><p>Erlang.mk comes with a target that generates a <em>rebar.config</em> +file when invoked:</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 rebar<span style="color: #990000">.</span>config</tt></pre></div></div> +<div class="paragraph"><p>Careful! This will build the file even if it already existed +before.</p></div> +<div class="paragraph"><p>To build this file, Erlang.mk uses information it finds in +the <code>DEPS</code> and <code>ERLC_OPTS</code> variables, among others. This +means that the Rebar family builds your project much the +same way as Erlang.mk.</p></div> +<div class="paragraph"><p>Careful though! Different build tools have different fetching +strategies. If some applications provide differing dependencies, +they might be fetched differently by other build tools. Check +the upcoming Sanity check chapter to find out how to detect such +issues.</p></div> +<div class="paragraph"><p>You can automatically generate this file when you build +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="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. +It could also be that we forgot to handle something! Sorry. +We are of course interested to hear about any compatibility +problems you may have, just open a ticket!</p></div> +</div> +<div class="sect3"> +<h4 id="_application_resource_file">Application resource file</h4> +<div class="paragraph"><p>Erlang.mk has two ways to generate an application resource +file: from the information found in the Makefile, or from +the information found in the <em>src/$(PROJECT).app.src</em> file. +Needless to say, if you have this file in your repository, +then you don’t need to worry about compatibility with other +build tools.</p></div> +<div class="paragraph"><p>If you don’t, however, it’s not much harder. Every time +Erlang.mk will compile your application, it will produce +a new <em>ebin/$(PROJECT).app</em> file. Simply commit this file +when it changes. It will only change when you modify the +configuration, add or remove modules.</p></div> +</div> +</div> +</div> + + + <nav style="margin:1em 0"> - <a style="float:left" href="https://ninenines.eu/docs/en/erlang.mk/1/guide/escripts/"> - Escripts + <a style="float:left" href="https://ninenines.eu/docs/en/erlang.mk/1/guide/kerl/"> + OTP version management </a> diff --git a/docs/en/erlang.mk/1/guide/contributing/index.html b/docs/en/erlang.mk/1/guide/contributing/index.html index 0d549029..c6719e0c 100644 --- a/docs/en/erlang.mk/1/guide/contributing/index.html +++ b/docs/en/erlang.mk/1/guide/contributing/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Contributing</title> @@ -67,137 +67,140 @@ <h1 class="lined-header"><span>Contributing</span></h1> -<div class="paragraph"><p>You are welcome and encouraged to contribute.</p></div>
-<div class="paragraph"><p>This is how.</p></div>
-<div class="sect1">
-<h2 id="_priorities">Priorities</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>From the most important to the least important:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Bugs
-</p>
-</li>
-<li>
-<p>
-Package issues/additions
-</p>
-</li>
-<li>
-<p>
-Refactoring
-</p>
-</li>
-<li>
-<p>
-Features
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_bugs">Bugs</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>If you have found a bug, you should open a ticket. Include
-everything relevant including the command you used, output,
-a link to the code that triggers the issue, why you think
-this is a bug, etc.</p></div>
-<div class="paragraph"><p>If you think you have found a bug but you are not sure, you
-should open a ticket as previously explained.</p></div>
-<div class="paragraph"><p>If you have found a bug and you need it to be solved RIGHT
-NOW, open a ticket as previously explained.</p></div>
-<div class="paragraph"><p>Once you have opened a ticket, be patient, try to answer
-questions in a timely manner and confirm that the bug was
-indeed fixed when it is.</p></div>
-<div class="paragraph"><p>If you can’t be patient, either try to solve the bug and
-contribute the fix back or become a paying customer.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_code">Code</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The code is located in the <em>core/*.mk</em> and <em>plugins/*.mk</em> files.
-The tests are located in the <em>test/Makefile</em> and <em>test/*.mk</em> files.</p></div>
-<div class="paragraph"><p>If you have a fix or a hack for a bug, you should open a
-pull request. Any fix should include a test case that fails
-before the fix and is working after.</p></div>
-<div class="paragraph"><p>If you have a test case that reproduces a bug, but no fix for
-it, you should open a pull request.</p></div>
-<div class="paragraph"><p>Changes need to be tested with at least the <code>make check</code>
-command. A specific test case can be tested using <code>make check c=CASE</code>
-with <code>CASE</code> the name of the target to run. Output can be
-modulated using the <code>V</code> variable, which is an integer
-from 0 to 4. A typical use would be <code>make check c=dialyzer V=3</code>.
-The value 4 is particular and shows expanded commands right
-before they are executed.</p></div>
-<div class="paragraph"><p>To run tests in parallel, use the <code>-j</code> option. It is generally
-a good idea to also use the <code>-k</code> option to run all tests even
-if one fails. For example: <code>make check -j 32 -k</code>.</p></div>
-<div class="paragraph"><p>Some changes should be tested against all packages. Continue
-reading for more details on testing them.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_packages">Packages</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can search existing packages using the <code>make search q=STRING</code>
-command. This can be done both from an Erlang.mk project or
-directly from the Erlang.mk repository.</p></div>
-<div class="paragraph"><p>Packages can be added to the index using the <code>pkg_add.sh</code> script.</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>$ git clone https<span style="color: #990000">:</span>//github<span style="color: #990000">.</span>com<span style="color: #990000">/</span><span style="color: #009900">$YOURUSERNAME</span>/erlang<span style="color: #990000">.</span>mk
-$ cd erlang<span style="color: #990000">.</span>mk
-$ <span style="color: #990000">.</span>/pkg_add<span style="color: #990000">.</span>sh cowboy git https<span style="color: #990000">:</span>//github<span style="color: #990000">.</span>com/ninenines/cowboy <span style="color: #993399">1.0</span><span style="color: #990000">.</span><span style="color: #993399">0</span>
- http<span style="color: #990000">:</span>//ninenines<span style="color: #990000">.</span>eu <span style="color: #FF0000">"Small, fast and modular HTTP server."</span>
-$ git push origin master</tt></pre></div></div>
-<div class="paragraph"><p>Before sending a pull request, you should test your package.
-You can use the following command: <code>make check p=PACKAGE</code>,
-where <code>PACKAGE</code> is the name of the package, for example
-<code>cowboy</code>.</p></div>
-<div class="paragraph"><p>To test all packages, the <code>make packages</code> command can be used.
-This can take a long time. Some packages will fail with certain
-versions of Erlang, or if a prerequisite is missing from your system.
-You can of course speed things up using the <code>-j</code> and <code>-k</code> flags.</p></div>
-<div class="paragraph"><p>After all packages have been tested, you can run the command
-<code>make summary</code> to know what changed since the previous run.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_documentation">Documentation</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The documentation is always right.</p></div>
-<div class="paragraph"><p>If you think you have found a mistake in the documentation,
-this is a bug. You can either open a ticket or send a pull
-request.</p></div>
-<div class="paragraph"><p>To make sure that the documentation changes work, install
-the listed <a href="../asciidoc">Requirements</a> on your system and
-run <code>make docs</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_feature_requests">Feature requests</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>If you have an awesome idea or need something that Erlang.mk
-doesn’t provide yet, open a ticket. Provide as much detail as
-possible.</p></div>
-<div class="paragraph"><p>If you have code, great! Open a pull request as previously
-explained.</p></div>
-<div class="paragraph"><p>If not, you can still improve your feature request by writing
-the related documentation.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>You are welcome and encouraged to contribute.</p></div> +<div class="paragraph"><p>This is how.</p></div> +<div class="sect1"> +<h2 id="_priorities">Priorities</h2> +<div class="sectionbody"> +<div class="paragraph"><p>From the most important to the least important:</p></div> +<div class="ulist"><ul> +<li> +<p> +Bugs +</p> +</li> +<li> +<p> +Package issues/additions +</p> +</li> +<li> +<p> +Refactoring +</p> +</li> +<li> +<p> +Features +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_bugs">Bugs</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you have found a bug, you should open a ticket. Include +everything relevant including the command you used, output, +a link to the code that triggers the issue, why you think +this is a bug, etc.</p></div> +<div class="paragraph"><p>If you think you have found a bug but you are not sure, you +should open a ticket as previously explained.</p></div> +<div class="paragraph"><p>If you have found a bug and you need it to be solved RIGHT +NOW, open a ticket as previously explained.</p></div> +<div class="paragraph"><p>Once you have opened a ticket, be patient, try to answer +questions in a timely manner and confirm that the bug was +indeed fixed when it is.</p></div> +<div class="paragraph"><p>If you can’t be patient, either try to solve the bug and +contribute the fix back or become a paying customer.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_code">Code</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The code is located in the <em>core/*.mk</em> and <em>plugins/*.mk</em> files. +The tests are located in the <em>test/Makefile</em> and <em>test/*.mk</em> files.</p></div> +<div class="paragraph"><p>If you have a fix or a hack for a bug, you should open a +pull request. Any fix should include a test case that fails +before the fix and is working after.</p></div> +<div class="paragraph"><p>If you have a test case that reproduces a bug, but no fix for +it, you should open a pull request.</p></div> +<div class="paragraph"><p>Changes need to be tested with at least the <code>make check</code> +command. A specific test case can be tested using <code>make check c=CASE</code> +with <code>CASE</code> the name of the target to run. Output can be +modulated using the <code>V</code> variable, which is an integer +from 0 to 4. A typical use would be <code>make check c=dialyzer V=3</code>. +The value 4 is particular and shows expanded commands right +before they are executed.</p></div> +<div class="paragraph"><p>To run tests in parallel, use the <code>-j</code> option. It is generally +a good idea to also use the <code>-k</code> option to run all tests even +if one fails. For example: <code>make check -j 32 -k</code>.</p></div> +<div class="paragraph"><p>Some changes should be tested against all packages. Continue +reading for more details on testing them.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_packages">Packages</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You can search existing packages using the <code>make search q=STRING</code> +command. This can be done both from an Erlang.mk project or +directly from the Erlang.mk repository.</p></div> +<div class="paragraph"><p>Packages can be added to the index using the <code>pkg_add.sh</code> script.</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>$ git clone https<span style="color: #990000">:</span>//github<span style="color: #990000">.</span>com<span style="color: #990000">/</span><span style="color: #009900">$YOURUSERNAME</span>/erlang<span style="color: #990000">.</span>mk +$ cd erlang<span style="color: #990000">.</span>mk +$ <span style="color: #990000">.</span>/pkg_add<span style="color: #990000">.</span>sh cowboy git https<span style="color: #990000">:</span>//github<span style="color: #990000">.</span>com/ninenines/cowboy <span style="color: #993399">1.0</span><span style="color: #990000">.</span><span style="color: #993399">0</span> + http<span style="color: #990000">:</span>//ninenines<span style="color: #990000">.</span>eu <span style="color: #FF0000">"Small, fast and modular HTTP server."</span> +$ git push origin master</tt></pre></div></div> +<div class="paragraph"><p>Before sending a pull request, you should test your package. +You can use the following command: <code>make check p=PACKAGE</code>, +where <code>PACKAGE</code> is the name of the package, for example +<code>cowboy</code>.</p></div> +<div class="paragraph"><p>To test all packages, the <code>make packages</code> command can be used. +This can take a long time. Some packages will fail with certain +versions of Erlang, or if a prerequisite is missing from your system. +You can of course speed things up using the <code>-j</code> and <code>-k</code> flags.</p></div> +<div class="paragraph"><p>After all packages have been tested, you can run the command +<code>make summary</code> to know what changed since the previous run.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_documentation">Documentation</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The documentation is always right.</p></div> +<div class="paragraph"><p>If you think you have found a mistake in the documentation, +this is a bug. You can either open a ticket or send a pull +request.</p></div> +<div class="paragraph"><p>To make sure that the documentation changes work, install +the listed <a href="../asciidoc">Requirements</a> on your system and +run <code>make docs</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_feature_requests">Feature requests</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you have an awesome idea or need something that Erlang.mk +doesn’t provide yet, open a ticket. Provide as much detail as +possible.</p></div> +<div class="paragraph"><p>If you have code, great! Open a pull request as previously +explained.</p></div> +<div class="paragraph"><p>If not, you can still improve your feature request by writing +the related documentation.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/coverage/index.html b/docs/en/erlang.mk/1/guide/coverage/index.html index 39cfde17..d341f6f5 100644 --- a/docs/en/erlang.mk/1/guide/coverage/index.html +++ b/docs/en/erlang.mk/1/guide/coverage/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Code coverage</title> @@ -67,13 +67,16 @@ <h1 class="lined-header"><span>Code coverage</span></h1> -<div class="paragraph"><p>Placeholder chapter.</p></div>
+<div class="paragraph"><p>Placeholder chapter.</p></div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/deps/index.html b/docs/en/erlang.mk/1/guide/deps/index.html index 330146d6..c5a1904a 100644 --- a/docs/en/erlang.mk/1/guide/deps/index.html +++ b/docs/en/erlang.mk/1/guide/deps/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Packages and dependencies</title> @@ -67,610 +67,717 @@ <h1 class="lined-header"><span>Packages and dependencies</span></h1> -<div class="paragraph"><p>Erlang.mk can fetch and compile the dependencies that your
-project requires. Erlang.mk improves upon the concepts
-introduced by Rebar, so they should be familiar to many
-seasoned Erlang developers.</p></div>
-<div class="paragraph"><p>Erlang.mk is not a package manager, nor is it trying to be,
-but it does include an index of Erlang packages to make
-discovering useful projects easier.</p></div>
-<div class="paragraph"><p>This chapter will explain how to use packages, add
-dependencies to your project or bundle them directly
-in a single repository.</p></div>
-<div class="sect1">
-<h2 id="_searching_packages">Searching packages</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk gives you access to nearly 500 packages, with more
-being added regularly.</p></div>
-<div class="paragraph"><p>To find a package, search for 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>$ make search <span style="color: #009900">q</span><span style="color: #990000">=</span>pool</tt></pre></div></div>
-<div class="paragraph"><p>This will return all packages matching this word, like worker
-pool and acceptor pool projects.</p></div>
-<div class="paragraph"><p>You can also list everything and use regular command line
-tools to find what you need, 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>$ make search <span style="color: #990000">|</span> less</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_adding_dependencies_to_your_project">Adding dependencies to your project</h2>
-<div class="sectionbody">
-<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"></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
-other operations.</p></div>
-<div class="paragraph"><p>Erlang.mk will fill in the application resource file with
-all applications found in <code>DEPS</code>. But not all dependencies
-are Erlang applications, and not all dependencies need to
-be a runtime dependency. That’s where the <code>BUILD_DEPS</code>
-variable comes in: it works just like <code>DEPS</code>, except the
-dependencies listed there will not be added as runtime
-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"></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"></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
-about that in the <a href="../ports">NIFs and port drivers</a>
-chapter.</p></div>
-<div class="paragraph"><p>Another variable, <code>LOCAL_DEPS</code>, allows specifying runtime
-dependencies which are part of Erlang/OTP itself, but also
-dependencies that are included in the repository. Since they
-are already on your system, there is no need to fetch them.
-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"></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"></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"></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"></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"></div></div>
-<div class="paragraph"><p>All these will be documented in more details in their respective
-chapters.</p></div>
-<div class="sect3">
-<h4 id="_modifying_the_dependency_source_or_version">Modifying the dependency source or version</h4>
-<div class="paragraph"><p>By default, Erlang.mk will look into its package index to
-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"></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>
-<div class="paragraph"><p>If you simply want to change the commit number, all you
-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"></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
-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"></div></div>
-<div class="paragraph"><p>This will fetch Cowboy from your fork at the given commit.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_fetch_methods">Fetch methods</h4>
-<div class="paragraph"><p>Erlang.mk comes with a number of different fetch methods.
-You can fetch from Git, Mercurial, SVN, to name a few.
-There are fetch methods that will work everywhere, and
-fetch methods that will only work in a given environment.</p></div>
-<div class="paragraph"><p>The following table lists all existing methods:</p></div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="border"
-cellspacing="0" cellpadding="4">
-<col width="33%" />
-<col width="33%" />
-<col width="33%" />
-<thead>
-<tr>
-<th align="left" valign="top"> Name </th>
-<th align="center" valign="top"> Format </th>
-<th align="center" valign="top"> Description</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table">git</p></td>
-<td align="center" valign="top"><p class="table">git repo commit</p></td>
-<td align="center" valign="top"><p class="table">Clone the Git repository and checkout the given version</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">git-submodule</p></td>
-<td align="center" valign="top"><p class="table">git-submodule</p></td>
-<td align="center" valign="top"><p class="table">Initialize and update the Git submodule</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">hg</p></td>
-<td align="center" valign="top"><p class="table">hg repo commit</p></td>
-<td align="center" valign="top"><p class="table">Clone the Mercurial repository and update to the given version</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">svn</p></td>
-<td align="center" valign="top"><p class="table">svn repo</p></td>
-<td align="center" valign="top"><p class="table">Checkout the given SVN repository</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">cp</p></td>
-<td align="center" valign="top"><p class="table">cp path/to/repo</p></td>
-<td align="center" valign="top"><p class="table">Recursively copy a local directory</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">ln</p></td>
-<td align="center" valign="top"><p class="table">ln path/to/repo</p></td>
-<td align="center" valign="top"><p class="table">Symbolically link a local directory</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">hex</p></td>
-<td align="center" valign="top"><p class="table">hex version</p></td>
-<td align="center" valign="top"><p class="table">Download the given project version from hex.pm</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">fail</p></td>
-<td align="center" valign="top"><p class="table">N/A</p></td>
-<td align="center" valign="top"><p class="table">Always fail, reserved for internal use</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">legacy</p></td>
-<td align="center" valign="top"><p class="table">N/A</p></td>
-<td align="center" valign="top"><p class="table">Legacy Erlang.mk fetcher, reserved for internal use</p></td>
-</tr>
-</tbody>
-</table>
-</div>
-<div class="paragraph"><p>The <code>git</code> and <code>hg</code> methods both have a repository and commit.
-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"></div></div>
-<div class="paragraph"><p>Or to fetch Ehsa tag 4.0.3 from Mercurial:</p></div>
-<div class="listingblock">
-<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"></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"></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"></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"></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"></div></div>
-</div>
-<div class="sect3">
-<h4 id="_custom_fetch_methods">Custom fetch methods</h4>
-<div class="paragraph"><p>If none of the existing methods fit your use, you can simply
-define your own. Erlang.mk will consider all variables that
-are named as <code>dep_fetch_$(METHOD)</code> to be available fetch
-methods. You can do anything inside this variable, as long
-as you create a folder named <em>$(DEPS_DIR)/$(call dep_name,$1)</em>.
-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"></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>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_how_deps_are_fetched_and_built">How deps are fetched and built</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The order in which dependencies are fetched and built is well
-defined. This means that Erlang.mk will get the same applications
-regardless of the command or options being used.</p></div>
-<div class="paragraph"><p>In tree traversal terms, where the list of dependencies is a
-tree, Erlang.mk fetches everything using the pre-order traversal
-method. The steps can be summarized like this, starting from
-the root application:</p></div>
-<div class="olist arabic"><ol class="arabic">
-<li>
-<p>
-Fetch all dependencies for the application
-</p>
-</li>
-<li>
-<p>
-Build first dependency
-</p>
-</li>
-<li>
-<p>
-Build Nth dependency
-</p>
-</li>
-<li>
-<p>
-Build last dependency
-</p>
-</li>
-</ol></div>
-<div class="paragraph"><p>Every time a dependency is built, these same steps are followed,
-recursively.</p></div>
-<div class="paragraph"><p>Do note that the first step, fetching all dependencies of
-an application, is not guaranteed to be ordered. The reason
-for this is that it is not possible to have the same dependency
-listed twice in a single application, and therefore there can
-be no conflicts. Remember, this step only fetches, at no point
-are different applications built in parallel.</p></div>
-<div class="paragraph"><p>What about conflicts between the dependencies of different
-applications? Simple. Since builds are ordered, this means
-that the first version of an application that is fetched
-will be the one that wins.</p></div>
-<div class="paragraph"><p>This means that if project A depends on projects B and C,
-in this order, and that both B and C depend on a different
-version of D, it will always be B’s version of D that wins,
-because we fetch the dependencies of B before fetching
-those from C.</p></div>
-<div class="paragraph"><p>Similarly, if project A depends on projects B, C and D,
-regardless of the order, and A, B and C depend on a
-different version of D, it will always be A’s version
-that wins, because we fetch all dependencies of A before
-fetching those from B or C.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_fetching_and_listing_dependencies_only">Fetching and listing dependencies only</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can fetch all dependencies recursively without building anything,
-with the <code>make fetch-deps</code> command. It follows the same rules described
-in the section above.</p></div>
-<div class="paragraph"><p>You can list all dependencies recursively, again without building
-anything, with the <code>make list-deps</code> command. It will obviously need
-to fetch all dependencies exactly like <code>make fetch-deps</code>. Once
-everything is fetched, it prints a sorted list of absolute paths to the
-dependencies.</p></div>
-<div class="paragraph"><p>By default, <code>fetch-deps</code> and <code>list-deps</code> work on the <code>BUILD_DEPS</code>
-and <code>DEPS</code> lists only. To also fetch/list <code>TEST_DEPS</code>, <code>DOC_DEPS</code>,
-<code>REL_DEPS</code> and/or <code>SHELL_DEPS</code>, you have two possibilities:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-You can use <code>make fetch-test-deps</code>, <code>make fetch-doc-deps</code>, <code>make
- fetch-rel-deps</code> and <code>make fetch-shell-deps</code> commands respectively.
- If you want to list them, you can use <code>make list-test-deps</code>, <code>make
- list-doc-deps</code>, <code>make list-rel-deps</code> and <code>make list-shell-deps</code>
- respectively.
-</p>
-</li>
-<li>
-<p>
-You can use <code>make fetch-deps</code> or <code>make list-deps</code> with the Makefile
- variable <code>DEP_TYPES</code> set to a list of dependency types you want.
- The types are <code>test</code>, <code>doc</code>, <code>rel</code> and <code>shell</code> respectively. For
- example, you can list test and doc dependencies with <code>make list-deps
- DEP_TYPES='test doc'</code>.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Note that only first level ‘TEST_DEPS<code>, `DOC_DEPS</code>, <code>REL_DEPS</code> and
-<code>SHELL_DEPS</code> are included, not dependencies’ one. In other word,
-<code>make list-test-deps</code> lists the <code>TEST_DEPS</code> of your project, but not
-<code>TEST_DEPS</code> of the projects yours depend on.</p></div>
-<div class="paragraph"><p>No matter which method you use, <code>BUILD_DEPS</code> and <code>DEPS</code> are always
-included.</p></div>
-<div class="paragraph"><p>Internally, the <code>make fetch-*</code> commands store the complete list of
-dependencies in files named <code>$(ERLANG_MK_RECURSIVE_DEPS_LIST)</code>,
-<code>$(ERLANG_MK_RECURSIVE_TEST_DEPS_LIST)</code>,
-<code>$(ERLANG_MK_RECURSIVE_DOC_DEPS_LIST)</code>,
-<code>$(ERLANG_MK_RECURSIVE_REL_DEPS_LIST)</code> and
-<code>$(ERLANG_MK_RECURSIVE_SHELL_DEPS_LIST)</code>. Those files are simply printed
-by the <code>make list-*</code> commands.</p></div>
-<div class="paragraph"><p><code>make list-*</code> commands are made for human beings. If you need the list
-of dependencies in a Makefile or a script, you should use the content
-of those files directly instead. The reason is that <code>make fetch-*</code> and
-<code>make list-*</code> may have unwanted content in their output, such as actual
-fetching of dependencies.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_ignoring_unwanted_dependencies">Ignoring unwanted dependencies</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Sometimes, you may want to ignore dependencies entirely.
-Not even fetch them. You may want to do this because a
-project you depend on depends on an application you do
-not need (like a dependency for building documentation
-or testing). Or maybe the dependency is already installed
-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"></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"></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>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_dependencies_directory">Dependencies directory</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Dependencies are fetched in <em>$(DEPS_DIR)</em>. By default this is
-the <em>deps</em> directory. You can change this default, but you
-should only do so if it was not defined previously. Erlang.mk
-uses this variable to tell dependencies where to fetch their
-own dependencies.</p></div>
-<div class="paragraph"><p>You will therefore need to use <code>?=</code> instead of <code>=</code>. Of course,
-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"></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
-compatibility with Rebar build tools, as long as they are
-recent enough.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_many_applications_in_one_repository">Many applications in one repository</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>In addition to the dependencies that are fetched, Erlang.mk
-also allows you to have dependencies local to your repository.
-This kind of layout is sometimes called multi-application
-repositories, or repositories with multiple applications.</p></div>
-<div class="paragraph"><p>They work exactly the same as remote dependencies, except:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-They are not fetched
-</p>
-</li>
-<li>
-<p>
-They are not autopatched
-</p>
-</li>
-<li>
-<p>
-They are not deleted on <code>make distclean</code>
-</p>
-</li>
-<li>
-<p>
-They are not automatically added to the application resource file
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>To properly fill the application resource file and compile apps in
-the right order, you will need to define the <code>LOCAL_DEPS</code> variable
-for each relevant application, the same as for OTP applications. Apps
-can depend on each other in this way, and their compilation order
-will follow the same rules as regular dependencies in <code>DEPS</code>.</p></div>
-<div class="paragraph"><p>The top-level <code>LOCAL_DEPS</code> variable, if defined, will determine which
-apps (along with their dependencies) to build, and also which apps
-should be added to the top-level application resource file, if there
-is one. This may be useful, for example, for specifying a different
-set of apps to build for different releases. If <code>LOCAL_DEPS</code> is not
-defined, then all apps in the <em>$(APPS_DIR)</em> will be built, but none
-will be automatically added to the top-level application resource
-file.</p></div>
-<div class="paragraph"><p>If there is a conflict between a local dependency and a
-remote dependency, then the local dependency always wins;
-an error will be triggered when trying to fetch the
-conflicting remote dependency.</p></div>
-<div class="paragraph"><p>To start using dependencies local to the repository, simply
-create a folder named <em>$(APPS_DIR)</em>. By default, this folder
-is the <em>apps/</em> directory.</p></div>
-<div class="paragraph"><p>You can use Erlang.mk to bootstrap local dependencies by
-using the command <code>make new-app</code> or <code>make new-lib</code>. This
-command will create the necessary directories and bootstrap
-the application.</p></div>
-<div class="paragraph"><p>For example, to create a full fledged OTP application as
-a local dependency:</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-app <span style="font-weight: bold"><span style="color: #0000FF">in</span></span><span style="color: #990000">=</span>webchat</tt></pre></div></div>
-<div class="paragraph"><p>Or, the same as an OTP library:</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-lib <span style="font-weight: bold"><span style="color: #0000FF">in</span></span><span style="color: #990000">=</span>webchat</tt></pre></div></div>
-<div class="paragraph"><p>Templates also work with local dependencies, from the root
-directory of the project. You do need however to tell
-Erlang.mk to create the files in the correct 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>$ make new <span style="color: #009900">t</span><span style="color: #990000">=</span>gen_server <span style="color: #009900">n</span><span style="color: #990000">=</span>my_server <span style="font-weight: bold"><span style="color: #0000FF">in</span></span><span style="color: #990000">=</span>webchat</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_repositories_with_no_application_at_the_root_level">Repositories with no application at the root level</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>It’s possible to use Erlang.mk with only applications in
-<em>$(APPS_DIR)</em>, and nothing at the root of the repository.
-Just create a folder, put the <em>erlang.mk</em> file in it,
-write a Makefile that includes it, and start creating
-your applications.</p></div>
-<div class="paragraph"><p>Similarly, it’s possible to have a repository with only
-dependencies found in <em>$(DEPS_DIR)</em>. You just need to
-create a Makefile and specify the dependencies you want.
-This allows you to create a repository for handling the
-building of releases, for example.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_autopatch">Autopatch</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk will automatically patch all the dependencies it
-fetches. It needs to do this to ensure that the dependencies
-become compatible with not only Erlang.mk, but also with
-the version of Erlang.mk that is currently used.</p></div>
-<div class="paragraph"><p>When fetching a dependency, the following operations are
-performed:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Fetch the dependency using the configured fetch method
-</p>
-</li>
-<li>
-<p>
-If it contains a <em>configure.ac</em> or <em>configure.in</em> file, run <code>autoreconf -Wall -vif -I m4</code>
-</p>
-</li>
-<li>
-<p>
-If it contains a <em>configure</em> script, run it
-</p>
-</li>
-<li>
-<p>
-Run autopatch on the project
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Autopatch first checks if there is any project-specific patch
-enabled. There are currently two: <code>RABBITMQ_CLIENT_PATCH</code> for
-the <code>amqp_client</code> dependency, and <code>RABBITMQ_SERVER_PATCH</code> for
-the <code>rabbit</code> dependency. These are needed only for RabbitMQ
-versions before 3.6.0 (assuming you are using upstream RabbitMQ,
-and not a fork).</p></div>
-<div class="paragraph"><p>Otherwise, autopatch performs different operations depending
-on the kind of project it finds the dependency to be.</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Rebar projects are automatically converted to use Erlang.mk
-as their build tool. This essentially patches Rebar out, and
-fixes and converts the project to be compatible with Erlang.mk.
-</p>
-</li>
-<li>
-<p>
-Erlang.mk projects have their <em>Makefile</em> patched, if necessary,
-to include the top-level project’s Erlang.mk. This is to ensure
-that functionality works across all dependencies, even if the
-dependency’s Erlang.mk is outdated. The patched Makefile
-can be safely committed if necessary.
-</p>
-</li>
-<li>
-<p>
-Other Erlang projects get a small Erlang.mk Makefile
-generated automatically.
-</p>
-</li>
-<li>
-<p>
-Projects with no source directory and no Makefile get an
-empty Makefile generated, for compatibility purposes.
-</p>
-</li>
-<li>
-<p>
-Other projects with no Makefile are left untouched.
-</p>
-</li>
-</ul></div>
-<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"></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"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_skipping_deps">Skipping deps</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>It is possible to temporarily skip all dependency operations.
-This is done by defining the <code>SKIP_DEPS</code> variable. Use cases
-include being somewhere with no connection to download them,
-or perhaps a peculiar setup.</p></div>
-<div class="paragraph"><p>A typical usage would be:</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 <span style="color: #009900">SKIP_DEPS</span><span style="color: #990000">=</span><span style="color: #993399">1</span></tt></pre></div></div>
-<div class="paragraph"><p>When the variable is defined:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Dependencies will not be compiled or downloaded when required
-</p>
-</li>
-<li>
-<p>
-The dependency directory <em>$(DEPS_DIR)</em> will not be removed on <code>make distclean</code>
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>This variable only applies to remote dependencies.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Erlang.mk can fetch and compile the dependencies that your +project requires. Erlang.mk improves upon the concepts +introduced by Rebar, so they should be familiar to many +seasoned Erlang developers.</p></div> +<div class="paragraph"><p>Erlang.mk is not a package manager, nor is it trying to be, +but it does include an index of Erlang packages to make +discovering useful projects easier.</p></div> +<div class="paragraph"><p>This chapter will explain how to use packages, add +dependencies to your project or bundle them directly +in a single repository.</p></div> +<div class="sect1"> +<h2 id="_searching_packages">Searching packages</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk gives you access to nearly 500 packages, with more +being added regularly.</p></div> +<div class="paragraph"><p>To find a package, search for 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>$ make search <span style="color: #009900">q</span><span style="color: #990000">=</span>pool</tt></pre></div></div> +<div class="paragraph"><p>This will return all packages matching this word, like worker +pool and acceptor pool projects.</p></div> +<div class="paragraph"><p>You can also list everything and use regular command line +tools to find what you need, 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>$ make search <span style="color: #990000">|</span> less</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_adding_dependencies_to_your_project">Adding dependencies to your project</h2> +<div class="sectionbody"> +<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="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 +other operations.</p></div> +<div class="paragraph"><p>Erlang.mk will fill in the application resource file with +all applications found in <code>DEPS</code>. But not all dependencies +are Erlang applications, and not all dependencies need to +be a runtime dependency. That’s where the <code>BUILD_DEPS</code> +variable comes in: it works just like <code>DEPS</code>, except the +dependencies listed there will not be added as runtime +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="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="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 +about that in the <a href="../ports">NIFs and port drivers</a> +chapter.</p></div> +<div class="paragraph"><p>Another variable, <code>LOCAL_DEPS</code>, allows specifying runtime +dependencies which are part of Erlang/OTP itself, but also +dependencies that are included in the repository. Since they +are already on your system, there is no need to fetch them. +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="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="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="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="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="paragraph"><p>All these will be documented in more details in their respective +chapters.</p></div> +<div class="sect3"> +<h4 id="_modifying_the_dependency_source_or_version">Modifying the dependency source or version</h4> +<div class="paragraph"><p>By default, Erlang.mk will look into its package index to +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="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> +<div class="paragraph"><p>If you simply want to change the commit number, all you +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="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 +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="paragraph"><p>This will fetch Cowboy from your fork at the given commit.</p></div> +</div> +<div class="sect3"> +<h4 id="_fetch_methods">Fetch methods</h4> +<div class="paragraph"><p>Erlang.mk comes with a number of different fetch methods. +You can fetch from Git, Mercurial, SVN, to name a few. +There are fetch methods that will work everywhere, and +fetch methods that will only work in a given environment.</p></div> +<div class="paragraph"><p>The following table lists all existing methods:</p></div> +<div class="tableblock"> +<table rules="all" +width="100%" +frame="border" +cellspacing="0" cellpadding="4"> +<col width="33%" /> +<col width="33%" /> +<col width="33%" /> +<thead> +<tr> +<th align="left" valign="top"> Name </th> +<th align="center" valign="top"> Format </th> +<th align="center" valign="top"> Description</th> +</tr> +</thead> +<tbody> +<tr> +<td align="left" valign="top"><p class="table">git</p></td> +<td align="center" valign="top"><p class="table">git repo commit</p></td> +<td align="center" valign="top"><p class="table">Clone the Git repository and checkout the given version</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">git-submodule</p></td> +<td align="center" valign="top"><p class="table">git-submodule</p></td> +<td align="center" valign="top"><p class="table">Initialize and update the Git submodule</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">hg</p></td> +<td align="center" valign="top"><p class="table">hg repo commit</p></td> +<td align="center" valign="top"><p class="table">Clone the Mercurial repository and update to the given version</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">svn</p></td> +<td align="center" valign="top"><p class="table">svn repo</p></td> +<td align="center" valign="top"><p class="table">Checkout the given SVN repository</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">cp</p></td> +<td align="center" valign="top"><p class="table">cp path/to/repo</p></td> +<td align="center" valign="top"><p class="table">Recursively copy a local directory</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">ln</p></td> +<td align="center" valign="top"><p class="table">ln path/to/repo</p></td> +<td align="center" valign="top"><p class="table">Symbolically link a local directory</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">hex</p></td> +<td align="center" valign="top"><p class="table">hex version</p></td> +<td align="center" valign="top"><p class="table">Download the given project version from hex.pm</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">fail</p></td> +<td align="center" valign="top"><p class="table">N/A</p></td> +<td align="center" valign="top"><p class="table">Always fail, reserved for internal use</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">legacy</p></td> +<td align="center" valign="top"><p class="table">N/A</p></td> +<td align="center" valign="top"><p class="table">Legacy Erlang.mk fetcher, reserved for internal use</p></td> +</tr> +</tbody> +</table> +</div> +<div class="paragraph"><p>The <code>git</code> and <code>hg</code> methods both have a repository and commit. +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="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="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="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="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="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="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> +<div class="sect3"> +<h4 id="_custom_fetch_methods">Custom fetch methods</h4> +<div class="paragraph"><p>If none of the existing methods fit your use, you can simply +define your own. Erlang.mk will consider all variables that +are named as <code>dep_fetch_$(METHOD)</code> to be available fetch +methods. You can do anything inside this variable, as long +as you create a folder named <em>$(DEPS_DIR)/$(call dep_name,$1)</em>. +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="paragraph"><p>Note that, like dependency information, this custom fetch method +must be written before including <em>erlang.mk</em>.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_how_deps_are_fetched_and_built">How deps are fetched and built</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The order in which dependencies are fetched and built is well +defined. This means that Erlang.mk will get the same applications +regardless of the command or options being used.</p></div> +<div class="paragraph"><p>In tree traversal terms, where the list of dependencies is a +tree, Erlang.mk fetches everything using the pre-order traversal +method. The steps can be summarized like this, starting from +the root application:</p></div> +<div class="olist arabic"><ol class="arabic"> +<li> +<p> +Fetch all dependencies for the application +</p> +</li> +<li> +<p> +Build first dependency +</p> +</li> +<li> +<p> +Build Nth dependency +</p> +</li> +<li> +<p> +Build last dependency +</p> +</li> +</ol></div> +<div class="paragraph"><p>Every time a dependency is built, these same steps are followed, +recursively.</p></div> +<div class="paragraph"><p>Do note that the first step, fetching all dependencies of +an application, is not guaranteed to be ordered. The reason +for this is that it is not possible to have the same dependency +listed twice in a single application, and therefore there can +be no conflicts. Remember, this step only fetches, at no point +are different applications built in parallel.</p></div> +<div class="paragraph"><p>What about conflicts between the dependencies of different +applications? Simple. Since builds are ordered, this means +that the first version of an application that is fetched +will be the one that wins.</p></div> +<div class="paragraph"><p>This means that if project A depends on projects B and C, +in this order, and that both B and C depend on a different +version of D, it will always be B’s version of D that wins, +because we fetch the dependencies of B before fetching +those from C.</p></div> +<div class="paragraph"><p>Similarly, if project A depends on projects B, C and D, +regardless of the order, and A, B and C depend on a +different version of D, it will always be A’s version +that wins, because we fetch all dependencies of A before +fetching those from B or C.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_fetching_and_listing_dependencies_only">Fetching and listing dependencies only</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You can fetch all dependencies recursively without building anything, +with the <code>make fetch-deps</code> command. It follows the same rules described +in the section above.</p></div> +<div class="paragraph"><p>You can list all dependencies recursively, again without building +anything, with the <code>make list-deps</code> command. It will obviously need +to fetch all dependencies exactly like <code>make fetch-deps</code>. Once +everything is fetched, it prints a sorted list of absolute paths to the +dependencies.</p></div> +<div class="paragraph"><p>By default, <code>fetch-deps</code> and <code>list-deps</code> work on the <code>BUILD_DEPS</code> +and <code>DEPS</code> lists only. To also fetch/list <code>TEST_DEPS</code>, <code>DOC_DEPS</code>, +<code>REL_DEPS</code> and/or <code>SHELL_DEPS</code>, you have two possibilities:</p></div> +<div class="ulist"><ul> +<li> +<p> +You can use <code>make fetch-test-deps</code>, <code>make fetch-doc-deps</code>, <code>make + fetch-rel-deps</code> and <code>make fetch-shell-deps</code> commands respectively. + If you want to list them, you can use <code>make list-test-deps</code>, <code>make + list-doc-deps</code>, <code>make list-rel-deps</code> and <code>make list-shell-deps</code> + respectively. +</p> +</li> +<li> +<p> +You can use <code>make fetch-deps</code> or <code>make list-deps</code> with the Makefile + variable <code>DEP_TYPES</code> set to a list of dependency types you want. + The types are <code>test</code>, <code>doc</code>, <code>rel</code> and <code>shell</code> respectively. For + example, you can list test and doc dependencies with <code>make list-deps + DEP_TYPES='test doc'</code>. +</p> +</li> +</ul></div> +<div class="paragraph"><p>Note that only first level ‘TEST_DEPS<code>, `DOC_DEPS</code>, <code>REL_DEPS</code> and +<code>SHELL_DEPS</code> are included, not dependencies’ one. In other word, +<code>make list-test-deps</code> lists the <code>TEST_DEPS</code> of your project, but not +<code>TEST_DEPS</code> of the projects yours depend on.</p></div> +<div class="paragraph"><p>No matter which method you use, <code>BUILD_DEPS</code> and <code>DEPS</code> are always +included.</p></div> +<div class="paragraph"><p>Internally, the <code>make fetch-*</code> commands store the complete list of +dependencies in files named <code>$(ERLANG_MK_RECURSIVE_DEPS_LIST)</code>, +<code>$(ERLANG_MK_RECURSIVE_TEST_DEPS_LIST)</code>, +<code>$(ERLANG_MK_RECURSIVE_DOC_DEPS_LIST)</code>, +<code>$(ERLANG_MK_RECURSIVE_REL_DEPS_LIST)</code> and +<code>$(ERLANG_MK_RECURSIVE_SHELL_DEPS_LIST)</code>. Those files are simply printed +by the <code>make list-*</code> commands.</p></div> +<div class="paragraph"><p><code>make list-*</code> commands are made for human beings. If you need the list +of dependencies in a Makefile or a script, you should use the content +of those files directly instead. The reason is that <code>make fetch-*</code> and +<code>make list-*</code> may have unwanted content in their output, such as actual +fetching of dependencies.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_ignoring_unwanted_dependencies">Ignoring unwanted dependencies</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Sometimes, you may want to ignore dependencies entirely. +Not even fetch them. You may want to do this because a +project you depend on depends on an application you do +not need (like a dependency for building documentation +or testing). Or maybe the dependency is already installed +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="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="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> +</div> +</div> +<div class="sect1"> +<h2 id="_dependencies_directory">Dependencies directory</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Dependencies are fetched in <em>$(DEPS_DIR)</em>. By default this is +the <em>deps</em> directory. You can change this default, but you +should only do so if it was not defined previously. Erlang.mk +uses this variable to tell dependencies where to fetch their +own dependencies.</p></div> +<div class="paragraph"><p>You will therefore need to use <code>?=</code> instead of <code>=</code>. Of course, +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="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 +compatibility with Rebar build tools, as long as they are +recent enough.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_many_applications_in_one_repository">Many applications in one repository</h2> +<div class="sectionbody"> +<div class="paragraph"><p>In addition to the dependencies that are fetched, Erlang.mk +also allows you to have dependencies local to your repository. +This kind of layout is sometimes called multi-application +repositories, or repositories with multiple applications.</p></div> +<div class="paragraph"><p>They work exactly the same as remote dependencies, except:</p></div> +<div class="ulist"><ul> +<li> +<p> +They are not fetched +</p> +</li> +<li> +<p> +They are not autopatched +</p> +</li> +<li> +<p> +They are not deleted on <code>make distclean</code> +</p> +</li> +<li> +<p> +They are not automatically added to the application resource file +</p> +</li> +</ul></div> +<div class="paragraph"><p>To properly fill the application resource file and compile apps in +the right order, you will need to define the <code>LOCAL_DEPS</code> variable +for each relevant application, the same as for OTP applications. Apps +can depend on each other in this way, and their compilation order +will follow the same rules as regular dependencies in <code>DEPS</code>.</p></div> +<div class="paragraph"><p>The top-level <code>LOCAL_DEPS</code> variable, if defined, will determine which +apps (along with their dependencies) to build, and also which apps +should be added to the top-level application resource file, if there +is one. This may be useful, for example, for specifying a different +set of apps to build for different releases. If <code>LOCAL_DEPS</code> is not +defined, then all apps in the <em>$(APPS_DIR)</em> will be built, but none +will be automatically added to the top-level application resource +file.</p></div> +<div class="paragraph"><p>If there is a conflict between a local dependency and a +remote dependency, then the local dependency always wins; +an error will be triggered when trying to fetch the +conflicting remote dependency.</p></div> +<div class="paragraph"><p>To start using dependencies local to the repository, simply +create a folder named <em>$(APPS_DIR)</em>. By default, this folder +is the <em>apps/</em> directory.</p></div> +<div class="paragraph"><p>You can use Erlang.mk to bootstrap local dependencies by +using the command <code>make new-app</code> or <code>make new-lib</code>. This +command will create the necessary directories and bootstrap +the application.</p></div> +<div class="paragraph"><p>For example, to create a full fledged OTP application as +a local dependency:</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-app <span style="font-weight: bold"><span style="color: #0000FF">in</span></span><span style="color: #990000">=</span>webchat</tt></pre></div></div> +<div class="paragraph"><p>Or, the same as an OTP library:</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-lib <span style="font-weight: bold"><span style="color: #0000FF">in</span></span><span style="color: #990000">=</span>webchat</tt></pre></div></div> +<div class="paragraph"><p>Templates also work with local dependencies, from the root +directory of the project. You do need however to tell +Erlang.mk to create the files in the correct 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>$ make new <span style="color: #009900">t</span><span style="color: #990000">=</span>gen_server <span style="color: #009900">n</span><span style="color: #990000">=</span>my_server <span style="font-weight: bold"><span style="color: #0000FF">in</span></span><span style="color: #990000">=</span>webchat</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_repositories_with_no_application_at_the_root_level">Repositories with no application at the root level</h2> +<div class="sectionbody"> +<div class="paragraph"><p>It’s possible to use Erlang.mk with only applications in +<em>$(APPS_DIR)</em>, and nothing at the root of the repository. +Just create a folder, put the <em>erlang.mk</em> file in it, +write a Makefile that includes it, and start creating +your applications.</p></div> +<div class="paragraph"><p>Similarly, it’s possible to have a repository with only +dependencies found in <em>$(DEPS_DIR)</em>. You just need to +create a Makefile and specify the dependencies you want. +This allows you to create a repository for handling the +building of releases, for example.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_autopatch">Autopatch</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk will automatically patch all the dependencies it +fetches. It needs to do this to ensure that the dependencies +become compatible with not only Erlang.mk, but also with +the version of Erlang.mk that is currently used.</p></div> +<div class="paragraph"><p>When fetching a dependency, the following operations are +performed:</p></div> +<div class="ulist"><ul> +<li> +<p> +Fetch the dependency using the configured fetch method +</p> +</li> +<li> +<p> +If it contains a <em>configure.ac</em> or <em>configure.in</em> file, run <code>autoreconf -Wall -vif -I m4</code> +</p> +</li> +<li> +<p> +If it contains a <em>configure</em> script, run it +</p> +</li> +<li> +<p> +Run autopatch on the project +</p> +</li> +</ul></div> +<div class="paragraph"><p>Autopatch first checks if there is any project-specific patch +enabled. There are currently two: <code>RABBITMQ_CLIENT_PATCH</code> for +the <code>amqp_client</code> dependency, and <code>RABBITMQ_SERVER_PATCH</code> for +the <code>rabbit</code> dependency. These are needed only for RabbitMQ +versions before 3.6.0 (assuming you are using upstream RabbitMQ, +and not a fork).</p></div> +<div class="paragraph"><p>Otherwise, autopatch performs different operations depending +on the kind of project it finds the dependency to be.</p></div> +<div class="ulist"><ul> +<li> +<p> +Rebar projects are automatically converted to use Erlang.mk +as their build tool. This essentially patches Rebar out, and +fixes and converts the project to be compatible with Erlang.mk. +</p> +</li> +<li> +<p> +Erlang.mk projects have their <em>Makefile</em> patched, if necessary, +to include the top-level project’s Erlang.mk. This is to ensure +that functionality works across all dependencies, even if the +dependency’s Erlang.mk is outdated. The patched Makefile +can be safely committed if necessary. +</p> +</li> +<li> +<p> +Other Erlang projects get a small Erlang.mk Makefile +generated automatically. +</p> +</li> +<li> +<p> +Projects with no source directory and no Makefile get an +empty Makefile generated, for compatibility purposes. +</p> +</li> +<li> +<p> +Other projects with no Makefile are left untouched. +</p> +</li> +</ul></div> +<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="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> +</div> +<div class="sect1"> +<h2 id="_skipping_deps">Skipping deps</h2> +<div class="sectionbody"> +<div class="paragraph"><p>It is possible to temporarily skip all dependency operations. +This is done by defining the <code>SKIP_DEPS</code> variable. Use cases +include being somewhere with no connection to download them, +or perhaps a peculiar setup.</p></div> +<div class="paragraph"><p>A typical usage would be:</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 <span style="color: #009900">SKIP_DEPS</span><span style="color: #990000">=</span><span style="color: #993399">1</span></tt></pre></div></div> +<div class="paragraph"><p>When the variable is defined:</p></div> +<div class="ulist"><ul> +<li> +<p> +Dependencies will not be compiled or downloaded when required +</p> +</li> +<li> +<p> +The dependency directory <em>$(DEPS_DIR)</em> will not be removed on <code>make distclean</code> +</p> +</li> +</ul></div> +<div class="paragraph"><p>This variable only applies to remote dependencies.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/dialyzer/index.html b/docs/en/erlang.mk/1/guide/dialyzer/index.html index d6c7a467..5d8779f8 100644 --- a/docs/en/erlang.mk/1/guide/dialyzer/index.html +++ b/docs/en/erlang.mk/1/guide/dialyzer/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Dialyzer</title> @@ -67,83 +67,86 @@ <h1 class="lined-header"><span>Dialyzer</span></h1> -<div class="paragraph"><p>Dialyzer is a tool that will detect discrepancies in your
-program. It does so using a technique known as success
-typing analysis which has the advantage of providing no
-false positives. Dialyzer is able to detect type errors,
-dead code and more.</p></div>
-<div class="paragraph"><p>Erlang.mk provides a wrapper around Dialyzer.</p></div>
-<div class="sect1">
-<h2 id="_how_it_works">How it works</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Dialyzer requires a PLT file to work. The PLT file contains
-the analysis information from all applications which are not
-expected to change, or rarely do. These would be all the
-dependencies of the application or applications you are
-currently working on, including standard applications in
-Erlang/OTP itself.</p></div>
-<div class="paragraph"><p>Dialyzer can generate this PLT file. Erlang.mk includes rules
-to automatically generate the PLT file when it is missing.</p></div>
-<div class="paragraph"><p>Once the PLT file is generated, Dialyzer can perform the
-analysis in record time.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_configuration">Configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>In a typical usage scenario, no variable needs to be set.
-The defaults should be enough. Do note however that the
-dependencies need to be set properly using the <code>DEPS</code> and
-<code>LOCAL_DEPS</code> variables.</p></div>
-<div class="paragraph"><p>The <code>DIALYZER_PLT</code> file indicates where the PLT file will
-be written to (and read from). By default this is
-<em>$(PROJECT).plt</em> in the project’s directory. Note that
-the <code>DIALYZER_PLT</code> variable is exported and is understood
-by Dialyzer directly.</p></div>
-<div class="paragraph"><p>The <code>PLT_APPS</code> variable can be used to add additional
-applications to the PLT. You can either list application
-names or paths to these applications.</p></div>
-<div class="paragraph"><p>Erlang.mk defines two variables for specifying options
-for the analysis: <code>DIALYZER_DIRS</code> and <code>DIALYZER_OPTS</code>.
-The former one defines which directories should be part
-of the analysis. The latter defines what extra warnings
-Dialyzer should report.</p></div>
-<div class="paragraph"><p>Note that Erlang.mk enables the race condition warnings
-by default. As it can take considerably large resources
-to run, you may want to disable it on larger projects.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_usage">Usage</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To perform an analysis, run the following 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>$ make dialyze</tt></pre></div></div>
-<div class="paragraph"><p>This will create the PLT file if it doesn’t exist.</p></div>
-<div class="paragraph"><p>The analysis will also be performed when you run the
-following command, alongside tests:</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 check</tt></pre></div></div>
-<div class="paragraph"><p>You can use the <code>plt</code> target to create the PLT file if
-it doesn’t exist. This is normally not necessary as
-Dialyzer creates it automatically.</p></div>
-<div class="paragraph"><p>The PLT file will be removed when you run <code>make distclean</code>.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Dialyzer is a tool that will detect discrepancies in your +program. It does so using a technique known as success +typing analysis which has the advantage of providing no +false positives. Dialyzer is able to detect type errors, +dead code and more.</p></div> +<div class="paragraph"><p>Erlang.mk provides a wrapper around Dialyzer.</p></div> +<div class="sect1"> +<h2 id="_how_it_works">How it works</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Dialyzer requires a PLT file to work. The PLT file contains +the analysis information from all applications which are not +expected to change, or rarely do. These would be all the +dependencies of the application or applications you are +currently working on, including standard applications in +Erlang/OTP itself.</p></div> +<div class="paragraph"><p>Dialyzer can generate this PLT file. Erlang.mk includes rules +to automatically generate the PLT file when it is missing.</p></div> +<div class="paragraph"><p>Once the PLT file is generated, Dialyzer can perform the +analysis in record time.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>In a typical usage scenario, no variable needs to be set. +The defaults should be enough. Do note however that the +dependencies need to be set properly using the <code>DEPS</code> and +<code>LOCAL_DEPS</code> variables.</p></div> +<div class="paragraph"><p>The <code>DIALYZER_PLT</code> file indicates where the PLT file will +be written to (and read from). By default this is +<em>$(PROJECT).plt</em> in the project’s directory. Note that +the <code>DIALYZER_PLT</code> variable is exported and is understood +by Dialyzer directly.</p></div> +<div class="paragraph"><p>The <code>PLT_APPS</code> variable can be used to add additional +applications to the PLT. You can either list application +names or paths to these applications.</p></div> +<div class="paragraph"><p>Erlang.mk defines two variables for specifying options +for the analysis: <code>DIALYZER_DIRS</code> and <code>DIALYZER_OPTS</code>. +The former one defines which directories should be part +of the analysis. The latter defines what extra warnings +Dialyzer should report.</p></div> +<div class="paragraph"><p>Note that Erlang.mk enables the race condition warnings +by default. As it can take considerably large resources +to run, you may want to disable it on larger projects.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_usage">Usage</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To perform an analysis, run the following 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>$ make dialyze</tt></pre></div></div> +<div class="paragraph"><p>This will create the PLT file if it doesn’t exist.</p></div> +<div class="paragraph"><p>The analysis will also be performed when you run the +following command, alongside tests:</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 check</tt></pre></div></div> +<div class="paragraph"><p>You can use the <code>plt</code> target to create the PLT file if +it doesn’t exist. This is normally not necessary as +Dialyzer creates it automatically.</p></div> +<div class="paragraph"><p>The PLT file will be removed when you run <code>make distclean</code>.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/edoc/index.html b/docs/en/erlang.mk/1/guide/edoc/index.html index bc6befd3..6fcaeeed 100644 --- a/docs/en/erlang.mk/1/guide/edoc/index.html +++ b/docs/en/erlang.mk/1/guide/edoc/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: EDoc comments</title> @@ -67,60 +67,72 @@ <h1 class="lined-header"><span>EDoc comments</span></h1> -<div class="paragraph"><p>Erlang.mk provides a thin wrapper on top of EDoc, an application
-that generates documentation based on comments found in modules.</p></div>
-<div class="sect1">
-<h2 id="_writing_edoc_comments">Writing EDoc comments</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <a href="http://www.erlang.org/doc/apps/edoc/chapter.html">EDoc user guide</a>
-explains everything you need to know about EDoc comments.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_configuration">Configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>EDOC_OPTS</code> variable allows you to specify additional
-EDoc options. Options are documented in the
-<a href="http://www.erlang.org/doc/man/edoc.html#run-2">EDoc manual</a>.</p></div>
-<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"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_usage">Usage</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To build all documentation, you would typically use:</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 docs</tt></pre></div></div>
-<div class="paragraph"><p>Do note, however, that EDoc comments will only be generated
-automatically if the <em>doc/overview.edoc</em> file exists. If you
-do not want that file and still want to generate doc comments,
-two solutions are available.</p></div>
-<div class="paragraph"><p>You can generate EDoc documentation 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>$ make edoc</tt></pre></div></div>
-<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"></div></div>
-</div>
-</div>
+<div class="paragraph"><p>Erlang.mk provides a thin wrapper on top of EDoc, an application +that generates documentation based on comments found in modules.</p></div> +<div class="sect1"> +<h2 id="_writing_edoc_comments">Writing EDoc comments</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <a href="http://www.erlang.org/doc/apps/edoc/chapter.html">EDoc user guide</a> +explains everything you need to know about EDoc comments.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>EDOC_OPTS</code> variable allows you to specify additional +EDoc options. Options are documented in the +<a href="http://www.erlang.org/doc/man/edoc.html#run-2">EDoc manual</a>.</p></div> +<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> +</div> +<div class="sect1"> +<h2 id="_usage">Usage</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To build all documentation, you would typically use:</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 docs</tt></pre></div></div> +<div class="paragraph"><p>Do note, however, that EDoc comments will only be generated +automatically if the <em>doc/overview.edoc</em> file exists. If you +do not want that file and still want to generate doc comments, +two solutions are available.</p></div> +<div class="paragraph"><p>You can generate EDoc documentation 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>$ make edoc</tt></pre></div></div> +<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> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/escripts/index.html b/docs/en/erlang.mk/1/guide/escripts/index.html index 2bdc36bf..89cffc80 100644 --- a/docs/en/erlang.mk/1/guide/escripts/index.html +++ b/docs/en/erlang.mk/1/guide/escripts/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Escripts</title> @@ -67,97 +67,105 @@ <h1 class="lined-header"><span>Escripts</span></h1> -<div class="paragraph"><p>Escripts are an alternative to release. They are meant to be
-used for small command line executables written in Erlang.</p></div>
-<div class="paragraph"><p>They are not self-contained, unlike <a href="../relx">releases</a>.
-Erlang must be installed for them to run. This however means
-that they are fairly small compared to releases.</p></div>
-<div class="paragraph"><p>For self-contained executables, check <a href="../sfx">self-extracting releases</a>.</p></div>
-<div class="sect1">
-<h2 id="_requirements">Requirements</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk uses <code>p7zip</code> by default to generate the escript
-archive. Make sure it is installed. On most systems the
-package is named <code>p7zip</code>; on Ubuntu you need <code>p7zip-full</code>.</p></div>
-<div class="paragraph"><p>If <code>p7zip</code> is unavailable, <code>zip</code> may be used by setting
-the <code>ESCRIPT_ZIP</code> variable. 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>$ make escript <span style="color: #009900">ESCRIPT_ZIP</span><span style="color: #990000">=</span>zip</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_generating_an_escript">Generating an escript</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Run the following command to generate an escript:</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 escript</tt></pre></div></div>
-<div class="paragraph"><p>This will by default create an escript with the same name as
-the project, in the project’s directory. If the project is
-called <code>relx</code> then the escript will be in <code>./relx</code>.</p></div>
-<div class="paragraph"><p>You can run the escript as you would any 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: #990000">.</span>/relx</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_configuration">Configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can change the name of the escript by setting <code>ESCRIPT_NAME</code>.
-The name determines both the default output file name and the
-entry module containing the function <code>main/1</code>.</p></div>
-<div class="paragraph"><p><code>ESCRIPT_FILE</code> can be set if you need a different file name
-or location.</p></div>
-<div class="paragraph"><p>The escript header can be entirely customized. The first line
-is the shebang, set by <code>ESCRIPT_SHEBANG</code>. The second line is
-a comment, set by <code>ESCRIPT_COMMENT</code>. The third line is the
-arguments the VM will use when running the escript, set by
-<code>ESCRIPT_EMU_ARGS</code>.</p></div>
-<div class="paragraph"><p>Finally, <code>ESCRIPT_ZIP</code> can be set to customize the command used
-to create the zip file. Read on for more information.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_extra_files">Extra files</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Generating an escript is a two-part process. First, a zip file
-is created with the contents of the escript. Then a header is
-added to this file to create the escript.</p></div>
-<div class="paragraph"><p>It is possible to add commands that will be executed between
-the two steps. You can for example add extra files to the zip
-archive:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>The <code>ESCRIPT_ZIP</code> variable contains the command to run to add
-files to the zip archive <code>ESCRIPT_ZIP_FILE</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_optimizing_for_size">Optimizing for size</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk will by default compile BEAM files with debug
-information. You may want to disable this behavior to obtain
-smaller escript files. Simply set <code>ERLC_OPTS</code> to a value that
-does not include <code>+debug_info</code>.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Escripts are an alternative to release. They are meant to be +used for small command line executables written in Erlang.</p></div> +<div class="paragraph"><p>They are not self-contained, unlike <a href="../relx">releases</a>. +Erlang must be installed for them to run. This however means +that they are fairly small compared to releases.</p></div> +<div class="paragraph"><p>For self-contained executables, check <a href="../sfx">self-extracting releases</a>.</p></div> +<div class="sect1"> +<h2 id="_requirements">Requirements</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk uses <code>p7zip</code> by default to generate the escript +archive. Make sure it is installed. On most systems the +package is named <code>p7zip</code>; on Ubuntu you need <code>p7zip-full</code>.</p></div> +<div class="paragraph"><p>If <code>p7zip</code> is unavailable, <code>zip</code> may be used by setting +the <code>ESCRIPT_ZIP</code> variable. 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>$ make escript <span style="color: #009900">ESCRIPT_ZIP</span><span style="color: #990000">=</span>zip</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_generating_an_escript">Generating an escript</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Run the following command to generate an escript:</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 escript</tt></pre></div></div> +<div class="paragraph"><p>This will by default create an escript with the same name as +the project, in the project’s directory. If the project is +called <code>relx</code> then the escript will be in <code>./relx</code>.</p></div> +<div class="paragraph"><p>You can run the escript as you would any 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: #990000">.</span>/relx</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You can change the name of the escript by setting <code>ESCRIPT_NAME</code>. +The name determines both the default output file name and the +entry module containing the function <code>main/1</code>.</p></div> +<div class="paragraph"><p><code>ESCRIPT_FILE</code> can be set if you need a different file name +or location.</p></div> +<div class="paragraph"><p>The escript header can be entirely customized. The first line +is the shebang, set by <code>ESCRIPT_SHEBANG</code>. The second line is +a comment, set by <code>ESCRIPT_COMMENT</code>. The third line is the +arguments the VM will use when running the escript, set by +<code>ESCRIPT_EMU_ARGS</code>.</p></div> +<div class="paragraph"><p>Finally, <code>ESCRIPT_ZIP</code> can be set to customize the command used +to create the zip file. Read on for more information.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_extra_files">Extra files</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Generating an escript is a two-part process. First, a zip file +is created with the contents of the escript. Then a header is +added to this file to create the escript.</p></div> +<div class="paragraph"><p>It is possible to add commands that will be executed between +the two steps. You can for example add extra files to the zip +archive:</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">escript-zip::</span> + <span style="color: #009900">$(verbose)</span> <span style="color: #009900">$(ESCRIPT_ZIP)</span> <span style="color: #009900">$(ESCRIPT_ZIP_FILE)</span> priv/templates<span style="color: #990000">/*</span></tt></pre></div></div> +<div class="paragraph"><p>The <code>ESCRIPT_ZIP</code> variable contains the command to run to add +files to the zip archive <code>ESCRIPT_ZIP_FILE</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_optimizing_for_size">Optimizing for size</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk will by default compile BEAM files with debug +information. You may want to disable this behavior to obtain +smaller escript files. Simply set <code>ERLC_OPTS</code> to a value that +does not include <code>+debug_info</code>.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> @@ -167,8 +175,8 @@ does not include <code>+debug_info</code>.</p></div> - <a style="float:right" href="https://ninenines.eu/docs/en/erlang.mk/1/guide/compat/"> - Compatibility with other build tools + <a style="float:right" href="https://ninenines.eu/docs/en/erlang.mk/1/guide/kerl/"> + OTP version management </a> </nav> diff --git a/docs/en/erlang.mk/1/guide/eunit/index.html b/docs/en/erlang.mk/1/guide/eunit/index.html index d3af8b7b..83435883 100644 --- a/docs/en/erlang.mk/1/guide/eunit/index.html +++ b/docs/en/erlang.mk/1/guide/eunit/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: EUnit</title> @@ -67,147 +67,158 @@ <h1 class="lined-header"><span>EUnit</span></h1> -<div class="paragraph"><p>EUnit is the tool of choice for unit testing. Erlang.mk
-automates a few things on top of EUnit, including the
-discovery and running of unit tests.</p></div>
-<div class="sect1">
-<h2 id="_writing_tests">Writing tests</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <a href="http://www.erlang.org/doc/apps/eunit/chapter.html">EUnit user guide</a>
-is the best place to learn how to write tests. Of note is
-that all functions ending with <code>_test</code> or <code>_test_</code> will be
-picked up as EUnit test cases.</p></div>
-<div class="paragraph"><p>Erlang.mk will automatically pick up tests found in any of
-the Erlang modules of your application. It will also pick up
-tests located in the <em>$(TEST_DIR)</em> directory, which defaults
-to <em>test/</em>.</p></div>
-<div class="paragraph"><p>It is generally a good practice to hide test code from
-the code you ship to production. With Erlang.mk, you can
-do this thanks to the <code>TEST</code> macro. It is only defined
-when running tests:</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: #000080">-ifdef</span></span>(<span style="color: #009900">TEST</span>)<span style="color: #990000">.</span>
-
-<span style="font-style: italic"><span style="color: #9A1900">%% Insert tests here.</span></span>
-
-<span style="font-weight: bold"><span style="color: #000080">-endif</span></span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Be careful, however, if you include the EUnit header file,
-as it also defines the <code>TEST</code> macro. Make sure to only include
-it inside an <code>ifdef</code> block, otherwise tests will always be
-compiled.</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: #000080">-ifdef</span></span>(<span style="color: #009900">TEST</span>)<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000080">-include_lib</span></span>(<span style="color: #990000">\</span><span style="color: #FF0000">"eunit/include/eunit.hrl\").</span>
-
-<span style="color: #FF0000">%% Insert tests here.</span>
-
-<span style="color: #FF0000">-endif.</span></tt></pre></div></div>
-<div class="paragraph"><p>Erlang.mk will automatically recompile your code when you
-perform a normal build after running tests, and vice versa.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_configuration">Configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>EUNIT_OPTS</code> variable allows you to specify additional
-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"></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"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_usage">Usage</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To run all tests (including EUnit):</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 tests</tt></pre></div></div>
-<div class="paragraph"><p>To run all tests and static checks (including EUnit):</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 check</tt></pre></div></div>
-<div class="paragraph"><p>You can also run EUnit separately:</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 eunit</tt></pre></div></div>
-<div class="paragraph"><p>EUnit will be quiet by default, only outputting errors.
-You can easily make it verbose for a single invocation:</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 eunit <span style="color: #009900">EUNIT_OPTS</span><span style="color: #990000">=</span>verbose</tt></pre></div></div>
-<div class="paragraph"><p>Erlang.mk allows you to run all tests from a specific
-module, or a specific test case from that module, using
-the variable <code>t</code>.</p></div>
-<div class="paragraph"><p>For example, to run all tests from the <code>cow_http_hd</code>
-module (instead of all tests from the entire project),
-one could 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>$ make eunit <span style="color: #009900">t</span><span style="color: #990000">=</span>cow_http_hd</tt></pre></div></div>
-<div class="paragraph"><p>Similarly, to run a specific test 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>$ make eunit <span style="color: #009900">t</span><span style="color: #990000">=</span>cow_http_hd<span style="color: #990000">:</span>parse_accept_test_</tt></pre></div></div>
-<div class="paragraph"><p>To do the same against a multi-application repository,
-you can use the <code>-C</code> option:</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 -C apps/my_app eunit <span style="color: #009900">t</span><span style="color: #990000">=</span>my_module<span style="color: #990000">:</span>hello_test</tt></pre></div></div>
-<div class="paragraph"><p>Note that this also applies to dependencies. From Cowboy,
-you can run the following 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>$ make -C deps/cowlib eunit <span style="color: #009900">t</span><span style="color: #990000">=</span>cow_http_hd</tt></pre></div></div>
-<div class="paragraph"><p>Finally, <a href="../coverage">code coverage</a> is available,
-but covered in its own chapter.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>EUnit is the tool of choice for unit testing. Erlang.mk +automates a few things on top of EUnit, including the +discovery and running of unit tests.</p></div> +<div class="sect1"> +<h2 id="_writing_tests">Writing tests</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <a href="http://www.erlang.org/doc/apps/eunit/chapter.html">EUnit user guide</a> +is the best place to learn how to write tests. Of note is +that all functions ending with <code>_test</code> or <code>_test_</code> will be +picked up as EUnit test cases.</p></div> +<div class="paragraph"><p>Erlang.mk will automatically pick up tests found in any of +the Erlang modules of your application. It will also pick up +tests located in the <em>$(TEST_DIR)</em> directory, which defaults +to <em>test/</em>.</p></div> +<div class="paragraph"><p>It is generally a good practice to hide test code from +the code you ship to production. With Erlang.mk, you can +do this thanks to the <code>TEST</code> macro. It is only defined +when running tests:</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: #000080">-ifdef</span></span>(<span style="color: #009900">TEST</span>)<span style="color: #990000">.</span> + +<span style="font-style: italic"><span style="color: #9A1900">%% Insert tests here.</span></span> + +<span style="font-weight: bold"><span style="color: #000080">-endif</span></span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Be careful, however, if you include the EUnit header file, +as it also defines the <code>TEST</code> macro. Make sure to only include +it inside an <code>ifdef</code> block, otherwise tests will always be +compiled.</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: #000080">-ifdef</span></span>(<span style="color: #009900">TEST</span>)<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000080">-include_lib</span></span>(<span style="color: #990000">\</span><span style="color: #FF0000">"eunit/include/eunit.hrl\").</span> + +<span style="color: #FF0000">%% Insert tests here.</span> + +<span style="color: #FF0000">-endif.</span></tt></pre></div></div> +<div class="paragraph"><p>Erlang.mk will automatically recompile your code when you +perform a normal build after running tests, and vice versa.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>EUNIT_OPTS</code> variable allows you to specify additional +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="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> +</div> +<div class="sect1"> +<h2 id="_usage">Usage</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To run all tests (including EUnit):</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 tests</tt></pre></div></div> +<div class="paragraph"><p>To run all tests and static checks (including EUnit):</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 check</tt></pre></div></div> +<div class="paragraph"><p>You can also run EUnit separately:</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 eunit</tt></pre></div></div> +<div class="paragraph"><p>EUnit will be quiet by default, only outputting errors. +You can easily make it verbose for a single invocation:</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 eunit <span style="color: #009900">EUNIT_OPTS</span><span style="color: #990000">=</span>verbose</tt></pre></div></div> +<div class="paragraph"><p>Erlang.mk allows you to run all tests from a specific +module, or a specific test case from that module, using +the variable <code>t</code>.</p></div> +<div class="paragraph"><p>For example, to run all tests from the <code>cow_http_hd</code> +module (instead of all tests from the entire project), +one could 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>$ make eunit <span style="color: #009900">t</span><span style="color: #990000">=</span>cow_http_hd</tt></pre></div></div> +<div class="paragraph"><p>Similarly, to run a specific test 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>$ make eunit <span style="color: #009900">t</span><span style="color: #990000">=</span>cow_http_hd<span style="color: #990000">:</span>parse_accept_test_</tt></pre></div></div> +<div class="paragraph"><p>To do the same against a multi-application repository, +you can use the <code>-C</code> option:</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 -C apps/my_app eunit <span style="color: #009900">t</span><span style="color: #990000">=</span>my_module<span style="color: #990000">:</span>hello_test</tt></pre></div></div> +<div class="paragraph"><p>Note that this also applies to dependencies. From Cowboy, +you can run the following 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>$ make -C deps/cowlib eunit <span style="color: #009900">t</span><span style="color: #990000">=</span>cow_http_hd</tt></pre></div></div> +<div class="paragraph"><p>Finally, <a href="../coverage">code coverage</a> is available, +but covered in its own chapter.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> 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 13d83701..6a901281 100644 --- a/docs/en/erlang.mk/1/guide/external_plugins/index.html +++ b/docs/en/erlang.mk/1/guide/external_plugins/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: External plugins</title> @@ -67,116 +67,163 @@ <h1 class="lined-header"><span>External plugins</span></h1> -<div class="paragraph"><p>It is often convenient to be able to keep the build files
-used by all your projects in one place. Those files could
-be Makefiles, configuration files, templates and more.</p></div>
-<div class="paragraph"><p>Erlang.mk allows you to automatically load plugins from
-dependencies. Plugins can do anything, including defining
-new variables, defining file templates, hooking themselves
-inside the normal Erlang.mk processing or even adding new
-rules.</p></div>
-<div class="paragraph"><p>You can load plugins using one of two methods. You can
-either load all plugins from a dependency, or just one.
-We will also cover conventions about writing external
-plugins.</p></div>
-<div class="sect1">
-<h2 id="_loading_all_plugins_from_a_dependency">Loading all plugins from a dependency</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To load plugins from a dependency, all you need to do is add
-the dependency name to <code>DEP_PLUGINS</code> in addition to the list
-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"></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>
-</div>
-<div class="sect1">
-<h2 id="_loading_one_plugin_from_a_dependency">Loading one plugin from a dependency</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Now that we know how to load all plugins, let’s take a look
-at how to load one specific plugin from a dependency.</p></div>
-<div class="paragraph"><p>To do this, instead of writing only the name of the dependency,
-we will write its name and the path to the plugin file. This
-means that writing <code>DEP_PLUGINS = cowboy</code> is equivalent to
-writing <code>DEP_PLUGINS = cowboy/plugins.mk</code>.</p></div>
-<div class="paragraph"><p>Knowing this, if we were to load the plugin <em>mk/dist.mk</em>
-from Cowboy and no other, we would write the following in
-our Makefile:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_writing_external_plugins">Writing external plugins</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <em>plugins.mk</em> file is a convention. It is meant to load
-all the plugins from the dependency. The code for the plugin
-can be written directly in <em>plugins.mk</em> or be separate.</p></div>
-<div class="paragraph"><p>If you are providing more than one plugin with your repository,
-the recommended way is to create one file per plugin in the
-<em>mk/</em> folder in your repository, and then include those
-individual plugins in <em>plugins.mk</em>.</p></div>
-<div class="paragraph"><p>For example, if you have two plugins <em>mk/dist.mk</em> and
-<em>mk/templates.mk</em>, you could write the following <em>plugins.mk</em>
-file:</p></div>
-<div class="listingblock">
-<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
-in one go if they wish to do so.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_early_stage_plugins">Early-stage plugins</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Plugins declared in <code>DEP_PLUGINS</code> are loaded near the end of Erlang.mk.
-That’s why you have access to all previously initialized variables.
-However, if you want your plugin to add common dependencies to
-your applications, a regular is loaded too late in the process.
-You need to use "Early-stage plugins". They are declared using the
-<code>DEP_EARLY_PLUGINS</code> variable instead. Plugins listed in this variable
-are loaded near the beginning of Erlang.mk Otherwise, they work exactly
-the same.</p></div>
-<div class="paragraph"><p>If you only give the name of a dependency, the default file loaded is
-<em>early-plugins.mk</em>. You can specify a filename exactly like you would
-have done it with regular plugins.</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_loading_plugins_local_to_the_application">Loading plugins local to the application</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>If the Erlang.mk plugin lives in the same directory or repository as your
-application or library, then you can load it exactly like an external
-plugin: the dependency name is simply the name of your application or
-library.</p></div>
-<div class="paragraph"><p>For example, the following Makefile loads a plugin in the <em>mk</em>
-subdirectory:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>This also works with early-stage plugins:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Like external plugins, if you do not specify the path to the plugin, it
-defaults to <em>plugins.mk</em> or <em>early-plugins.mk</em>, located at the root of
-your application:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-</div>
-</div>
+<div class="paragraph"><p>It is often convenient to be able to keep the build files +used by all your projects in one place. Those files could +be Makefiles, configuration files, templates and more.</p></div> +<div class="paragraph"><p>Erlang.mk allows you to automatically load plugins from +dependencies. Plugins can do anything, including defining +new variables, defining file templates, hooking themselves +inside the normal Erlang.mk processing or even adding new +rules.</p></div> +<div class="paragraph"><p>You can load plugins using one of two methods. You can +either load all plugins from a dependency, or just one. +We will also cover conventions about writing external +plugins.</p></div> +<div class="sect1"> +<h2 id="_loading_all_plugins_from_a_dependency">Loading all plugins from a dependency</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To load plugins from a dependency, all you need to do is add +the dependency name to <code>DEP_PLUGINS</code> in addition to the list +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="paragraph"><p>This will load the file <em>plugins.mk</em> in the root folder of +the Cowboy repository.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_loading_one_plugin_from_a_dependency">Loading one plugin from a dependency</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Now that we know how to load all plugins, let’s take a look +at how to load one specific plugin from a dependency.</p></div> +<div class="paragraph"><p>To do this, instead of writing only the name of the dependency, +we will write its name and the path to the plugin file. This +means that writing <code>DEP_PLUGINS = cowboy</code> is equivalent to +writing <code>DEP_PLUGINS = cowboy/plugins.mk</code>.</p></div> +<div class="paragraph"><p>Knowing this, if we were to load the plugin <em>mk/dist.mk</em> +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> +</div> +<div class="sect1"> +<h2 id="_writing_external_plugins">Writing external plugins</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <em>plugins.mk</em> file is a convention. It is meant to load +all the plugins from the dependency. The code for the plugin +can be written directly in <em>plugins.mk</em> or be separate.</p></div> +<div class="paragraph"><p>If you are providing more than one plugin with your repository, +the recommended way is to create one file per plugin in the +<em>mk/</em> folder in your repository, and then include those +individual plugins in <em>plugins.mk</em>.</p></div> +<div class="paragraph"><p>For example, if you have two plugins <em>mk/dist.mk</em> and +<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="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 +in one go if they wish to do so.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_early_stage_plugins">Early-stage plugins</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Plugins declared in <code>DEP_PLUGINS</code> are loaded near the end of Erlang.mk. +That’s why you have access to all previously initialized variables. +However, if you want your plugin to add common dependencies to +your applications, a regular is loaded too late in the process. +You need to use "Early-stage plugins". They are declared using the +<code>DEP_EARLY_PLUGINS</code> variable instead. Plugins listed in this variable +are loaded near the beginning of Erlang.mk Otherwise, they work exactly +the same.</p></div> +<div class="paragraph"><p>If you only give the name of a dependency, the default file loaded is +<em>early-plugins.mk</em>. You can specify a filename exactly like you would +have done it with regular plugins.</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-style: italic"><span style="color: #9A1900"># In your application's Makefile</span></span> +<span style="color: #009900">BUILD_DEPS =</span> common_deps +<span style="color: #009900">DEP_EARLY_PLUGINS =</span> common_deps</tt></pre></div></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-style: italic"><span style="color: #9A1900"># In the plugin's early-plugins.mk</span></span> +DEPS <span style="color: #990000">+=</span> cowboy +<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> +</div> +<div class="sect1"> +<h2 id="_loading_plugins_local_to_the_application">Loading plugins local to the application</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If the Erlang.mk plugin lives in the same directory or repository as your +application or library, then you can load it exactly like an external +plugin: the dependency name is simply the name of your application or +library.</p></div> +<div class="paragraph"><p>For example, the following Makefile loads a plugin in the <em>mk</em> +subdirectory:</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_PLUGINS =</span> <span style="color: #009900">$(PROJECT)</span>/mk/dist.mk</tt></pre></div></div> +<div class="paragraph"><p>This also works with early-stage plugins:</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_EARLY_PLUGINS =</span> <span style="color: #009900">$(PROJECT)</span>/mk/variables.mk</tt></pre></div></div> +<div class="paragraph"><p>Like external plugins, if you do not specify the path to the plugin, it +defaults to <em>plugins.mk</em> or <em>early-plugins.mk</em>, located at the root of +your 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="font-style: italic"><span style="color: #9A1900"># Loads ./early-plugins.mk</span></span> +<span style="color: #009900">DEP_EARLY_PLUGINS =</span> <span style="color: #009900">$(PROJECT)</span> +<span style="font-style: italic"><span style="color: #9A1900"># Loads ./plugins.mk</span></span> +<span style="color: #009900">DEP_PLUGINS =</span> <span style="color: #009900">$(PROJECT)</span></tt></pre></div></div> +</div> +</div> + + + <nav style="margin:1em 0"> 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 452edb39..694b0c58 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 @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: List of plugins</title> @@ -67,93 +67,96 @@ <h1 class="lined-header"><span>List of plugins</span></h1> -<div class="paragraph"><p>This is a non-exhaustive list of Erlang.mk plugins, sorted
-alphabetically.</p></div>
-<div class="sect1">
-<h2 id="_efene_mk">efene.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An <a href="https://github.com/ninenines/efene.mk">Efene plugin</a> for Erlang.mk.
-<a href="http://efene.org/">Efene</a> is an alternative language for the BEAM.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_elixir_mk">elixir.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An <a href="https://github.com/botsunit/elixir.mk">Elixir plugin</a> for
-Erlang.mk. <a href="http://elixir-lang.org/">Elixir</a> is an alternative
-language for the BEAM.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_elvis_mk">elvis.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An <a href="https://github.com/inaka/elvis.mk">Elvis plugin</a> for Erlang.mk.
-Elvis is an <a href="https://github.com/inaka/elvis">Erlang style reviewer</a>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_geas">geas</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="https://github.com/crownedgrouse/geas">Geas</a> gives aggregated
-information on a project and its dependencies, and is available
-as an Erlang.mk plugin.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_hexer_mk">hexer.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An <a href="https://github.com/inaka/hexer.mk">Hex plugin</a> for Erlang.mk
-using the <code>hexer</code> tool.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_hexpm_mk">hexpm.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Another <a href="https://github.com/botsunit/hexpm.mk">Hex plugin</a> for
-Erlang.mk, with support for Hex dependency operators.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_jorel">jorel</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="https://github.com/emedia-project/jorel">Jorel</a> is Just anOther RELease
-assembler for Erlang/OTP, and is available as an Erlang.mk plugin.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_lfe_mk">lfe.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An <a href="https://github.com/ninenines/lfe.mk">LFE plugin</a> for Erlang.mk.
-LFE, or <a href="http://lfe.io/">Lisp Flavoured Erlang</a>, is an alternative
-language for the BEAM.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_mix_mk">mix.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A <a href="https://github.com/botsunit/mix.mk">Mix plugin</a> for Erlang.mk,
-to generate a compatible configuration file for
-<a href="http://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html">Mix</a>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_reload_mk">reload.mk</h2>
-<div class="sectionbody">
-<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>
+<div class="paragraph"><p>This is a non-exhaustive list of Erlang.mk plugins, sorted +alphabetically.</p></div> +<div class="sect1"> +<h2 id="_efene_mk">efene.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An <a href="https://github.com/ninenines/efene.mk">Efene plugin</a> for Erlang.mk. +<a href="http://efene.org/">Efene</a> is an alternative language for the BEAM.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_elixir_mk">elixir.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An <a href="https://github.com/botsunit/elixir.mk">Elixir plugin</a> for +Erlang.mk. <a href="http://elixir-lang.org/">Elixir</a> is an alternative +language for the BEAM.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_elvis_mk">elvis.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An <a href="https://github.com/inaka/elvis.mk">Elvis plugin</a> for Erlang.mk. +Elvis is an <a href="https://github.com/inaka/elvis">Erlang style reviewer</a>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_geas">geas</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="https://github.com/crownedgrouse/geas">Geas</a> gives aggregated +information on a project and its dependencies, and is available +as an Erlang.mk plugin.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_hexer_mk">hexer.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An <a href="https://github.com/inaka/hexer.mk">Hex plugin</a> for Erlang.mk +using the <code>hexer</code> tool.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_hexpm_mk">hexpm.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Another <a href="https://github.com/botsunit/hexpm.mk">Hex plugin</a> for +Erlang.mk, with support for Hex dependency operators.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_jorel">jorel</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="https://github.com/emedia-project/jorel">Jorel</a> is Just anOther RELease +assembler for Erlang/OTP, and is available as an Erlang.mk plugin.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_lfe_mk">lfe.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An <a href="https://github.com/ninenines/lfe.mk">LFE plugin</a> for Erlang.mk. +LFE, or <a href="http://lfe.io/">Lisp Flavoured Erlang</a>, is an alternative +language for the BEAM.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_mix_mk">mix.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A <a href="https://github.com/botsunit/mix.mk">Mix plugin</a> for Erlang.mk, +to generate a compatible configuration file for +<a href="http://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html">Mix</a>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_reload_mk">reload.mk</h2> +<div class="sectionbody"> +<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> + + + <nav style="margin:1em 0"> 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 2652c05d..dc20db0c 100644 --- a/docs/en/erlang.mk/1/guide/getting_started/index.html +++ b/docs/en/erlang.mk/1/guide/getting_started/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Getting started</title> @@ -67,364 +67,371 @@ <h1 class="lined-header"><span>Getting started</span></h1> -<div class="paragraph"><p>This chapter explains how to get started using Erlang.mk.</p></div>
-<div class="sect1">
-<h2 id="_creating_a_folder_for_your_project">Creating a folder for your project</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The first step is always to create a new folder that will
-contain your project.</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>$ mkdir hello_joe
-$ cd hello_joe</tt></pre></div></div>
-<div class="paragraph"><p>Most people tend to put all their projects side by side in
-a common folder. We recommend keeping an organization similar
-to your remote repositories. For example, for GitHub users,
-put all your projects in a common folder with the same name
-as your username. For example <em>$HOME/ninenines/cowboy</em> for
-the Cowboy project.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_downloading_erlang_mk">Downloading Erlang.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>At the time of writing, Erlang.mk is unlikely to be present
-in your Erlang distribution, or even in your OS packages.</p></div>
-<div class="paragraph"><p>The next step is therefore to download 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>$ 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 -O 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>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>
-<div class="sect1">
-<h2 id="_getting_started_with_otp_applications">Getting started with OTP applications</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An OTP application is an Erlang application that has a supervision
-tree. In other words, it will always have processes running.</p></div>
-<div class="paragraph"><p>This kind of project can be automatically generated by Erlang.mk.
-All you need to do is use the <code>bootstrap</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>$ make -f erlang<span style="color: #990000">.</span>mk bootstrap</tt></pre></div></div>
-<div class="paragraph"><p>Something similar to the following snippet will then appear
-on your screen:</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>git clone https<span style="color: #990000">:</span>//github<span style="color: #990000">.</span>com/ninenines/erlang<span style="color: #990000">.</span>mk <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build
-Cloning into <span style="color: #FF0000">'.erlang.mk.build'</span><span style="color: #990000">...</span>
-remote<span style="color: #990000">:</span> Counting objects<span style="color: #990000">:</span> <span style="color: #993399">4035</span><span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-remote<span style="color: #990000">:</span> Compressing objects<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">12</span><span style="color: #990000">/</span><span style="color: #993399">12</span><span style="color: #990000">),</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-remote<span style="color: #990000">:</span> Total <span style="color: #993399">4035</span> <span style="color: #990000">(</span>delta <span style="color: #993399">8</span><span style="color: #990000">),</span> reused <span style="color: #993399">4</span> <span style="color: #990000">(</span>delta <span style="color: #993399">4</span><span style="color: #990000">),</span> pack-reused <span style="color: #993399">4019</span>
-Receiving objects<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">4035</span><span style="color: #990000">/</span><span style="color: #993399">4035</span><span style="color: #990000">),</span> <span style="color: #993399">1.10</span> MiB <span style="color: #990000">|</span> <span style="color: #993399">784.00</span> KiB/s<span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-Resolving deltas<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">2442</span><span style="color: #990000">/</span><span style="color: #993399">2442</span><span style="color: #990000">),</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-Checking connectivity<span style="color: #990000">...</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">[</span> -f build<span style="color: #990000">.</span>config <span style="color: #990000">];</span> <span style="font-weight: bold"><span style="color: #0000FF">then</span></span> cp build<span style="color: #990000">.</span>config <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build<span style="color: #990000">;</span> <span style="font-weight: bold"><span style="color: #0000FF">fi</span></span>
-cd <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build <span style="color: #990000">&&</span> make
-make<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]:</span> Entering directory <span style="color: #FF0000">'/home/essen/tmp/hello_joe/.erlang.mk.build'</span>
-awk <span style="color: #FF0000">'FNR==1 && NR!=1{print ""}1'</span> core/core<span style="color: #990000">.</span>mk index<span style="color: #990000">/*.</span>mk core/index<span style="color: #990000">.</span>mk core/deps<span style="color: #990000">.</span>mk plugins/protobuffs<span style="color: #990000">.</span>mk core/erlc<span style="color: #990000">.</span>mk core/docs<span style="color: #990000">.</span>mk core/test<span style="color: #990000">.</span>mk plugins/asciidoc<span style="color: #990000">.</span>mk plugins/bootstrap<span style="color: #990000">.</span>mk plugins/c_src<span style="color: #990000">.</span>mk plugins/ci<span style="color: #990000">.</span>mk plugins/ct<span style="color: #990000">.</span>mk plugins/dialyzer<span style="color: #990000">.</span>mk plugins/edoc<span style="color: #990000">.</span>mk plugins/elvis<span style="color: #990000">.</span>mk plugins/erlydtl<span style="color: #990000">.</span>mk plugins/escript<span style="color: #990000">.</span>mk plugins/eunit<span style="color: #990000">.</span>mk plugins/relx<span style="color: #990000">.</span>mk plugins/shell<span style="color: #990000">.</span>mk plugins/triq<span style="color: #990000">.</span>mk plugins/xref<span style="color: #990000">.</span>mk plugins/cover<span style="color: #990000">.</span>mk <span style="color: #990000">\</span>
- <span style="color: #990000">|</span> sed <span style="color: #FF0000">'s/^ERLANG_MK_VERSION = .*/ERLANG_MK_VERSION = 1.2.0-642-gccd2b9f/'</span> <span style="color: #990000">></span> erlang<span style="color: #990000">.</span>mk
-make<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]:</span> Leaving directory <span style="color: #FF0000">'/home/essen/tmp/hello_joe/.erlang.mk.build'</span>
-cp <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build/erlang<span style="color: #990000">.</span>mk <span style="color: #990000">.</span>/erlang<span style="color: #990000">.</span>mk
-rm -rf <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build</tt></pre></div></div>
-<div class="paragraph"><p>This is Erlang.mk bootstrapping itself. Indeed, the file you
-initially downloaded contains nothing more than the code needed
-to bootstrap. This operation is done only once. Consult the
-<a href="../updating">Updating Erlang.mk</a> chapter for more
-information.</p></div>
-<div class="paragraph"><p>Of course, the generated project can now be compiled:</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</tt></pre></div></div>
-<div class="paragraph"><p>Cheers!</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_getting_started_with_otp_libraries">Getting started with OTP libraries</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An OTP library is an Erlang application that has no supervision
-tree. In other words, it is nothing but modules.</p></div>
-<div class="paragraph"><p>This kind of project can also be generated by Erlang.mk, using
-the <code>bootstrap-lib</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>$ make -f erlang<span style="color: #990000">.</span>mk bootstrap-lib</tt></pre></div></div>
-<div class="paragraph"><p>Erlang.mk will once again bootstrap itself and generate all
-the files for your project. You can now compile 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>$ make</tt></pre></div></div>
-<div class="paragraph"><p>Enjoy!</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_getting_started_with_otp_releases">Getting started with OTP releases</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An OTP release is the combination of the Erlang RunTime System (ERTS)
-along with all the libraries and files that your node will need
-to run. It is entirely self contained, and can often be sent as-is
-to your production system and run without any extra setup.</p></div>
-<div class="paragraph"><p>Erlang.mk can of course bootstrap your project to generate releases.
-You can use the <code>bootstrap-rel</code> target for this purpose:</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 bootstrap-rel</tt></pre></div></div>
-<div class="paragraph"><p>This target can be combined with <code>bootstrap</code> or <code>bootstrap-lib</code> to
-create a project that will build a 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>$ make -f erlang<span style="color: #990000">.</span>mk bootstrap-lib bootstrap-rel</tt></pre></div></div>
-<div class="paragraph"><p>It is often very useful to keep the top-level project for
-commands useful during operations, and put the components
-of the system in separate applications that you will then
-depend on. Consult the <a href="../deps">Packages and dependencies</a>
-chapter for more information.</p></div>
-<div class="paragraph"><p>When you run <code>make</code> from now on, Erlang.mk will compile your
-project and build 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>$ make
- APP hello_joe<span style="color: #990000">.</span>app<span style="color: #990000">.</span>src
- GEN distclean-relx-rel
- GEN /home/essen/tmp/hello_joe/relx
-<span style="color: #990000">===></span> Starting relx build process <span style="color: #990000">...</span>
-<span style="color: #990000">===></span> Resolving OTP Applications from directories<span style="color: #990000">:</span>
- /home/essen/tmp/hello_joe/ebin
- /usr/lib/erlang/lib
- /home/essen/tmp/hello_joe/deps
-<span style="color: #990000">===></span> Resolved hello_joe_release-<span style="color: #993399">1</span>
-<span style="color: #990000">===></span> Including Erts from /usr/lib/erlang
-<span style="color: #990000">===></span> release successfully created<span style="color: #990000">!</span></tt></pre></div></div>
-<div class="paragraph"><p>The first time you run this command, Erlang.mk will download
-<em>relx</em>, the release building tool. So don’t worry if you see
-more output than above.</p></div>
-<div class="paragraph"><p>If building the release is slow, no need to upgrade your
-hardware just yet. Just consult the <a href="../relx">Releases</a>
-chapter for various tips to speed up build time during
-development.</p></div>
-<div class="paragraph"><p>You can start the release using the <em>./_rel/hello_joe_release/bin/hello_joe_release</em>
-script, or simply run <code>make run</code>. The latter will also compile
-your project and build the release if it wasn’t already:</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 run
- APP hello_joe<span style="color: #990000">.</span>app<span style="color: #990000">.</span>src
- GEN distclean-relx-rel
-<span style="color: #990000">===></span> Starting relx build process <span style="color: #990000">...</span>
-<span style="color: #990000">===></span> Resolving OTP Applications from directories<span style="color: #990000">:</span>
- /home/essen/tmp/hello_joe/ebin
- /usr/lib/erlang/lib
- /home/essen/tmp/hello_joe/deps
-<span style="color: #990000">===></span> Resolved hello_joe_release-<span style="color: #993399">1</span>
-<span style="color: #990000">===></span> Including Erts from /usr/lib/erlang
-<span style="color: #990000">===></span> release successfully created<span style="color: #990000">!</span>
-Exec<span style="color: #990000">:</span> /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/erts-<span style="color: #993399">7.0</span>/bin/erlexec -boot /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/releases<span style="color: #990000">/</span><span style="color: #993399">1</span>/hello_joe_release -boot_var ERTS_LIB_DIR /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/erts-<span style="color: #993399">7.0</span><span style="color: #990000">/..</span>/lib -env ERL_LIBS /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/releases<span style="color: #990000">/</span><span style="color: #993399">1</span>/lib -config /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/releases<span style="color: #990000">/</span><span style="color: #993399">1</span>/sys<span style="color: #990000">.</span>config -args_file /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/releases<span style="color: #990000">/</span><span style="color: #993399">1</span>/vm<span style="color: #990000">.</span>args -- console
-Root<span style="color: #990000">:</span> /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release
-/home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release
-heart_beat_kill_pid <span style="color: #990000">=</span> <span style="color: #993399">16389</span>
-Erlang/OTP <span style="color: #993399">18</span> <span style="color: #990000">[</span>erts-<span style="color: #993399">7.0</span><span style="color: #990000">]</span> <span style="color: #990000">[</span><span style="font-weight: bold"><span style="color: #0000FF">source</span></span><span style="color: #990000">]</span> <span style="color: #990000">[</span><span style="color: #993399">64</span>-bit<span style="color: #990000">]</span> <span style="color: #990000">[</span>smp<span style="color: #990000">:</span><span style="color: #993399">4</span><span style="color: #990000">:</span><span style="color: #993399">4</span><span style="color: #990000">]</span> <span style="color: #990000">[</span>async-threads<span style="color: #990000">:</span><span style="color: #993399">10</span><span style="color: #990000">]</span> <span style="color: #990000">[</span>hipe<span style="color: #990000">]</span> <span style="color: #990000">[</span>kernel-poll<span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #0000FF">false</span></span><span style="color: #990000">]</span>
-
-Eshell V7<span style="color: #990000">.</span><span style="color: #993399">0</span> <span style="color: #990000">(</span>abort with <span style="color: #990000">^</span>G<span style="color: #990000">)</span>
-<span style="color: #990000">(</span>hello_joe@<span style="color: #993399">127.0</span><span style="color: #990000">.</span><span style="color: #993399">0.1</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>Simple as that!</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_getting_started_from_scratch">Getting started from scratch</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>If you already have an application, or you want to have full
-control over what files will be created, you can setup Erlang.mk
-manually.</p></div>
-<div class="paragraph"><p>Erlang.mk is very easy to setup: all that you need to do is to
-create a folder, put Erlang.mk in it, and write a one line
-Makefile containing:</p></div>
-<div class="listingblock">
-<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
-by Lorenzo Bettini
-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>//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
-using templates.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_using_spaces_instead_of_tabs">Using spaces instead of tabs</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk defaults to tabs when creating files from templates.
-This is in part because of a personal preference, and in part
-because it is much easier to convert tabs to spaces than the
-opposite.</p></div>
-<div class="paragraph"><p>Use the <code>SP</code> variable if you prefer spaces. Set it to the number
-of spaces per indentation level you want.</p></div>
-<div class="paragraph"><p>For example, if you prefer two spaces per indentation level:</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 -f erlang<span style="color: #990000">.</span>mk bootstrap <span style="color: #009900">SP</span><span style="color: #990000">=</span><span style="color: #993399">2</span></tt></pre></div></div>
-<div class="paragraph"><p>When you bootstrap the project initially, the variable automatically
-gets added to the Makefile, so you only need to provide it when
-you get started.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_using_templates">Using templates</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>It is no secret that Erlang’s OTP behaviors tend to have some
-boilerplate. It is rarely an issue of course, except when
-creating new modules. That’s why Erlang.mk not only comes with
-templates for generating projects, but also individual modules!</p></div>
-<div class="paragraph"><p>You can list all available templates with the <code>list-templates</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>$ make list-templates
-Available templates<span style="color: #990000">:</span> cowboy_http cowboy_loop cowboy_rest cowboy_ws gen_fsm gen_server ranch_protocol supervisor</tt></pre></div></div>
-<div class="paragraph"><p>To generate a module, let’s say a <code>gen_server</code>, all you need to
-do is to call <code>make new</code> with the appropriate arguments:</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>gen_server <span style="color: #009900">n</span><span style="color: #990000">=</span>my_server</tt></pre></div></div>
-<div class="paragraph"><p>This will create a module located in <em>src/my_server.erl</em>
-using the <code>gen_server</code> template.</p></div>
-<div class="paragraph"><p>This module is automatically compiled the next time you run
-<code>make</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>$ make
- ERLC my_server<span style="color: #990000">.</span>erl
- APP hello_joe<span style="color: #990000">.</span>app<span style="color: #990000">.</span>src</tt></pre></div></div>
-<div class="paragraph"><p>All that’s left to do is to open it in your favorite editor
-and make it do something!</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_hiding_erlang_mk_from_git">Hiding Erlang.mk from git</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk is a large text file. It can easily take a large part of
-a <code>git diff</code> or a <code>git grep</code> command. You can avoid this by telling
-Git that <em>erlang.mk</em> is a binary file.</p></div>
-<div class="paragraph"><p>Add this to your <em>.gitattributes</em> file. This is a file that you
-can create at the root of your repository:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>erlang.mk -diff</code></pre>
-</div></div>
-<div class="paragraph"><p>The <em>erlang.mk</em> file will still appear in diffs and greps, but
-as a binary file, meaning its contents won’t be shown by default
-anymore.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_getting_help">Getting help</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>During development, if you don’t remember the name of a target,
-you can always run <code>make help</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>$ make <span style="font-weight: bold"><span style="color: #0000FF">help</span></span>
-erlang<span style="color: #990000">.</span>mk <span style="color: #990000">(</span>version <span style="color: #993399">1.2</span><span style="color: #990000">.</span><span style="color: #993399">0</span>-<span style="color: #993399">642</span>-gccd2b9f<span style="color: #990000">)</span> is distributed under the terms of the ISC License<span style="color: #990000">.</span>
-Copyright <span style="color: #990000">(</span>c<span style="color: #990000">)</span> <span style="color: #993399">2013</span>-<span style="color: #993399">2016</span> Loïc Hoguin <span style="color: #990000"><</span>essen@ninenines<span style="color: #990000">.</span>eu<span style="color: #990000">></span>
-
-Usage<span style="color: #990000">:</span> <span style="color: #990000">[</span><span style="color: #009900">V</span><span style="color: #990000">=</span><span style="color: #993399">1</span><span style="color: #990000">]</span> make <span style="color: #990000">[</span>target<span style="color: #990000">]...</span>
-
-Core targets<span style="color: #990000">:</span>
- all Run deps<span style="color: #990000">,</span> app and rel targets <span style="font-weight: bold"><span style="color: #0000FF">in</span></span> that order
- app Compile the project
- deps Fetch dependencies <span style="color: #990000">(</span><span style="font-weight: bold"><span style="color: #0000FF">if</span></span> needed<span style="color: #990000">)</span> and compile them
- search <span style="color: #009900">q</span><span style="color: #990000">=...</span> Search <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> a package <span style="font-weight: bold"><span style="color: #0000FF">in</span></span> the built-in index
- rel Build a release <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project<span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> applicable
- docs Build the documentation <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project
- install-docs Install the man pages <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project
- check Compile and run all tests and analysis <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project
- tests Run the tests <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project
- clean Delete temporary and output files from most targets
- distclean Delete all temporary and output files
- <span style="font-weight: bold"><span style="color: #0000FF">help</span></span> Display this <span style="font-weight: bold"><span style="color: #0000FF">help</span></span> and <span style="font-weight: bold"><span style="color: #0000FF">exit</span></span>
- erlang-mk Update erlang<span style="color: #990000">.</span>mk to the latest version
-
-Bootstrap targets<span style="color: #990000">:</span>
- bootstrap Generate a skeleton of an OTP application
- bootstrap-lib Generate a skeleton of an OTP library
- bootstrap-rel Generate the files needed to build a release
- new <span style="color: #009900">t</span><span style="color: #990000">=</span>TPL <span style="color: #009900">n</span><span style="color: #990000">=</span>NAME Generate a module NAME based on the template TPL
- list-templates List available templates
-<span style="color: #990000">...</span></tt></pre></div></div>
-<div class="paragraph"><p>This guide should provide any other answer. If not, please
-open a ticket on <a href="https://github.com/ninenines/erlang.mk/issues">the official repository</a>
-and we will work on improving the guide.</p></div>
-<div class="paragraph"><p>Commercial support is available through Nine Nines. Please contact
-Loïc Hoguin by sending an email to <a href="mailto:[email protected]">[email protected]</a>.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter explains how to get started using Erlang.mk.</p></div> +<div class="sect1"> +<h2 id="_creating_a_folder_for_your_project">Creating a folder for your project</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The first step is always to create a new folder that will +contain your project.</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>$ mkdir hello_joe +$ cd hello_joe</tt></pre></div></div> +<div class="paragraph"><p>Most people tend to put all their projects side by side in +a common folder. We recommend keeping an organization similar +to your remote repositories. For example, for GitHub users, +put all your projects in a common folder with the same name +as your username. For example <em>$HOME/ninenines/cowboy</em> for +the Cowboy project.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_downloading_erlang_mk">Downloading Erlang.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>At the time of writing, Erlang.mk is unlikely to be present +in your Erlang distribution, or even in your OS packages.</p></div> +<div class="paragraph"><p>The next step is therefore to download 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>$ 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 -O 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>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> +<div class="sect1"> +<h2 id="_getting_started_with_otp_applications">Getting started with OTP applications</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An OTP application is an Erlang application that has a supervision +tree. In other words, it will always have processes running.</p></div> +<div class="paragraph"><p>This kind of project can be automatically generated by Erlang.mk. +All you need to do is use the <code>bootstrap</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>$ make -f erlang<span style="color: #990000">.</span>mk bootstrap</tt></pre></div></div> +<div class="paragraph"><p>Something similar to the following snippet will then appear +on your screen:</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>git clone https<span style="color: #990000">:</span>//github<span style="color: #990000">.</span>com/ninenines/erlang<span style="color: #990000">.</span>mk <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build +Cloning into <span style="color: #FF0000">'.erlang.mk.build'</span><span style="color: #990000">...</span> +remote<span style="color: #990000">:</span> Counting objects<span style="color: #990000">:</span> <span style="color: #993399">4035</span><span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +remote<span style="color: #990000">:</span> Compressing objects<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">12</span><span style="color: #990000">/</span><span style="color: #993399">12</span><span style="color: #990000">),</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +remote<span style="color: #990000">:</span> Total <span style="color: #993399">4035</span> <span style="color: #990000">(</span>delta <span style="color: #993399">8</span><span style="color: #990000">),</span> reused <span style="color: #993399">4</span> <span style="color: #990000">(</span>delta <span style="color: #993399">4</span><span style="color: #990000">),</span> pack-reused <span style="color: #993399">4019</span> +Receiving objects<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">4035</span><span style="color: #990000">/</span><span style="color: #993399">4035</span><span style="color: #990000">),</span> <span style="color: #993399">1.10</span> MiB <span style="color: #990000">|</span> <span style="color: #993399">784.00</span> KiB/s<span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +Resolving deltas<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">2442</span><span style="color: #990000">/</span><span style="color: #993399">2442</span><span style="color: #990000">),</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +Checking connectivity<span style="color: #990000">...</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">[</span> -f build<span style="color: #990000">.</span>config <span style="color: #990000">];</span> <span style="font-weight: bold"><span style="color: #0000FF">then</span></span> cp build<span style="color: #990000">.</span>config <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build<span style="color: #990000">;</span> <span style="font-weight: bold"><span style="color: #0000FF">fi</span></span> +cd <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build <span style="color: #990000">&&</span> make +make<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]:</span> Entering directory <span style="color: #FF0000">'/home/essen/tmp/hello_joe/.erlang.mk.build'</span> +awk <span style="color: #FF0000">'FNR==1 && NR!=1{print ""}1'</span> core/core<span style="color: #990000">.</span>mk index<span style="color: #990000">/*.</span>mk core/index<span style="color: #990000">.</span>mk core/deps<span style="color: #990000">.</span>mk plugins/protobuffs<span style="color: #990000">.</span>mk core/erlc<span style="color: #990000">.</span>mk core/docs<span style="color: #990000">.</span>mk core/test<span style="color: #990000">.</span>mk plugins/asciidoc<span style="color: #990000">.</span>mk plugins/bootstrap<span style="color: #990000">.</span>mk plugins/c_src<span style="color: #990000">.</span>mk plugins/ci<span style="color: #990000">.</span>mk plugins/ct<span style="color: #990000">.</span>mk plugins/dialyzer<span style="color: #990000">.</span>mk plugins/edoc<span style="color: #990000">.</span>mk plugins/elvis<span style="color: #990000">.</span>mk plugins/erlydtl<span style="color: #990000">.</span>mk plugins/escript<span style="color: #990000">.</span>mk plugins/eunit<span style="color: #990000">.</span>mk plugins/relx<span style="color: #990000">.</span>mk plugins/shell<span style="color: #990000">.</span>mk plugins/triq<span style="color: #990000">.</span>mk plugins/xref<span style="color: #990000">.</span>mk plugins/cover<span style="color: #990000">.</span>mk <span style="color: #990000">\</span> + <span style="color: #990000">|</span> sed <span style="color: #FF0000">'s/^ERLANG_MK_VERSION = .*/ERLANG_MK_VERSION = 1.2.0-642-gccd2b9f/'</span> <span style="color: #990000">></span> erlang<span style="color: #990000">.</span>mk +make<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]:</span> Leaving directory <span style="color: #FF0000">'/home/essen/tmp/hello_joe/.erlang.mk.build'</span> +cp <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build/erlang<span style="color: #990000">.</span>mk <span style="color: #990000">.</span>/erlang<span style="color: #990000">.</span>mk +rm -rf <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build</tt></pre></div></div> +<div class="paragraph"><p>This is Erlang.mk bootstrapping itself. Indeed, the file you +initially downloaded contains nothing more than the code needed +to bootstrap. This operation is done only once. Consult the +<a href="../updating">Updating Erlang.mk</a> chapter for more +information.</p></div> +<div class="paragraph"><p>Of course, the generated project can now be compiled:</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</tt></pre></div></div> +<div class="paragraph"><p>Cheers!</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_getting_started_with_otp_libraries">Getting started with OTP libraries</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An OTP library is an Erlang application that has no supervision +tree. In other words, it is nothing but modules.</p></div> +<div class="paragraph"><p>This kind of project can also be generated by Erlang.mk, using +the <code>bootstrap-lib</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>$ make -f erlang<span style="color: #990000">.</span>mk bootstrap-lib</tt></pre></div></div> +<div class="paragraph"><p>Erlang.mk will once again bootstrap itself and generate all +the files for your project. You can now compile 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>$ make</tt></pre></div></div> +<div class="paragraph"><p>Enjoy!</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_getting_started_with_otp_releases">Getting started with OTP releases</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An OTP release is the combination of the Erlang RunTime System (ERTS) +along with all the libraries and files that your node will need +to run. It is entirely self contained, and can often be sent as-is +to your production system and run without any extra setup.</p></div> +<div class="paragraph"><p>Erlang.mk can of course bootstrap your project to generate releases. +You can use the <code>bootstrap-rel</code> target for this purpose:</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 bootstrap-rel</tt></pre></div></div> +<div class="paragraph"><p>This target can be combined with <code>bootstrap</code> or <code>bootstrap-lib</code> to +create a project that will build a 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>$ make -f erlang<span style="color: #990000">.</span>mk bootstrap-lib bootstrap-rel</tt></pre></div></div> +<div class="paragraph"><p>It is often very useful to keep the top-level project for +commands useful during operations, and put the components +of the system in separate applications that you will then +depend on. Consult the <a href="../deps">Packages and dependencies</a> +chapter for more information.</p></div> +<div class="paragraph"><p>When you run <code>make</code> from now on, Erlang.mk will compile your +project and build 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>$ make + APP hello_joe<span style="color: #990000">.</span>app<span style="color: #990000">.</span>src + GEN distclean-relx-rel + GEN /home/essen/tmp/hello_joe/relx +<span style="color: #990000">===></span> Starting relx build process <span style="color: #990000">...</span> +<span style="color: #990000">===></span> Resolving OTP Applications from directories<span style="color: #990000">:</span> + /home/essen/tmp/hello_joe/ebin + /usr/lib/erlang/lib + /home/essen/tmp/hello_joe/deps +<span style="color: #990000">===></span> Resolved hello_joe_release-<span style="color: #993399">1</span> +<span style="color: #990000">===></span> Including Erts from /usr/lib/erlang +<span style="color: #990000">===></span> release successfully created<span style="color: #990000">!</span></tt></pre></div></div> +<div class="paragraph"><p>The first time you run this command, Erlang.mk will download +<em>relx</em>, the release building tool. So don’t worry if you see +more output than above.</p></div> +<div class="paragraph"><p>If building the release is slow, no need to upgrade your +hardware just yet. Just consult the <a href="../relx">Releases</a> +chapter for various tips to speed up build time during +development.</p></div> +<div class="paragraph"><p>You can start the release using the <em>./_rel/hello_joe_release/bin/hello_joe_release</em> +script, or simply run <code>make run</code>. The latter will also compile +your project and build the release if it wasn’t already:</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 run + APP hello_joe<span style="color: #990000">.</span>app<span style="color: #990000">.</span>src + GEN distclean-relx-rel +<span style="color: #990000">===></span> Starting relx build process <span style="color: #990000">...</span> +<span style="color: #990000">===></span> Resolving OTP Applications from directories<span style="color: #990000">:</span> + /home/essen/tmp/hello_joe/ebin + /usr/lib/erlang/lib + /home/essen/tmp/hello_joe/deps +<span style="color: #990000">===></span> Resolved hello_joe_release-<span style="color: #993399">1</span> +<span style="color: #990000">===></span> Including Erts from /usr/lib/erlang +<span style="color: #990000">===></span> release successfully created<span style="color: #990000">!</span> +Exec<span style="color: #990000">:</span> /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/erts-<span style="color: #993399">7.0</span>/bin/erlexec -boot /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/releases<span style="color: #990000">/</span><span style="color: #993399">1</span>/hello_joe_release -boot_var ERTS_LIB_DIR /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/erts-<span style="color: #993399">7.0</span><span style="color: #990000">/..</span>/lib -env ERL_LIBS /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/releases<span style="color: #990000">/</span><span style="color: #993399">1</span>/lib -config /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/releases<span style="color: #990000">/</span><span style="color: #993399">1</span>/sys<span style="color: #990000">.</span>config -args_file /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release/releases<span style="color: #990000">/</span><span style="color: #993399">1</span>/vm<span style="color: #990000">.</span>args -- console +Root<span style="color: #990000">:</span> /home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release +/home/essen/tmp/hello_joe<span style="color: #990000">/</span>_rel/hello_joe_release +heart_beat_kill_pid <span style="color: #990000">=</span> <span style="color: #993399">16389</span> +Erlang/OTP <span style="color: #993399">18</span> <span style="color: #990000">[</span>erts-<span style="color: #993399">7.0</span><span style="color: #990000">]</span> <span style="color: #990000">[</span><span style="font-weight: bold"><span style="color: #0000FF">source</span></span><span style="color: #990000">]</span> <span style="color: #990000">[</span><span style="color: #993399">64</span>-bit<span style="color: #990000">]</span> <span style="color: #990000">[</span>smp<span style="color: #990000">:</span><span style="color: #993399">4</span><span style="color: #990000">:</span><span style="color: #993399">4</span><span style="color: #990000">]</span> <span style="color: #990000">[</span>async-threads<span style="color: #990000">:</span><span style="color: #993399">10</span><span style="color: #990000">]</span> <span style="color: #990000">[</span>hipe<span style="color: #990000">]</span> <span style="color: #990000">[</span>kernel-poll<span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #0000FF">false</span></span><span style="color: #990000">]</span> + +Eshell V7<span style="color: #990000">.</span><span style="color: #993399">0</span> <span style="color: #990000">(</span>abort with <span style="color: #990000">^</span>G<span style="color: #990000">)</span> +<span style="color: #990000">(</span>hello_joe@<span style="color: #993399">127.0</span><span style="color: #990000">.</span><span style="color: #993399">0.1</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>Simple as that!</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_getting_started_from_scratch">Getting started from scratch</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you already have an application, or you want to have full +control over what files will be created, you can setup Erlang.mk +manually.</p></div> +<div class="paragraph"><p>Erlang.mk is very easy to setup: all that you need to do is to +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="paragraph"><p>For a step by step:</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>$ mkdir hello_joe +$ cd hello_joe +$ 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 +using templates.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_using_spaces_instead_of_tabs">Using spaces instead of tabs</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk defaults to tabs when creating files from templates. +This is in part because of a personal preference, and in part +because it is much easier to convert tabs to spaces than the +opposite.</p></div> +<div class="paragraph"><p>Use the <code>SP</code> variable if you prefer spaces. Set it to the number +of spaces per indentation level you want.</p></div> +<div class="paragraph"><p>For example, if you prefer two spaces per indentation level:</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 -f erlang<span style="color: #990000">.</span>mk bootstrap <span style="color: #009900">SP</span><span style="color: #990000">=</span><span style="color: #993399">2</span></tt></pre></div></div> +<div class="paragraph"><p>When you bootstrap the project initially, the variable automatically +gets added to the Makefile, so you only need to provide it when +you get started.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_using_templates">Using templates</h2> +<div class="sectionbody"> +<div class="paragraph"><p>It is no secret that Erlang’s OTP behaviors tend to have some +boilerplate. It is rarely an issue of course, except when +creating new modules. That’s why Erlang.mk not only comes with +templates for generating projects, but also individual modules!</p></div> +<div class="paragraph"><p>You can list all available templates with the <code>list-templates</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>$ make list-templates +Available templates<span style="color: #990000">:</span> cowboy_http cowboy_loop cowboy_rest cowboy_ws gen_fsm gen_server ranch_protocol supervisor</tt></pre></div></div> +<div class="paragraph"><p>To generate a module, let’s say a <code>gen_server</code>, all you need to +do is to call <code>make new</code> with the appropriate arguments:</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>gen_server <span style="color: #009900">n</span><span style="color: #990000">=</span>my_server</tt></pre></div></div> +<div class="paragraph"><p>This will create a module located in <em>src/my_server.erl</em> +using the <code>gen_server</code> template.</p></div> +<div class="paragraph"><p>This module is automatically compiled the next time you run +<code>make</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>$ make + ERLC my_server<span style="color: #990000">.</span>erl + APP hello_joe<span style="color: #990000">.</span>app<span style="color: #990000">.</span>src</tt></pre></div></div> +<div class="paragraph"><p>All that’s left to do is to open it in your favorite editor +and make it do something!</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_hiding_erlang_mk_from_git">Hiding Erlang.mk from git</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk is a large text file. It can easily take a large part of +a <code>git diff</code> or a <code>git grep</code> command. You can avoid this by telling +Git that <em>erlang.mk</em> is a binary file.</p></div> +<div class="paragraph"><p>Add this to your <em>.gitattributes</em> file. This is a file that you +can create at the root of your repository:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><code>erlang.mk -diff</code></pre> +</div></div> +<div class="paragraph"><p>The <em>erlang.mk</em> file will still appear in diffs and greps, but +as a binary file, meaning its contents won’t be shown by default +anymore.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_getting_help">Getting help</h2> +<div class="sectionbody"> +<div class="paragraph"><p>During development, if you don’t remember the name of a target, +you can always run <code>make help</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>$ make <span style="font-weight: bold"><span style="color: #0000FF">help</span></span> +erlang<span style="color: #990000">.</span>mk <span style="color: #990000">(</span>version <span style="color: #993399">1.2</span><span style="color: #990000">.</span><span style="color: #993399">0</span>-<span style="color: #993399">642</span>-gccd2b9f<span style="color: #990000">)</span> is distributed under the terms of the ISC License<span style="color: #990000">.</span> +Copyright <span style="color: #990000">(</span>c<span style="color: #990000">)</span> <span style="color: #993399">2013</span>-<span style="color: #993399">2016</span> Loïc Hoguin <span style="color: #990000"><</span>essen@ninenines<span style="color: #990000">.</span>eu<span style="color: #990000">></span> + +Usage<span style="color: #990000">:</span> <span style="color: #990000">[</span><span style="color: #009900">V</span><span style="color: #990000">=</span><span style="color: #993399">1</span><span style="color: #990000">]</span> make <span style="color: #990000">[</span>target<span style="color: #990000">]...</span> + +Core targets<span style="color: #990000">:</span> + all Run deps<span style="color: #990000">,</span> app and rel targets <span style="font-weight: bold"><span style="color: #0000FF">in</span></span> that order + app Compile the project + deps Fetch dependencies <span style="color: #990000">(</span><span style="font-weight: bold"><span style="color: #0000FF">if</span></span> needed<span style="color: #990000">)</span> and compile them + search <span style="color: #009900">q</span><span style="color: #990000">=...</span> Search <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> a package <span style="font-weight: bold"><span style="color: #0000FF">in</span></span> the built-in index + rel Build a release <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project<span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> applicable + docs Build the documentation <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project + install-docs Install the man pages <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project + check Compile and run all tests and analysis <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project + tests Run the tests <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> this project + clean Delete temporary and output files from most targets + distclean Delete all temporary and output files + <span style="font-weight: bold"><span style="color: #0000FF">help</span></span> Display this <span style="font-weight: bold"><span style="color: #0000FF">help</span></span> and <span style="font-weight: bold"><span style="color: #0000FF">exit</span></span> + erlang-mk Update erlang<span style="color: #990000">.</span>mk to the latest version + +Bootstrap targets<span style="color: #990000">:</span> + bootstrap Generate a skeleton of an OTP application + bootstrap-lib Generate a skeleton of an OTP library + bootstrap-rel Generate the files needed to build a release + new <span style="color: #009900">t</span><span style="color: #990000">=</span>TPL <span style="color: #009900">n</span><span style="color: #990000">=</span>NAME Generate a module NAME based on the template TPL + list-templates List available templates +<span style="color: #990000">...</span></tt></pre></div></div> +<div class="paragraph"><p>This guide should provide any other answer. If not, please +open a ticket on <a href="https://github.com/ninenines/erlang.mk/issues">the official repository</a> +and we will work on improving the guide.</p></div> +<div class="paragraph"><p>Commercial support is available through Nine Nines. Please contact +Loïc Hoguin by sending an email to <a href="mailto:[email protected]">[email protected]</a>.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/history/index.html b/docs/en/erlang.mk/1/guide/history/index.html index 07482cec..5bad3b62 100644 --- a/docs/en/erlang.mk/1/guide/history/index.html +++ b/docs/en/erlang.mk/1/guide/history/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Short history</title> @@ -67,67 +67,70 @@ <h1 class="lined-header"><span>Short history</span></h1> -<div class="paragraph"><p>This chapter aims to be a brief record of the life of the
-Erlang.mk project.</p></div>
-<div class="sect1">
-<h2 id="_before_erlang_mk">Before Erlang.mk</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk originates from the Cowboy project. Cowboy started
-as a Rebar project and I, Loïc Hoguin, was very happy with it
-for a couple years. Over time however I started getting annoyed
-and frustrated by a number of things, including bad defaults,
-changing defaults and overall slowness.</p></div>
-<div class="paragraph"><p>In particular, at the time I gave up on Rebar, the Cowboy
-test suite was taking about five minutes to run. A quick experiment
-showed I could get much lower times by simply invoking <code>ct_run</code>
-directly. On January 4th, 2013, the Cowboy test suite took less
-than a minute to complete.</p></div>
-<div class="paragraph"><p>Following this success I started removing a little more and,
-on the fateful day of January 5th, 2013, removed the dependency
-on Rebar entirely. Rebar, and in particular the concept of
-dependencies, was, and still is, a pretty strong influence.</p></div>
-<div class="paragraph"><p>Erlang.mk was conceived.</p></div>
-<div class="paragraph"><p>A few months passed and, on May 1st, 2013, the Erlang.mk
-repository was created. Erlang.mk was born.</p></div>
-<div class="paragraph"><p>Little did I know how much it would grow.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_lifetime_of_the_project">Lifetime of the project</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk would eventually become a much larger file able to
-deal with many more projects than just Cowboy. From the birth
-of the project, the biggest force for growth was user contributions,
-because Erlang.mk appealed to a variety of people with different
-needs, needs that Erlang.mk was not fulfilling yet.</p></div>
-<div class="paragraph"><p>The project was split into smaller files focused on a different
-feature each, and a build script was written to build the single
-Erlang.mk file.</p></div>
-<div class="paragraph"><p>A test suite was contributed by a user, and later taken as a basis
-for the current, much more complete test suite. Turns out testing
-a Makefile is pretty straightforward.</p></div>
-<div class="paragraph"><p>A package index was added to solve the problem of discovering
-Erlang projects.</p></div>
-<div class="paragraph"><p>After trying to see if Erlang build tools could cooperate, the
-decision was made to improve compatibility with existing Rebar
-projects by patching Rebar out, using Rebar. This feature, called
-autopatch, proved very successful and made Erlang.mk compatible
-with more than 90% of all Erlang projects.</p></div>
-<div class="paragraph"><p>Erlang.mk documentation was much improved and the Erlang.mk website
-was created in the summer of 2015.</p></div>
-<div class="paragraph"><p>Over the year of 2015, Erlang.mk went from curiosity to a serious
-alternative to other Erlang build tools. The user base increased
-immensely and large projects started using it, including RabbitMQ
-from the 3.6.0 release onward.</p></div>
-<div class="paragraph"><p>A bright future lies ahead.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter aims to be a brief record of the life of the +Erlang.mk project.</p></div> +<div class="sect1"> +<h2 id="_before_erlang_mk">Before Erlang.mk</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk originates from the Cowboy project. Cowboy started +as a Rebar project and I, Loïc Hoguin, was very happy with it +for a couple years. Over time however I started getting annoyed +and frustrated by a number of things, including bad defaults, +changing defaults and overall slowness.</p></div> +<div class="paragraph"><p>In particular, at the time I gave up on Rebar, the Cowboy +test suite was taking about five minutes to run. A quick experiment +showed I could get much lower times by simply invoking <code>ct_run</code> +directly. On January 4th, 2013, the Cowboy test suite took less +than a minute to complete.</p></div> +<div class="paragraph"><p>Following this success I started removing a little more and, +on the fateful day of January 5th, 2013, removed the dependency +on Rebar entirely. Rebar, and in particular the concept of +dependencies, was, and still is, a pretty strong influence.</p></div> +<div class="paragraph"><p>Erlang.mk was conceived.</p></div> +<div class="paragraph"><p>A few months passed and, on May 1st, 2013, the Erlang.mk +repository was created. Erlang.mk was born.</p></div> +<div class="paragraph"><p>Little did I know how much it would grow.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_lifetime_of_the_project">Lifetime of the project</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk would eventually become a much larger file able to +deal with many more projects than just Cowboy. From the birth +of the project, the biggest force for growth was user contributions, +because Erlang.mk appealed to a variety of people with different +needs, needs that Erlang.mk was not fulfilling yet.</p></div> +<div class="paragraph"><p>The project was split into smaller files focused on a different +feature each, and a build script was written to build the single +Erlang.mk file.</p></div> +<div class="paragraph"><p>A test suite was contributed by a user, and later taken as a basis +for the current, much more complete test suite. Turns out testing +a Makefile is pretty straightforward.</p></div> +<div class="paragraph"><p>A package index was added to solve the problem of discovering +Erlang projects.</p></div> +<div class="paragraph"><p>After trying to see if Erlang build tools could cooperate, the +decision was made to improve compatibility with existing Rebar +projects by patching Rebar out, using Rebar. This feature, called +autopatch, proved very successful and made Erlang.mk compatible +with more than 90% of all Erlang projects.</p></div> +<div class="paragraph"><p>Erlang.mk documentation was much improved and the Erlang.mk website +was created in the summer of 2015.</p></div> +<div class="paragraph"><p>Over the year of 2015, Erlang.mk went from curiosity to a serious +alternative to other Erlang build tools. The user base increased +immensely and large projects started using it, including RabbitMQ +from the 3.6.0 release onward.</p></div> +<div class="paragraph"><p>A bright future lies ahead.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/index.html b/docs/en/erlang.mk/1/guide/index.html index 5b8db024..0e1f31d0 100644 --- a/docs/en/erlang.mk/1/guide/index.html +++ b/docs/en/erlang.mk/1/guide/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Erlang.mk User Guide</title> @@ -67,173 +67,178 @@ <h1 class="lined-header"><span>Erlang.mk User Guide</span></h1> -<div class="ulist"><ul>
-<li>
-<p>
-<a href="installation/">Installation</a>
-</p>
-</li>
-<li>
-<p>
-<a href="getting_started/">Getting started</a>
-</p>
-</li>
-<li>
-<p>
-<a href="overview/">Overview</a>
-</p>
-</li>
-<li>
-<p>
-<a href="updating/">Updating Erlang.mk</a>
-</p>
-</li>
-<li>
-<p>
-<a href="limitations/">Limitations</a>
-</p>
-</li>
-</ul></div>
-<div class="sect1">
-<h2 id="code">Code</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="app/">Building</a>
-</p>
-</li>
-<li>
-<p>
-<a href="deps/">Packages and dependencies</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ports/">NIFs and port drivers</a>
-</p>
-</li>
-<li>
-<p>
-<a href="releases/">Releases</a>
-</p>
-</li>
-<li>
-<p>
-<a href="sfx/">Self-extracting releases</a>
-</p>
-</li>
-<li>
-<p>
-<a href="escripts/">Escripts</a>
-</p>
-</li>
-<li>
-<p>
-<a href="compat/">Compatibility with other build tools</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="docs">Documentation</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="asciidoc/">Asciidoc documentation</a>
-</p>
-</li>
-<li>
-<p>
-<a href="edoc/">EDoc comments</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="tests">Tests</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="shell/">Erlang shell</a>
-</p>
-</li>
-<li>
-<p>
-<a href="eunit/">EUnit</a>
-</p>
-</li>
-<li>
-<p>
-<a href="common_test/">Common Test</a>
-</p>
-</li>
-<li>
-<p>
-<a href="coverage/">Code coverage</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ci/">Continuous integration</a>
-</p>
-</li>
-<li>
-<p>
-<a href="dialyzer/">Dialyzer</a>
-</p>
-</li>
-<li>
-<p>
-<a href="xref/">Xref</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="plugins">Third-party plugins</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="external_plugins/">External plugins</a>
-</p>
-</li>
-<li>
-<p>
-<a href="external_plugins_list/">List of plugins</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="about">About Erlang.mk</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="why/">Why erlang.mk?</a>
-</p>
-</li>
-<li>
-<p>
-<a href="history/">Short history</a>
-</p>
-</li>
-<li>
-<p>
-<a href="contributing/">Contributing</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
+<div class="ulist"><ul> +<li> +<p> +<a href="installation/">Installation</a> +</p> +</li> +<li> +<p> +<a href="getting_started/">Getting started</a> +</p> +</li> +<li> +<p> +<a href="overview/">Overview</a> +</p> +</li> +<li> +<p> +<a href="updating/">Updating Erlang.mk</a> +</p> +</li> +<li> +<p> +<a href="limitations/">Limitations</a> +</p> +</li> +</ul></div> +<div class="sect1"> +<h2 id="code">Code</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="app/">Building</a> +</p> +</li> +<li> +<p> +<a href="deps/">Packages and dependencies</a> +</p> +</li> +<li> +<p> +<a href="ports/">NIFs and port drivers</a> +</p> +</li> +<li> +<p> +<a href="releases/">Releases</a> +</p> +</li> +<li> +<p> +<a href="sfx/">Self-extracting releases</a> +</p> +</li> +<li> +<p> +<a href="escripts/">Escripts</a> +</p> +</li> +<li> +<p> +<a href="kerl/">OTP version management</a> +</p> +</li> +<li> +<p> +<a href="compat/">Compatibility with other build tools</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="docs">Documentation</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="asciidoc/">Asciidoc documentation</a> +</p> +</li> +<li> +<p> +<a href="edoc/">EDoc comments</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="tests">Tests</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="shell/">Erlang shell</a> +</p> +</li> +<li> +<p> +<a href="eunit/">EUnit</a> +</p> +</li> +<li> +<p> +<a href="common_test/">Common Test</a> +</p> +</li> +<li> +<p> +<a href="coverage/">Code coverage</a> +</p> +</li> +<li> +<p> +<a href="ci/">Continuous integration</a> +</p> +</li> +<li> +<p> +<a href="dialyzer/">Dialyzer</a> +</p> +</li> +<li> +<p> +<a href="xref/">Xref</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="plugins">Third-party plugins</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="external_plugins/">External plugins</a> +</p> +</li> +<li> +<p> +<a href="external_plugins_list/">List of plugins</a> +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="about">About Erlang.mk</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<a href="why/">Why erlang.mk?</a> +</p> +</li> +<li> +<p> +<a href="history/">Short history</a> +</p> +</li> +<li> +<p> +<a href="contributing/">Contributing</a> +</p> +</li> +</ul></div> +</div> +</div> diff --git a/docs/en/erlang.mk/1/guide/installation/index.html b/docs/en/erlang.mk/1/guide/installation/index.html index c909fec1..806b25e8 100644 --- a/docs/en/erlang.mk/1/guide/installation/index.html +++ b/docs/en/erlang.mk/1/guide/installation/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Installation</title> @@ -67,186 +67,189 @@ <h1 class="lined-header"><span>Installation</span></h1> -<div class="sect1">
-<h2 id="_on_unix">On Unix</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk requires GNU Make to be installed. While it will
-currently work with GNU Make 3.81, support for this version
-is deprecated and will be removed in 2017. We recommend
-GNU Make 4.1 or later.</p></div>
-<div class="paragraph"><p>Git and Erlang/OTP must also be installed.</p></div>
-<div class="paragraph"><p>Some functionality requires that Autoconf 2.59 or later be
-installed, in order to compile Erlang/OTP. Erlang/OTP may
-have further requirements depending on your needs.</p></div>
-<div class="paragraph"><p>Some packages may require additional libraries.</p></div>
-<div class="sect3">
-<h4 id="_linux">Linux</h4>
-<div class="paragraph"><p>The commands to install packages vary between distributions:</p></div>
-<div class="listingblock">
-<div class="title">Arch Linux</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>$ pacman -S erlang git make</tt></pre></div></div>
-</div>
-<div class="sect3">
-<h4 id="_freebsd">FreeBSD</h4>
-<div class="paragraph"><p>FreeBSD comes with binary and source packages:</p></div>
-<div class="listingblock">
-<div class="title">Install binary packages</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>$ pkg install erlang git gmake</tt></pre></div></div>
-<div class="paragraph"><p>On FreeBSD the <code>make</code> command is BSD Make. Use <code>gmake</code> instead.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_os_x_and_macos">OS X and macOS</h4>
-<div class="paragraph"><p>While Apple distributes their own GNU Make, their version is
-very old and plagued with numerous bugs. It is recommended
-to install a more recent version from either Homebrew or
-MacPorts:</p></div>
-<div class="listingblock">
-<div class="title">Homebrew</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>$ brew install erlang git homebrew/dupes/make</tt></pre></div></div>
-<div class="paragraph"><p>Homebrew installs GNU Make as <code>gmake</code>. The <code>make</code> command
-is the one provided by Apple.</p></div>
-<div class="listingblock">
-<div class="title">MacPorts</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>$ sudo port install erlang git gmake</tt></pre></div></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_on_windows">On Windows</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk can be used on Windows inside an MSYS2 environment.
-Cygwin, MSYS (the original) and native Windows (both Batch
-and PowerShell) are currently not supported.</p></div>
-<div class="admonitionblock">
-<table><tr>
-<td class="icon">
-<div class="title">Note</div>
-</td>
-<td class="content">Erlang.mk expects Unix line breaks in most of the files
-(LF instead of CRLF). Make sure to configure your text editor
-adequately.</td>
-</tr></table>
-</div>
-<div class="paragraph"><p>The rest of this section details how to setup Erlang/OTP and
-MSYS2 in order to use Erlang.mk.</p></div>
-<div class="sect3">
-<h4 id="_installing_erlang_otp">Installing Erlang/OTP</h4>
-<div class="paragraph"><p>Erlang.mk requires Erlang/OTP to be installed. The OTP team
-provides binaries of Erlang/OTP for all major and minor releases,
-available from the <a href="http://www.erlang.org/download.html">official download page</a>.
-It is recommended that you use the 64-bit installer unless
-technically impossible. Please follow the instructions from
-the installer to complete the installation.</p></div>
-<div class="paragraph"><p>The OTP team also provides a short guide to
-<a href="http://www.erlang.org/download.html">installing Erlang/OTP on Windows</a>
-if you need additional references.</p></div>
-<div class="paragraph"><p>You can install Erlang/OTP silently using the <code>/S</code> switch
-on the command line:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>C:\Users\essen\Downloads> otp_win64_18.0.exe /S</code></pre>
-</div></div>
-</div>
-<div class="sect3">
-<h4 id="_installing_msys2">Installing MSYS2</h4>
-<div class="paragraph"><p>The only supported environment on Windows is MSYS2. MSYS2 is
-a lightweight Unix-like environment for Windows that comes
-with the Arch Linux package manager, <code>pacman</code>.</p></div>
-<div class="paragraph"><p>The MSYS2 project provides a <a href="http://msys2.github.io">one click installer</a>
-and instructions to set things up post-installation.</p></div>
-<div class="paragraph"><p>It is currently not possible to use the installer silently.
-Thankfully, the MSYS2 project provides an archive that can
-be used in lieu of the installer. The archive however requires
-<em>7zip</em> to decompress it.</p></div>
-<div class="paragraph"><p>First, download the
-<a href="http://sourceforge.net/projects/msys2/files/Base/x86_64/msys2-base-x86_64-20150512.tar.xz/download">MSYS2 base archive</a>
-and extract it under <em>C:\</em>. Assuming you downloaded the
-archive as <em>msys2.tar.xz</em> and put it in <em>C:\</em>, you can
-use the following commands to extract it:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>C:\> 7z x msys2.tar.xz
-C:\> 7z x msys2.tar > NUL</code></pre>
-</div></div>
-<div class="paragraph"><p>Then you can run the two commands needed to perform the
-post-installation setup:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>C:\> C:\msys64\usr\bin\bash -lc "pacman --needed --noconfirm -Sy bash pacman pacman-mirrors msys2-runtime"
-C:\> C:\msys64\usr\bin\bash -lc "pacman --noconfirm -Syu"</code></pre>
-</div></div>
-</div>
-<div class="sect3">
-<h4 id="_installing_the_required_msys2_packages">Installing the required MSYS2 packages</h4>
-<div class="paragraph"><p>After following these instructions, you can install GNU Make,
-Git and any other required softwares. From an MSYS2 shell,
-you can call <code>pacman</code> 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>$ pacman -S git make</tt></pre></div></div>
-<div class="paragraph"><p>You can use <code>pacman -Ss</code> to search packages. For example,
-to find all packages related to GCC:</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>$ pacman -Ss gcc</tt></pre></div></div>
-<div class="paragraph"><p>If you are going to compile C/C++ code, you will need to
-install this package, as Erlang.mk cannot use the normal
-"gcc" package:</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>$ pacman -S mingw-w<span style="color: #993399">64</span>-x86_64-gcc</tt></pre></div></div>
-<div class="paragraph"><p>You can also run commands under the MSYS2 environment from
-the Windows command line or batch files. This command will
-install GNU Make and Git:</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>C:\> C:\msys64\usr\bin\bash -lc "pacman --noconfirm -S git make"</code></pre>
-</div></div>
-<div class="paragraph"><p>You can use similar <code>bash</code> commands if you need to run programs
-inside the MSYS2 environment from a batch file.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_gotchas">Gotchas</h4>
-<div class="paragraph"><p>While most of the basic functionality will just work, there are
-still some issues. Erlang.mk needs to be fixed to pass the
-right paths when running Erlang scripts. We are working on it.
-Erlang.mk is fully tested on both Linux and Windows, but is
-lacking tests in the areas not yet covered by this guide,
-so expect bugs to be fixed as more tests are added.</p></div>
-</div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_on_unix">On Unix</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk requires GNU Make to be installed. While it will +currently work with GNU Make 3.81, support for this version +is deprecated and will be removed in 2017. We recommend +GNU Make 4.1 or later.</p></div> +<div class="paragraph"><p>Git and Erlang/OTP must also be installed.</p></div> +<div class="paragraph"><p>Some functionality requires that Autoconf 2.59 or later be +installed, in order to compile Erlang/OTP. Erlang/OTP may +have further requirements depending on your needs.</p></div> +<div class="paragraph"><p>Some packages may require additional libraries.</p></div> +<div class="sect3"> +<h4 id="_linux">Linux</h4> +<div class="paragraph"><p>The commands to install packages vary between distributions:</p></div> +<div class="listingblock"> +<div class="title">Arch Linux</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>$ pacman -S erlang git make</tt></pre></div></div> +</div> +<div class="sect3"> +<h4 id="_freebsd">FreeBSD</h4> +<div class="paragraph"><p>FreeBSD comes with binary and source packages:</p></div> +<div class="listingblock"> +<div class="title">Install binary packages</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>$ pkg install erlang git gmake</tt></pre></div></div> +<div class="paragraph"><p>On FreeBSD the <code>make</code> command is BSD Make. Use <code>gmake</code> instead.</p></div> +</div> +<div class="sect3"> +<h4 id="_os_x_and_macos">OS X and macOS</h4> +<div class="paragraph"><p>While Apple distributes their own GNU Make, their version is +very old and plagued with numerous bugs. It is recommended +to install a more recent version from either Homebrew or +MacPorts:</p></div> +<div class="listingblock"> +<div class="title">Homebrew</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>$ brew install erlang git homebrew/dupes/make</tt></pre></div></div> +<div class="paragraph"><p>Homebrew installs GNU Make as <code>gmake</code>. The <code>make</code> command +is the one provided by Apple.</p></div> +<div class="listingblock"> +<div class="title">MacPorts</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>$ sudo port install erlang git gmake</tt></pre></div></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_on_windows">On Windows</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk can be used on Windows inside an MSYS2 environment. +Cygwin, MSYS (the original) and native Windows (both Batch +and PowerShell) are currently not supported.</p></div> +<div class="admonitionblock"> +<table><tr> +<td class="icon"> +<div class="title">Note</div> +</td> +<td class="content">Erlang.mk expects Unix line breaks in most of the files +(LF instead of CRLF). Make sure to configure your text editor +adequately.</td> +</tr></table> +</div> +<div class="paragraph"><p>The rest of this section details how to setup Erlang/OTP and +MSYS2 in order to use Erlang.mk.</p></div> +<div class="sect3"> +<h4 id="_installing_erlang_otp">Installing Erlang/OTP</h4> +<div class="paragraph"><p>Erlang.mk requires Erlang/OTP to be installed. The OTP team +provides binaries of Erlang/OTP for all major and minor releases, +available from the <a href="http://www.erlang.org/download.html">official download page</a>. +It is recommended that you use the 64-bit installer unless +technically impossible. Please follow the instructions from +the installer to complete the installation.</p></div> +<div class="paragraph"><p>The OTP team also provides a short guide to +<a href="http://www.erlang.org/download.html">installing Erlang/OTP on Windows</a> +if you need additional references.</p></div> +<div class="paragraph"><p>You can install Erlang/OTP silently using the <code>/S</code> switch +on the command line:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><code>C:\Users\essen\Downloads> otp_win64_18.0.exe /S</code></pre> +</div></div> +</div> +<div class="sect3"> +<h4 id="_installing_msys2">Installing MSYS2</h4> +<div class="paragraph"><p>The only supported environment on Windows is MSYS2. MSYS2 is +a lightweight Unix-like environment for Windows that comes +with the Arch Linux package manager, <code>pacman</code>.</p></div> +<div class="paragraph"><p>The MSYS2 project provides a <a href="http://msys2.github.io">one click installer</a> +and instructions to set things up post-installation.</p></div> +<div class="paragraph"><p>It is currently not possible to use the installer silently. +Thankfully, the MSYS2 project provides an archive that can +be used in lieu of the installer. The archive however requires +<em>7zip</em> to decompress it.</p></div> +<div class="paragraph"><p>First, download the +<a href="http://sourceforge.net/projects/msys2/files/Base/x86_64/msys2-base-x86_64-20150512.tar.xz/download">MSYS2 base archive</a> +and extract it under <em>C:\</em>. Assuming you downloaded the +archive as <em>msys2.tar.xz</em> and put it in <em>C:\</em>, you can +use the following commands to extract it:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><code>C:\> 7z x msys2.tar.xz +C:\> 7z x msys2.tar > NUL</code></pre> +</div></div> +<div class="paragraph"><p>Then you can run the two commands needed to perform the +post-installation setup:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><code>C:\> C:\msys64\usr\bin\bash -lc "pacman --needed --noconfirm -Sy bash pacman pacman-mirrors msys2-runtime" +C:\> C:\msys64\usr\bin\bash -lc "pacman --noconfirm -Syu"</code></pre> +</div></div> +</div> +<div class="sect3"> +<h4 id="_installing_the_required_msys2_packages">Installing the required MSYS2 packages</h4> +<div class="paragraph"><p>After following these instructions, you can install GNU Make, +Git and any other required softwares. From an MSYS2 shell, +you can call <code>pacman</code> 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>$ pacman -S git make</tt></pre></div></div> +<div class="paragraph"><p>You can use <code>pacman -Ss</code> to search packages. For example, +to find all packages related to GCC:</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>$ pacman -Ss gcc</tt></pre></div></div> +<div class="paragraph"><p>If you are going to compile C/C++ code, you will need to +install this package, as Erlang.mk cannot use the normal +"gcc" package:</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>$ pacman -S mingw-w<span style="color: #993399">64</span>-x86_64-gcc</tt></pre></div></div> +<div class="paragraph"><p>You can also run commands under the MSYS2 environment from +the Windows command line or batch files. This command will +install GNU Make and Git:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><code>C:\> C:\msys64\usr\bin\bash -lc "pacman --noconfirm -S git make"</code></pre> +</div></div> +<div class="paragraph"><p>You can use similar <code>bash</code> commands if you need to run programs +inside the MSYS2 environment from a batch file.</p></div> +</div> +<div class="sect3"> +<h4 id="_gotchas">Gotchas</h4> +<div class="paragraph"><p>While most of the basic functionality will just work, there are +still some issues. Erlang.mk needs to be fixed to pass the +right paths when running Erlang scripts. We are working on it. +Erlang.mk is fully tested on both Linux and Windows, but is +lacking tests in the areas not yet covered by this guide, +so expect bugs to be fixed as more tests are added.</p></div> +</div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/kerl.asciidoc b/docs/en/erlang.mk/1/guide/kerl.asciidoc new file mode 100644 index 00000000..c557d432 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/kerl.asciidoc @@ -0,0 +1,76 @@ +[[kerl]] +== OTP version management + +Erlang.mk comes with integrated support for +https://github.com/kerl/kerl[Kerl], a shell script that +automates the downloading, building and installing of +Erlang/OTP. It can be used to easily build a specific +Erlang/OTP version (with or without custom build options) +or maintain different versions side by side. + +=== Erlang versions + +Erlang.mk uses the Git tags from Erlang/OTP to identify +OTP versions. The most recent tag at the time of writing +is `OTP-20.0.4`, which is a patch release of `OTP-20.0`. +A patch release is a non-official release containing a +few fixes on top of the official release. + +Older versions used a slightly different versioning scheme +and tag format, for example: `OTP_R16B03`. Beware though, +there also was an `OTP_R16B03-1` release that fixed a +critical issue in the initial release. + +The README file for all official Erlang/OTP releases can +be found on http://www.erlang.org/downloads[erlang.org]. +To obtain information about patch releases when they are +released you need to be subscribed to the +http://erlang.org/mailman/listinfo/erlang-questions[erlang-questions mailing list]. + +[[otp_version_pinning]] +=== OTP version pinning + +Erlang.mk can use a specific version of Erlang/OTP when +interacting with your project. This can be very useful +when you are working with a team because you can define +the version you need in the Makefile and Erlang.mk will +ensure this version is used by everyone in your team. + +To pin the version all you need to do is to set the +`ERLANG_OTP` variable in your Makefile before including +Erlang.mk. For example, to use `OTP-20.0.4`: + +[source,make] +---- +ERLANG_OTP = OTP-20.0.4 + +include erlang.mk +---- + +The next time you run `make` Erlang.mk will build and +use the version you configured. + +Note that there has been reports that this functionality +is not compatible with the `.ONESHELL` feature from +GNU Make. + +=== Continuous integration + +Erlang.mk can automatically test your project against +many different Erlang/OTP versions. This functionality +is documented in the xref:ci[Continuous integration] chapter. + +=== Configuring Kerl + +All of the Kerl variables can be configured directly in the +Makefile. All you need to do is to export them. For example, +to change the installation directory for the Erlang/OTP +versions managed by Kerl, you could add the following to +your Makefile: + +[source,make] +export KERL_INSTALL_DIR = $(CURDIR)/erlang + +When configuring paths like this, always make sure to provide +an absolute path in the value. Erlang.mk will NOT expand them +automatically for you. diff --git a/docs/en/erlang.mk/1/guide/kerl/index.html b/docs/en/erlang.mk/1/guide/kerl/index.html new file mode 100644 index 00000000..d5474929 --- /dev/null +++ b/docs/en/erlang.mk/1/guide/kerl/index.html @@ -0,0 +1,233 @@ +<!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.26" /> + + <title>Nine Nines: OTP version management</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=1" 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>OTP version management</span></h1> + +<div class="paragraph"><p>Erlang.mk comes with integrated support for +<a href="https://github.com/kerl/kerl">Kerl</a>, a shell script that +automates the downloading, building and installing of +Erlang/OTP. It can be used to easily build a specific +Erlang/OTP version (with or without custom build options) +or maintain different versions side by side.</p></div> +<div class="sect1"> +<h2 id="_erlang_versions">Erlang versions</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk uses the Git tags from Erlang/OTP to identify +OTP versions. The most recent tag at the time of writing +is <code>OTP-20.0.4</code>, which is a patch release of <code>OTP-20.0</code>. +A patch release is a non-official release containing a +few fixes on top of the official release.</p></div> +<div class="paragraph"><p>Older versions used a slightly different versioning scheme +and tag format, for example: <code>OTP_R16B03</code>. Beware though, +there also was an <code>OTP_R16B03-1</code> release that fixed a +critical issue in the initial release.</p></div> +<div class="paragraph"><p>The README file for all official Erlang/OTP releases can +be found on <a href="http://www.erlang.org/downloads">erlang.org</a>. +To obtain information about patch releases when they are +released you need to be subscribed to the +<a href="http://erlang.org/mailman/listinfo/erlang-questions">erlang-questions mailing list</a>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="otp_version_pinning">OTP version pinning</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk can use a specific version of Erlang/OTP when +interacting with your project. This can be very useful +when you are working with a team because you can define +the version you need in the Makefile and Erlang.mk will +ensure this version is used by everyone in your team.</p></div> +<div class="paragraph"><p>To pin the version all you need to do is to set the +<code>ERLANG_OTP</code> variable in your Makefile before including +Erlang.mk. For example, to use <code>OTP-20.0.4</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">ERLANG_OTP =</span> OTP-20.0.4 + +include erlang.mk</tt></pre></div></div> +<div class="paragraph"><p>The next time you run <code>make</code> Erlang.mk will build and +use the version you configured.</p></div> +<div class="paragraph"><p>Note that there has been reports that this functionality +is not compatible with the <code>.ONESHELL</code> feature from +GNU Make.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_continuous_integration">Continuous integration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk can automatically test your project against +many different Erlang/OTP versions. This functionality +is documented in the <a href="../ci">Continuous integration</a> chapter.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuring_kerl">Configuring Kerl</h2> +<div class="sectionbody"> +<div class="paragraph"><p>All of the Kerl variables can be configured directly in the +Makefile. All you need to do is to export them. For example, +to change the installation directory for the Erlang/OTP +versions managed by Kerl, you could add 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="font-weight: bold"><span style="color: #0000FF">export</span></span> KERL_INSTALL_DIR <span style="color: #990000">=</span> <span style="color: #009900">$(CURDIR)</span>/erlang</tt></pre></div></div> +<div class="paragraph"><p>When configuring paths like this, always make sure to provide +an absolute path in the value. Erlang.mk will NOT expand them +automatically for you.</p></div> +</div> +</div> + + + + + + + + + + + <nav style="margin:1em 0"> + + <a style="float:left" href="https://ninenines.eu/docs/en/erlang.mk/1/guide/escripts/"> + Escripts + </a> + + + + <a style="float:right" href="https://ninenines.eu/docs/en/erlang.mk/1/guide/compat/"> + Compatibility with other build tools + </a> + + </nav> + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Erlang.mk + 1 + + User Guide +</h3> + +<ul> + + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/erlang.mk/1/guide">1</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="/js/custom.js"></script> + </body> +</html> + + diff --git a/docs/en/erlang.mk/1/guide/limitations/index.html b/docs/en/erlang.mk/1/guide/limitations/index.html index abf19700..48561e8f 100644 --- a/docs/en/erlang.mk/1/guide/limitations/index.html +++ b/docs/en/erlang.mk/1/guide/limitations/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Limitations</title> @@ -67,55 +67,58 @@ <h1 class="lined-header"><span>Limitations</span></h1> -<div class="paragraph"><p>No software is perfect.</p></div>
-<div class="paragraph"><p>It’s very important, when evaluating and when using a tool,
-to understand its limitations, so as to avoid making mistakes
-and wasting valuable time.</p></div>
-<div class="paragraph"><p>This chapter lists all known limitations of Erlang.mk.</p></div>
-<div class="sect1">
-<h2 id="_erlang_must_be_available">Erlang must be available</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Currently Erlang.mk requires you to install Erlang beforehand.
-Installing Erlang is not always easy, particularly if you need
-a specific version of Erlang for a specific project.</p></div>
-<div class="paragraph"><p>In addition, the Erlang being used must be in your <code>$PATH</code>
-before you use Erlang.mk.</p></div>
-<div class="paragraph"><p>In the future we envision, Erlang.mk could manage the Erlang
-version you need to use a project. Erlang.mk already does this
-for running tests when using <code>make ci</code>, so doing this during
-development is just a step away.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_spaces_in_path">Spaces in path</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk will currently not work properly if the path to the
-project contains spaces. To check if that is the case, use the
-command <code>pwd</code>.</p></div>
-<div class="paragraph"><p>This issue is due to how Makefiles work. There might be ways
-to solve it, we have not given up on it, but it’s very low
-priority considering how simple the workaround is.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_dependency_tracking_and_modification_times">Dependency tracking and modification times</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang source files that depend on other files will have their
-modification time updated when they need to be recompiled due
-to a dependency having changed. This could cause some editors to
-think the file changed when it didn’t.</p></div>
-<div class="paragraph"><p>Erlang.mk must use this method in order to be able to compile
-files in one <code>erlc</code> invocation. The benefits greatly outweigh
-the issue in this case and so there are currently no plans to
-fix this behavior.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>No software is perfect.</p></div> +<div class="paragraph"><p>It’s very important, when evaluating and when using a tool, +to understand its limitations, so as to avoid making mistakes +and wasting valuable time.</p></div> +<div class="paragraph"><p>This chapter lists all known limitations of Erlang.mk.</p></div> +<div class="sect1"> +<h2 id="_erlang_must_be_available">Erlang must be available</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Currently Erlang.mk requires you to install Erlang beforehand. +Installing Erlang is not always easy, particularly if you need +a specific version of Erlang for a specific project.</p></div> +<div class="paragraph"><p>In addition, the Erlang being used must be in your <code>$PATH</code> +before you use Erlang.mk.</p></div> +<div class="paragraph"><p>In the future we envision, Erlang.mk could manage the Erlang +version you need to use a project. Erlang.mk already does this +for running tests when using <code>make ci</code>, so doing this during +development is just a step away.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_spaces_in_path">Spaces in path</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk will currently not work properly if the path to the +project contains spaces. To check if that is the case, use the +command <code>pwd</code>.</p></div> +<div class="paragraph"><p>This issue is due to how Makefiles work. There might be ways +to solve it, we have not given up on it, but it’s very low +priority considering how simple the workaround is.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_dependency_tracking_and_modification_times">Dependency tracking and modification times</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang source files that depend on other files will have their +modification time updated when they need to be recompiled due +to a dependency having changed. This could cause some editors to +think the file changed when it didn’t.</p></div> +<div class="paragraph"><p>Erlang.mk must use this method in order to be able to compile +files in one <code>erlc</code> invocation. The benefits greatly outweigh +the issue in this case and so there are currently no plans to +fix this behavior.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/overview/index.html b/docs/en/erlang.mk/1/guide/overview/index.html index 5c072e64..2a6cbf1f 100644 --- a/docs/en/erlang.mk/1/guide/overview/index.html +++ b/docs/en/erlang.mk/1/guide/overview/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Overview</title> @@ -67,100 +67,103 @@ <h1 class="lined-header"><span>Overview</span></h1> -<div class="paragraph"><p>Now that you know how to get started, let’s take a look at
-what Erlang.mk can do for you.</p></div>
-<div class="sect1">
-<h2 id="_building_your_project">Building your project</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk is first and foremost a build tool. It is especially
-tailored for Erlang developers and follows widely accepted
-practices in the Erlang community.</p></div>
-<div class="paragraph"><p>Erlang.mk will happily build all <a href="../building">Erlang-specific files</a>
-you throw at it. Other kinds of files too, like C or C++ code
-when you are working on <a href="../ports">a NIF or a port driver</a>.</p></div>
-<div class="paragraph"><p>Erlang.mk embraces the concept of <a href="../deps">source dependencies</a>.
-It can fetch dependency source code using a variety of mechanisms,
-including fetching from Git, Mercurial or SVN.</p></div>
-<div class="paragraph"><p>Erlang.mk will automatically <a href="../relx">generate releases</a>
-when applicable. It can also <a href="../escript">generate escripts</a>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exploring_the_package_index">Exploring the package index</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk comes with a <a href="../deps">built-in package index</a>.
-It is built as an extension of the dependency system and is
-meant to be used for discovery purposes.</p></div>
-<div class="paragraph"><p>No package is ever installed, they are only used as dependencies
-and are always project-specific. They can be thought of as a
-shortcut over plain dependencies.</p></div>
-<div class="paragraph"><p>You can get a list of all packages known to Erlang.mk by using
-the <code>search</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>$ make search</tt></pre></div></div>
-<div class="paragraph"><p>You can also use this target to search across all packages, for
-example to find all packages related to 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>$ make search <span style="color: #009900">q</span><span style="color: #990000">=</span>cowboy</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_generating_documentation">Generating documentation</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk supports <em>EDoc</em> and <em>Asciidoc</em>.</p></div>
-<div class="paragraph"><p><a href="../edoc">EDoc</a> generates HTML documentation directly from
-your source code.</p></div>
-<div class="paragraph"><p>While it is convenient, ask yourself: if all the documentation is
-inside the source code, why not just open the source code directly?
-That’s where <em>Asciidoc</em> comes in.</p></div>
-<div class="paragraph"><p>The <a href="../asciidoc">Asciidoc</a> plugin expects all documentation
-to be separate from source. It will generate HTML, PDF, man pages and
-more from the documentation you write in the <em>doc/src/</em> folder in
-your repository.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_running_tests">Running tests</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk supports a lot of different testing and static
-analysis tools.</p></div>
-<div class="paragraph"><p>The <a href="../shell">make shell</a> command allows you
-to test your project manually. You can automate these
-unit tests with <a href="../eunit">EUnit</a> and test
-your entire system with <a href="../ct">Common Test</a>.
-<a href="../coverage">Code coverage</a> can of course
-be enabled during tests.</p></div>
-<div class="paragraph"><p>Erlang.mk comes with features to make your life easier when
-setting up and using <a href="../ci">Continuous integration</a>.</p></div>
-<div class="paragraph"><p>On the static analysis side of things, Erlang.mk comes with
-support for <a href="../dialyzer">Dialyzer</a> and <a href="#xref">Xref</a>,
-to perform success typing analysis and cross referencing
-of the code.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_need_more">Need more?</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Not convinced yet? You can read about <a href="../why">why you should use Erlang.mk</a>
-and its <a href="../history">history</a>. And if you’re still not
-convinced after that, it’s OK! The world would be boring if
-everyone agreed on everything all the time.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Now that you know how to get started, let’s take a look at +what Erlang.mk can do for you.</p></div> +<div class="sect1"> +<h2 id="_building_your_project">Building your project</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk is first and foremost a build tool. It is especially +tailored for Erlang developers and follows widely accepted +practices in the Erlang community.</p></div> +<div class="paragraph"><p>Erlang.mk will happily build all <a href="../building">Erlang-specific files</a> +you throw at it. Other kinds of files too, like C or C++ code +when you are working on <a href="../ports">a NIF or a port driver</a>.</p></div> +<div class="paragraph"><p>Erlang.mk embraces the concept of <a href="../deps">source dependencies</a>. +It can fetch dependency source code using a variety of mechanisms, +including fetching from Git, Mercurial or SVN.</p></div> +<div class="paragraph"><p>Erlang.mk will automatically <a href="../relx">generate releases</a> +when applicable. It can also <a href="../escript">generate escripts</a>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_exploring_the_package_index">Exploring the package index</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk comes with a <a href="../deps">built-in package index</a>. +It is built as an extension of the dependency system and is +meant to be used for discovery purposes.</p></div> +<div class="paragraph"><p>No package is ever installed, they are only used as dependencies +and are always project-specific. They can be thought of as a +shortcut over plain dependencies.</p></div> +<div class="paragraph"><p>You can get a list of all packages known to Erlang.mk by using +the <code>search</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>$ make search</tt></pre></div></div> +<div class="paragraph"><p>You can also use this target to search across all packages, for +example to find all packages related to 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>$ make search <span style="color: #009900">q</span><span style="color: #990000">=</span>cowboy</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_generating_documentation">Generating documentation</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk supports <em>EDoc</em> and <em>Asciidoc</em>.</p></div> +<div class="paragraph"><p><a href="../edoc">EDoc</a> generates HTML documentation directly from +your source code.</p></div> +<div class="paragraph"><p>While it is convenient, ask yourself: if all the documentation is +inside the source code, why not just open the source code directly? +That’s where <em>Asciidoc</em> comes in.</p></div> +<div class="paragraph"><p>The <a href="../asciidoc">Asciidoc</a> plugin expects all documentation +to be separate from source. It will generate HTML, PDF, man pages and +more from the documentation you write in the <em>doc/src/</em> folder in +your repository.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_running_tests">Running tests</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk supports a lot of different testing and static +analysis tools.</p></div> +<div class="paragraph"><p>The <a href="../shell">make shell</a> command allows you +to test your project manually. You can automate these +unit tests with <a href="../eunit">EUnit</a> and test +your entire system with <a href="../ct">Common Test</a>. +<a href="../coverage">Code coverage</a> can of course +be enabled during tests.</p></div> +<div class="paragraph"><p>Erlang.mk comes with features to make your life easier when +setting up and using <a href="../ci">Continuous integration</a>.</p></div> +<div class="paragraph"><p>On the static analysis side of things, Erlang.mk comes with +support for <a href="../dialyzer">Dialyzer</a> and <a href="#xref">Xref</a>, +to perform success typing analysis and cross referencing +of the code.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_need_more">Need more?</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Not convinced yet? You can read about <a href="../why">why you should use Erlang.mk</a> +and its <a href="../history">history</a>. And if you’re still not +convinced after that, it’s OK! The world would be boring if +everyone agreed on everything all the time.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/ports.asciidoc b/docs/en/erlang.mk/1/guide/ports.asciidoc index 02c636fd..907ee366 100644 --- a/docs/en/erlang.mk/1/guide/ports.asciidoc +++ b/docs/en/erlang.mk/1/guide/ports.asciidoc @@ -98,3 +98,37 @@ The source files are automatically gathered from the contents of '$(C_SRC_DIR)'. Erlang.mk looks for '.c', '.C', '.cc' and '.cpp' source files. You can define the variable `SOURCES` to manually list the files to compile. + +=== Propagating compile and linker flags to sub-Makefiles + +In some cases it might be necessary to propagate the flags +you just defined to the sub-Makefiles of your local project. +You generally can't just export those as this could impact +the building of dependencies. + +Makefiles allow you to export variables for specific targets. +When doing this, the variables will be exported only when +this target runs, and not for other targets. It is therefore +possible to export them when building the C code without +impacting other build steps. + +By adding this to your Makefile all five variables will be +made available to sub-Makefiles when building C code: + +[source,make] +---- +app-c_src: export CC += +app-c_src: export CFLAGS += +app-c_src: export CPPFLAGS += +app-c_src: export LDFLAGS += +app-c_src: export LDLIBS += +---- + +Appending an empty string to the existing value is necessary +because Makefiles expect an assignment for target-specific +exports. Alternatively you can set a new value: + +[source,make] +---- +app-c_src: export CFLAGS = -O3 +---- diff --git a/docs/en/erlang.mk/1/guide/ports/index.html b/docs/en/erlang.mk/1/guide/ports/index.html index 619cfb40..24fa8b15 100644 --- a/docs/en/erlang.mk/1/guide/ports/index.html +++ b/docs/en/erlang.mk/1/guide/ports/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: NIFs and port drivers</title> @@ -67,148 +67,202 @@ <h1 class="lined-header"><span>NIFs and port drivers</span></h1> -<div class="paragraph"><p>Erlang.mk can not only build Erlang projects, but also the C code
-that some projects come with, like NIFs and port drivers.</p></div>
-<div class="paragraph"><p>There are two ways to build the C code: using a custom Makefile,
-or making Erlang.mk do it directly. The C code will be built
-as needed when you run <code>make</code>.</p></div>
-<div class="sect1">
-<h2 id="_c_source_code_location_and_erlang_environment">C source code location and Erlang environment</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The C source code should be located in the <em>$(C_SRC_DIR)</em> directory.
-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"></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"></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">
-<code>ERTS_INCLUDE_DIR</code>
-</dt>
-<dd>
-<p>
- Path to the ERTS include files (<em>erl_driver.h</em>, <em>erl_nif.h</em> and more).
-</p>
-</dd>
-<dt class="hdlist1">
-<code>ERL_INTERFACE_INCLUDE_DIR</code>
-</dt>
-<dd>
-<p>
- Path to the Erl_Interface include files (<em>ei.h</em> and related).
-</p>
-</dd>
-<dt class="hdlist1">
-<code>ERL_INTERFACE_LIB_DIR</code>
-</dt>
-<dd>
-<p>
- Path to the Erl_Interface static libraries.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_using_a_custom_makefile">Using a custom Makefile</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk will automatically run <code>make</code> if it detects a Makefile
-in <em>$(C_SRC_DIR)/Makefile</em>.</p></div>
-<div class="paragraph"><p>The Makefile should have at least two targets: a default target
-(which can be anything, for example <code>all</code>) which is invoked when
-building the C code, and a <code>clean</code> target invoked when cleaning
-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"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_using_erlang_mk_directly">Using Erlang.mk directly</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You don’t need to write a Makefile to build C source code, however.
-Erlang.mk comes with rules to build both shared libraries and
-executables, using the source files it finds in <em>$(C_SRC_DIR)</em>.</p></div>
-<div class="paragraph"><p>By default, Erlang.mk will create a shared library. To change
-this and create an executable instead, put this in your Makefile
-before including Erlang.mk:</p></div>
-<div class="listingblock">
-<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>
-<div class="paragraph"><p>For shared libraries, the generated file name will be
-<em>$(C_SRC_OUTPUT)$(C_SRC_SHARED_EXTENSION)</em>, with the default
-being <em>$(CURDIR)/priv/$(PROJECT)</em> followed by the extension:
-<code>.dll</code> on Windows, <code>.so</code> everywhere else.</p></div>
-<div class="paragraph"><p>For executables, the generated file name is
-<em>$(C_SRC_OUTPUT)$(C_SRC_EXECUTABLE_EXTENSION)</em>, with the same
-default except for the extension: <code>.exe</code> on Windows, and otherwise
-nothing.</p></div>
-<div class="paragraph"><p>Erlang.mk sets appropriate compile and linker flags by default.
-These flags vary depending on the platform, and can of course
-be overriden.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<code>CC</code>
-</dt>
-<dd>
-<p>
- The compiler to be used.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>CFLAGS</code>
-</dt>
-<dd>
-<p>
- C compiler flags.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>CXXFLAGS</code>
-</dt>
-<dd>
-<p>
- C++ compiler flags.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>LDFLAGS</code>
-</dt>
-<dd>
-<p>
- Linker flags.
-</p>
-</dd>
-<dt class="hdlist1">
-<code>LDLIBS</code>
-</dt>
-<dd>
-<p>
- Libraries to link against.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>The source files are automatically gathered from the contents
-of <em>$(C_SRC_DIR)</em>. Erlang.mk looks for <em>.c</em>, <em>.C</em>, <em>.cc</em> and <em>.cpp</em>
-source files. You can define the variable <code>SOURCES</code> to manually
-list the files to compile.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Erlang.mk can not only build Erlang projects, but also the C code +that some projects come with, like NIFs and port drivers.</p></div> +<div class="paragraph"><p>There are two ways to build the C code: using a custom Makefile, +or making Erlang.mk do it directly. The C code will be built +as needed when you run <code>make</code>.</p></div> +<div class="sect1"> +<h2 id="_c_source_code_location_and_erlang_environment">C source code location and Erlang environment</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The C source code should be located in the <em>$(C_SRC_DIR)</em> directory. +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="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="paragraph"><p>It contains a few variable definitions for the environment used for the build:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +<code>ERTS_INCLUDE_DIR</code> +</dt> +<dd> +<p> + Path to the ERTS include files (<em>erl_driver.h</em>, <em>erl_nif.h</em> and more). +</p> +</dd> +<dt class="hdlist1"> +<code>ERL_INTERFACE_INCLUDE_DIR</code> +</dt> +<dd> +<p> + Path to the Erl_Interface include files (<em>ei.h</em> and related). +</p> +</dd> +<dt class="hdlist1"> +<code>ERL_INTERFACE_LIB_DIR</code> +</dt> +<dd> +<p> + Path to the Erl_Interface static libraries. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_using_a_custom_makefile">Using a custom Makefile</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk will automatically run <code>make</code> if it detects a Makefile +in <em>$(C_SRC_DIR)/Makefile</em>.</p></div> +<div class="paragraph"><p>The Makefile should have at least two targets: a default target +(which can be anything, for example <code>all</code>) which is invoked when +building the C code, and a <code>clean</code> target invoked when cleaning +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> +</div> +<div class="sect1"> +<h2 id="_using_erlang_mk_directly">Using Erlang.mk directly</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You don’t need to write a Makefile to build C source code, however. +Erlang.mk comes with rules to build both shared libraries and +executables, using the source files it finds in <em>$(C_SRC_DIR)</em>.</p></div> +<div class="paragraph"><p>By default, Erlang.mk will create a shared library. To change +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="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> +<div class="paragraph"><p>For shared libraries, the generated file name will be +<em>$(C_SRC_OUTPUT)$(C_SRC_SHARED_EXTENSION)</em>, with the default +being <em>$(CURDIR)/priv/$(PROJECT)</em> followed by the extension: +<code>.dll</code> on Windows, <code>.so</code> everywhere else.</p></div> +<div class="paragraph"><p>For executables, the generated file name is +<em>$(C_SRC_OUTPUT)$(C_SRC_EXECUTABLE_EXTENSION)</em>, with the same +default except for the extension: <code>.exe</code> on Windows, and otherwise +nothing.</p></div> +<div class="paragraph"><p>Erlang.mk sets appropriate compile and linker flags by default. +These flags vary depending on the platform, and can of course +be overriden.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +<code>CC</code> +</dt> +<dd> +<p> + The compiler to be used. +</p> +</dd> +<dt class="hdlist1"> +<code>CFLAGS</code> +</dt> +<dd> +<p> + C compiler flags. +</p> +</dd> +<dt class="hdlist1"> +<code>CXXFLAGS</code> +</dt> +<dd> +<p> + C++ compiler flags. +</p> +</dd> +<dt class="hdlist1"> +<code>LDFLAGS</code> +</dt> +<dd> +<p> + Linker flags. +</p> +</dd> +<dt class="hdlist1"> +<code>LDLIBS</code> +</dt> +<dd> +<p> + Libraries to link against. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>The source files are automatically gathered from the contents +of <em>$(C_SRC_DIR)</em>. Erlang.mk looks for <em>.c</em>, <em>.C</em>, <em>.cc</em> and <em>.cpp</em> +source files. You can define the variable <code>SOURCES</code> to manually +list the files to compile.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_propagating_compile_and_linker_flags_to_sub_makefiles">Propagating compile and linker flags to sub-Makefiles</h2> +<div class="sectionbody"> +<div class="paragraph"><p>In some cases it might be necessary to propagate the flags +you just defined to the sub-Makefiles of your local project. +You generally can’t just export those as this could impact +the building of dependencies.</p></div> +<div class="paragraph"><p>Makefiles allow you to export variables for specific targets. +When doing this, the variables will be exported only when +this target runs, and not for other targets. It is therefore +possible to export them when building the C code without +impacting other build steps.</p></div> +<div class="paragraph"><p>By adding this to your Makefile all five variables will be +made available to sub-Makefiles when building C 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: #990000">app-c_src:</span> <span style="font-weight: bold"><span style="color: #0000FF">export</span></span> CC <span style="color: #990000">+=</span> +<span style="color: #990000">app-c_src:</span> <span style="font-weight: bold"><span style="color: #0000FF">export</span></span> CFLAGS <span style="color: #990000">+=</span> +<span style="color: #990000">app-c_src:</span> <span style="font-weight: bold"><span style="color: #0000FF">export</span></span> CPPFLAGS <span style="color: #990000">+=</span> +<span style="color: #990000">app-c_src:</span> <span style="font-weight: bold"><span style="color: #0000FF">export</span></span> LDFLAGS <span style="color: #990000">+=</span> +<span style="color: #990000">app-c_src:</span> <span style="font-weight: bold"><span style="color: #0000FF">export</span></span> LDLIBS <span style="color: #990000">+=</span></tt></pre></div></div> +<div class="paragraph"><p>Appending an empty string to the existing value is necessary +because Makefiles expect an assignment for target-specific +exports. Alternatively you can set a new 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: #990000">app-c_src:</span> <span style="font-weight: bold"><span style="color: #0000FF">export</span></span> CFLAGS <span style="color: #990000">=</span> -O<span style="color: #993399">3</span></tt></pre></div></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/releases/index.html b/docs/en/erlang.mk/1/guide/releases/index.html index e3c46057..606c47e3 100644 --- a/docs/en/erlang.mk/1/guide/releases/index.html +++ b/docs/en/erlang.mk/1/guide/releases/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Releases</title> @@ -67,199 +67,226 @@ <h1 class="lined-header"><span>Releases</span></h1> -<div class="paragraph"><p>Erlang.mk relies on <em>Relx</em> for generating releases. This
-chapter covers the Erlang.mk-specific bits. Consult the
-<a href="https://erlware.github.io/relx/">Relx website</a> for more information.</p></div>
-<div class="sect1">
-<h2 id="_setup">Setup</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk will create a release if it detects a Relx configuration
-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"></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
-location defaults to <em>$(CURDIR)/relx</em> and can be overriden.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_configuration">Configuration</h2>
-<div class="sectionbody">
-<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"></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"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_generating_the_release">Generating the release</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Now that you’re all set, all you need to do is generate the
-release. As mentioned before, Erlang.mk will automatically
-generate it when it detects the <em>$(RELX_CONFIG)</em> file. This
-means the following command will also build 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>$ make</tt></pre></div></div>
-<div class="paragraph"><p>If you need to generate the release, and only the release,
-the <code>rel</code> target can be used:</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 rel</tt></pre></div></div>
-<div class="paragraph"><p>Erlang.mk always generates a tarball alongside the release,
-which can be directly uploaded to a server. The tarball is
-located at <code>$(RELX_OUTPUT_DIR)/<name>/<name>-<vsn>.tar.gz</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_running_the_release">Running the release</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk provides a convenience function for running the
-release with one simple 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>$ make run</tt></pre></div></div>
-<div class="paragraph"><p>This command will also build the project and generate the
-release if they weren’t already. It starts the release in
-<em>console mode</em>, meaning you will also have a shell ready to
-use to check things as needed.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_upgrading_a_release">Upgrading a release</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk provides a <code>relup</code> target for generating release
-upgrades. Release upgrades allow updating the code and the
-state of a running release without restarting it.</p></div>
-<div class="paragraph"><p>Once your changes are done, you need to update the version
-of the application(s) that will be updated. You also need
-to update the version of the release.</p></div>
-<div class="paragraph"><p>For each application that needs to be updated, an
-<a href="http://erlang.org/doc/man/appup.html">appup file</a>
-must be written. Refer to the Erlang/OTP documentation
-for more details.</p></div>
-<div class="paragraph"><p>For the purpose of this section, assume the initial release
-version was <code>1</code>, and the new version is <code>2</code>. The name of the
-release will be <code>example</code>.</p></div>
-<div class="paragraph"><p>Once all this is done, you can build the tarball for the
-release upgrade:</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 relup</tt></pre></div></div>
-<div class="paragraph"><p>This will create an archive at the root directory of the
-release, <code>$RELX_OUTPUT_DIR/example/example-2.tar.gz</code>.</p></div>
-<div class="paragraph"><p>Move the archive to the correct location on the running
-node. From the release’s root directory:</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>$ mkdir releases<span style="color: #990000">/</span><span style="color: #993399">2</span><span style="color: #990000">/</span>
-$ mv path/to/example-<span style="color: #993399">2</span><span style="color: #990000">.</span>tar<span style="color: #990000">.</span>gz releases<span style="color: #990000">/</span><span style="color: #993399">2</span><span style="color: #990000">/</span></tt></pre></div></div>
-<div class="paragraph"><p>Finally, upgrade 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>$ bin/example_release upgrade <span style="color: #FF0000">"2/example_release"</span></tt></pre></div></div>
-<div class="paragraph"><p>Or on Windows:</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>$ bin/example_release<span style="color: #990000">.</span>cmd upgrade <span style="color: #FF0000">"2/example_release"</span></tt></pre></div></div>
-<div class="paragraph"><p>Your release was upgraded!</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_getting_relx_semver_value">Getting Relx semver value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>There is a <strong>workaround</strong> to get the semver value which is
-generated by Relx based on VCS history.</p></div>
-<div class="paragraph"><p>Create a file <em>rel/version</em> with only one line inside:</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">release_version</span> }}</tt></pre></div></div>
-<div class="paragraph"><p>Add/Update the <code>overlay</code> section of your <code>relx.config</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: #FF6600">overlay</span>, [
- {<span style="color: #FF6600">template</span>, <span style="color: #FF0000">"rel/version"</span>, <span style="color: #FF0000">"version"</span>}
-]}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>When you run <code>make rel</code> it creates the file <em>$(RELX_OUTPUT_DIR)/example/version</em>
-which contains the version value generated by Relx.</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>$ cat _rel/app/release
-<span style="color: #993399">1.0</span><span style="color: #990000">.</span><span style="color: #993399">0</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0</tt></pre></div></div>
-<div class="paragraph"><p>In your <code>Makefile</code> you can use this simple snippet to get the version,
-but please keep in mind that this should depend on the <code>rel</code> target:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>For example:</p></div>
-<div class="listingblock">
-<div class="content"></div></div>
-<div class="paragraph"><p>Would output:</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 myrecipe
-<span style="color: #990000">...</span>
-<span style="color: #990000">===></span> Starting relx build process <span style="color: #990000">...</span>
-<span style="color: #990000">===></span> Resolving OTP Applications from directories<span style="color: #990000">:</span>
- /home/username/example/apps
- /home/username/example/deps
- /usr/lib/erlang/lib
- /home/username/example<span style="color: #990000">/</span>_rel
-<span style="color: #990000">===></span> Resolved example-<span style="color: #993399">0.3</span><span style="color: #990000">.</span><span style="color: #993399">10</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0
-<span style="color: #990000">===></span> Including Erts from /usr/lib/erlang
-<span style="color: #990000">===></span> release successfully created<span style="color: #990000">!</span>
-<span style="color: #990000">===></span> tarball /home/username/example<span style="color: #990000">/</span>_rel/example/example-<span style="color: #993399">0.3</span><span style="color: #990000">.</span><span style="color: #993399">10</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0<span style="color: #990000">.</span>tar<span style="color: #990000">.</span>gz successfully created<span style="color: #990000">!</span>
-echo APP_VERSION <span style="color: #990000">=</span> <span style="color: #993399">0.3</span><span style="color: #990000">.</span><span style="color: #993399">10</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0
-APP_VERSION <span style="color: #990000">=</span> <span style="color: #993399">0.3</span><span style="color: #990000">.</span><span style="color: #993399">10</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0</tt></pre></div></div>
-</div>
-</div>
+<div class="paragraph"><p>Erlang.mk relies on <em>Relx</em> for generating releases. This +chapter covers the Erlang.mk-specific bits. Consult the +<a href="https://erlware.github.io/relx/">Relx website</a> for more information.</p></div> +<div class="sect1"> +<h2 id="_setup">Setup</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk will create a release if it detects a Relx configuration +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="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 +location defaults to <em>$(CURDIR)/relx</em> and can be overriden.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<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="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> +</div> +<div class="sect1"> +<h2 id="_generating_the_release">Generating the release</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Now that you’re all set, all you need to do is generate the +release. As mentioned before, Erlang.mk will automatically +generate it when it detects the <em>$(RELX_CONFIG)</em> file. This +means the following command will also build 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>$ make</tt></pre></div></div> +<div class="paragraph"><p>If you need to generate the release, and only the release, +the <code>rel</code> target can be used:</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 rel</tt></pre></div></div> +<div class="paragraph"><p>Erlang.mk always generates a tarball alongside the release, +which can be directly uploaded to a server. The tarball is +located at <code>$(RELX_OUTPUT_DIR)/<name>/<name>-<vsn>.tar.gz</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_running_the_release">Running the release</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk provides a convenience function for running the +release with one simple 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>$ make run</tt></pre></div></div> +<div class="paragraph"><p>This command will also build the project and generate the +release if they weren’t already. It starts the release in +<em>console mode</em>, meaning you will also have a shell ready to +use to check things as needed.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_upgrading_a_release">Upgrading a release</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk provides a <code>relup</code> target for generating release +upgrades. Release upgrades allow updating the code and the +state of a running release without restarting it.</p></div> +<div class="paragraph"><p>Once your changes are done, you need to update the version +of the application(s) that will be updated. You also need +to update the version of the release.</p></div> +<div class="paragraph"><p>For each application that needs to be updated, an +<a href="http://erlang.org/doc/man/appup.html">appup file</a> +must be written. Refer to the Erlang/OTP documentation +for more details.</p></div> +<div class="paragraph"><p>For the purpose of this section, assume the initial release +version was <code>1</code>, and the new version is <code>2</code>. The name of the +release will be <code>example</code>.</p></div> +<div class="paragraph"><p>Once all this is done, you can build the tarball for the +release upgrade:</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 relup</tt></pre></div></div> +<div class="paragraph"><p>This will create an archive at the root directory of the +release, <code>$RELX_OUTPUT_DIR/example/example-2.tar.gz</code>.</p></div> +<div class="paragraph"><p>Move the archive to the correct location on the running +node. From the release’s root directory:</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>$ mkdir releases<span style="color: #990000">/</span><span style="color: #993399">2</span><span style="color: #990000">/</span> +$ mv path/to/example-<span style="color: #993399">2</span><span style="color: #990000">.</span>tar<span style="color: #990000">.</span>gz releases<span style="color: #990000">/</span><span style="color: #993399">2</span><span style="color: #990000">/</span></tt></pre></div></div> +<div class="paragraph"><p>Finally, upgrade 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>$ bin/example_release upgrade <span style="color: #FF0000">"2/example_release"</span></tt></pre></div></div> +<div class="paragraph"><p>Or on Windows:</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>$ bin/example_release<span style="color: #990000">.</span>cmd upgrade <span style="color: #FF0000">"2/example_release"</span></tt></pre></div></div> +<div class="paragraph"><p>Your release was upgraded!</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_getting_relx_semver_value">Getting Relx semver value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>There is a <strong>workaround</strong> to get the semver value which is +generated by Relx based on VCS history.</p></div> +<div class="paragraph"><p>Create a file <em>rel/version</em> with only one line inside:</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">release_version</span> }}</tt></pre></div></div> +<div class="paragraph"><p>Add/Update the <code>overlay</code> section of your <code>relx.config</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: #FF6600">overlay</span>, [ + {<span style="color: #FF6600">template</span>, <span style="color: #FF0000">"rel/version"</span>, <span style="color: #FF0000">"version"</span>} +]}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>When you run <code>make rel</code> it creates the file <em>$(RELX_OUTPUT_DIR)/example/version</em> +which contains the version value generated by Relx.</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>$ cat _rel/app/release +<span style="color: #993399">1.0</span><span style="color: #990000">.</span><span style="color: #993399">0</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0</tt></pre></div></div> +<div class="paragraph"><p>In your <code>Makefile</code> you can use this simple snippet to get the version, +but please keep in mind that this should depend on the <code>rel</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: #009900">$(</span>shell cat <span style="color: #009900">$(RELX_OUTPUT_DIR)/$(RELX_REL_NAME)/version)</span></tt></pre></div></div> +<div class="paragraph"><p>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>include erlang.mk + +<span style="color: #009900">APP_VERSION =</span> <span style="color: #009900">$(</span>shell cat <span style="color: #009900">$(RELX_OUTPUT_DIR)/$(RELX_REL_NAME)/version)</span> +<span style="color: #990000">myrecipe:</span> all + echo APP_VERSION <span style="color: #990000">=</span> <span style="color: #009900">$(APP_VERSION)</span></tt></pre></div></div> +<div class="paragraph"><p>Would output:</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 myrecipe +<span style="color: #990000">...</span> +<span style="color: #990000">===></span> Starting relx build process <span style="color: #990000">...</span> +<span style="color: #990000">===></span> Resolving OTP Applications from directories<span style="color: #990000">:</span> + /home/username/example/apps + /home/username/example/deps + /usr/lib/erlang/lib + /home/username/example<span style="color: #990000">/</span>_rel +<span style="color: #990000">===></span> Resolved example-<span style="color: #993399">0.3</span><span style="color: #990000">.</span><span style="color: #993399">10</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0 +<span style="color: #990000">===></span> Including Erts from /usr/lib/erlang +<span style="color: #990000">===></span> release successfully created<span style="color: #990000">!</span> +<span style="color: #990000">===></span> tarball /home/username/example<span style="color: #990000">/</span>_rel/example/example-<span style="color: #993399">0.3</span><span style="color: #990000">.</span><span style="color: #993399">10</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0<span style="color: #990000">.</span>tar<span style="color: #990000">.</span>gz successfully created<span style="color: #990000">!</span> +echo APP_VERSION <span style="color: #990000">=</span> <span style="color: #993399">0.3</span><span style="color: #990000">.</span><span style="color: #993399">10</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0 +APP_VERSION <span style="color: #990000">=</span> <span style="color: #993399">0.3</span><span style="color: #990000">.</span><span style="color: #993399">10</span><span style="color: #990000">+</span>build<span style="color: #990000">.</span><span style="color: #993399">11</span><span style="color: #990000">.</span>ref5612aa0</tt></pre></div></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/sfx/index.html b/docs/en/erlang.mk/1/guide/sfx/index.html index 38a1f25b..a97c253f 100644 --- a/docs/en/erlang.mk/1/guide/sfx/index.html +++ b/docs/en/erlang.mk/1/guide/sfx/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Self-extracting releases</title> @@ -67,61 +67,64 @@ <h1 class="lined-header"><span>Self-extracting releases</span></h1> -<div class="paragraph"><p>Erlang.mk allows you to package <a href="../relx">Relx releases</a> as
-self-extracting archives. These archives contain all the
-files in the release and come in the form of a script that
-will extract and run the release automatically.</p></div>
-<div class="paragraph"><p>This allows you to package the release as a single file
-that can then be executed.</p></div>
-<div class="paragraph"><p>This feature is currently experimental. Feedback is much
-appreciated.</p></div>
-<div class="sect1">
-<h2 id="_generating_the_self_extracting_archive">Generating the self-extracting archive</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To generate a self-extracting release, all you need to do
-is pass the <code>SFX=1</code> variable to Make when you build 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>$ make <span style="color: #009900">SFX</span><span style="color: #990000">=</span><span style="color: #993399">1</span></tt></pre></div></div>
-<div class="paragraph"><p>This will create a self-extracting archive in
-<code>$RELX_OUTPUT_DIR/<name>.run</code>. For example if the release
-is named <code>hello_world</code> and <code>$RELX_OUTPUT_DIR</code> is the default,
-the file will be located at <code>_rel/hello_world.run</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_running_the_release">Running the release</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Simply execute the script to get started:</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>_rel/hello_world<span style="color: #990000">.</span>run
-Exec<span style="color: #990000">:</span> /tmp/tmp<span style="color: #990000">.</span>3eeEq7E1ta/erts-<span style="color: #993399">8.1</span>/bin/erlexec <span style="color: #990000">...</span>
-Root<span style="color: #990000">:</span> /tmp/tmp<span style="color: #990000">.</span>3eeEq7E1ta
-/tmp/tmp<span style="color: #990000">.</span>3eeEq7E1ta
-Erlang/OTP <span style="color: #993399">19</span> <span style="color: #990000">[</span>erts-<span style="color: #993399">8.1</span><span style="color: #990000">]</span> <span style="color: #990000">[</span><span style="font-weight: bold"><span style="color: #0000FF">source</span></span><span style="color: #990000">]</span> <span style="color: #990000">[</span><span style="color: #993399">64</span>-bit<span style="color: #990000">]</span> <span style="color: #990000">[</span>smp<span style="color: #990000">:</span><span style="color: #993399">4</span><span style="color: #990000">:</span><span style="color: #993399">4</span><span style="color: #990000">]</span> <span style="color: #990000">...</span>
-
-Eshell V8<span style="color: #990000">.</span><span style="color: #993399">1</span> <span style="color: #990000">(</span>abort with <span style="color: #990000">^</span>G<span style="color: #990000">)</span>
-<span style="color: #990000">(</span>hello_world@localhost<span style="color: #990000">)</span><span style="color: #993399">1</span><span style="color: #990000">></span></tt></pre></div></div>
-<div class="paragraph"><p>As you can see the archive is extracted to a temporary
-directory before the release can be started.</p></div>
-<div class="paragraph"><p>The self-extracting script currently only supports starting
-the release in <code>console</code> mode.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Erlang.mk allows you to package <a href="../relx">Relx releases</a> as +self-extracting archives. These archives contain all the +files in the release and come in the form of a script that +will extract and run the release automatically.</p></div> +<div class="paragraph"><p>This allows you to package the release as a single file +that can then be executed.</p></div> +<div class="paragraph"><p>This feature is currently experimental. Feedback is much +appreciated.</p></div> +<div class="sect1"> +<h2 id="_generating_the_self_extracting_archive">Generating the self-extracting archive</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To generate a self-extracting release, all you need to do +is pass the <code>SFX=1</code> variable to Make when you build 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>$ make <span style="color: #009900">SFX</span><span style="color: #990000">=</span><span style="color: #993399">1</span></tt></pre></div></div> +<div class="paragraph"><p>This will create a self-extracting archive in +<code>$RELX_OUTPUT_DIR/<name>.run</code>. For example if the release +is named <code>hello_world</code> and <code>$RELX_OUTPUT_DIR</code> is the default, +the file will be located at <code>_rel/hello_world.run</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_running_the_release">Running the release</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Simply execute the script to get started:</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>_rel/hello_world<span style="color: #990000">.</span>run +Exec<span style="color: #990000">:</span> /tmp/tmp<span style="color: #990000">.</span>3eeEq7E1ta/erts-<span style="color: #993399">8.1</span>/bin/erlexec <span style="color: #990000">...</span> +Root<span style="color: #990000">:</span> /tmp/tmp<span style="color: #990000">.</span>3eeEq7E1ta +/tmp/tmp<span style="color: #990000">.</span>3eeEq7E1ta +Erlang/OTP <span style="color: #993399">19</span> <span style="color: #990000">[</span>erts-<span style="color: #993399">8.1</span><span style="color: #990000">]</span> <span style="color: #990000">[</span><span style="font-weight: bold"><span style="color: #0000FF">source</span></span><span style="color: #990000">]</span> <span style="color: #990000">[</span><span style="color: #993399">64</span>-bit<span style="color: #990000">]</span> <span style="color: #990000">[</span>smp<span style="color: #990000">:</span><span style="color: #993399">4</span><span style="color: #990000">:</span><span style="color: #993399">4</span><span style="color: #990000">]</span> <span style="color: #990000">...</span> + +Eshell V8<span style="color: #990000">.</span><span style="color: #993399">1</span> <span style="color: #990000">(</span>abort with <span style="color: #990000">^</span>G<span style="color: #990000">)</span> +<span style="color: #990000">(</span>hello_world@localhost<span style="color: #990000">)</span><span style="color: #993399">1</span><span style="color: #990000">></span></tt></pre></div></div> +<div class="paragraph"><p>As you can see the archive is extracted to a temporary +directory before the release can be started.</p></div> +<div class="paragraph"><p>The self-extracting script currently only supports starting +the release in <code>console</code> mode.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/shell/index.html b/docs/en/erlang.mk/1/guide/shell/index.html index 28a13113..873e7b2f 100644 --- a/docs/en/erlang.mk/1/guide/shell/index.html +++ b/docs/en/erlang.mk/1/guide/shell/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Erlang shell</title> @@ -67,53 +67,72 @@ <h1 class="lined-header"><span>Erlang shell</span></h1> -<div class="paragraph"><p>Erlang.mk provides a convenient target for starting a shell
-with all the paths set properly to experiment with your code.</p></div>
-<div class="sect1">
-<h2 id="_configuration">Configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>SHELL_DEPS</code> variable can be used to define dependencies
-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"></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.
-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"></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"></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"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_usage">Usage</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To start the shell, all you need is the following 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>$ make shell</tt></pre></div></div>
-<div class="paragraph"><p>The shell can be stopped as usual with a double Ctrl+C or the
-command <code>q().</code>.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Erlang.mk provides a convenient target for starting a shell +with all the paths set properly to experiment with your code.</p></div> +<div class="sect1"> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>SHELL_DEPS</code> variable can be used to define dependencies +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="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. +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="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="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> +</div> +<div class="sect1"> +<h2 id="_usage">Usage</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To start the shell, all you need is the following 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>$ make shell</tt></pre></div></div> +<div class="paragraph"><p>The shell can be stopped as usual with a double Ctrl+C or the +command <code>q().</code>.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/updating/index.html b/docs/en/erlang.mk/1/guide/updating/index.html index 96223e32..826e1b0d 100644 --- a/docs/en/erlang.mk/1/guide/updating/index.html +++ b/docs/en/erlang.mk/1/guide/updating/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Updating Erlang.mk</title> @@ -67,95 +67,98 @@ <h1 class="lined-header"><span>Updating Erlang.mk</span></h1> -<div class="paragraph"><p>This chapter describes how to update the <em>erlang.mk</em> file
-in your repository.</p></div>
-<div class="sect1">
-<h2 id="_initial_bootstrap">Initial bootstrap</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The first time you use Erlang.mk, it will bootstrap itself.
-It always uses the most recent version for this, so you don’t
-have to update after creating your project.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_updating">Updating</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Later on though, updating becomes a necessity. Erlang.mk
-developers and contributors relentlessly improve the project
-and add new features; it would be a waste not to benefit
-from this.</p></div>
-<div class="paragraph"><p>That’s why updating Erlang.mk is so simple. All you need
-to do is to call <code>make erlang-mk</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>$ make erlang-mk
-git clone https<span style="color: #990000">:</span>//github<span style="color: #990000">.</span>com/ninenines/erlang<span style="color: #990000">.</span>mk <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build
-Cloning into <span style="color: #FF0000">'.erlang.mk.build'</span><span style="color: #990000">...</span>
-remote<span style="color: #990000">:</span> Counting objects<span style="color: #990000">:</span> <span style="color: #993399">4035</span><span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-remote<span style="color: #990000">:</span> Compressing objects<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">12</span><span style="color: #990000">/</span><span style="color: #993399">12</span><span style="color: #990000">),</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-remote<span style="color: #990000">:</span> Total <span style="color: #993399">4035</span> <span style="color: #990000">(</span>delta <span style="color: #993399">8</span><span style="color: #990000">),</span> reused <span style="color: #993399">4</span> <span style="color: #990000">(</span>delta <span style="color: #993399">4</span><span style="color: #990000">),</span> pack-reused <span style="color: #993399">4019</span>
-Receiving objects<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">4035</span><span style="color: #990000">/</span><span style="color: #993399">4035</span><span style="color: #990000">),</span> <span style="color: #993399">1.10</span> MiB <span style="color: #990000">|</span> <span style="color: #993399">1000.00</span> KiB/s<span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-Resolving deltas<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">2442</span><span style="color: #990000">/</span><span style="color: #993399">2442</span><span style="color: #990000">),</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-Checking connectivity<span style="color: #990000">...</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">[</span> -f build<span style="color: #990000">.</span>config <span style="color: #990000">];</span> <span style="font-weight: bold"><span style="color: #0000FF">then</span></span> cp build<span style="color: #990000">.</span>config <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build<span style="color: #990000">;</span> <span style="font-weight: bold"><span style="color: #0000FF">fi</span></span>
-cd <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build <span style="color: #990000">&&</span> make
-make<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]:</span> Entering directory <span style="color: #FF0000">'/home/essen/tmp/emkg/hello_joe/.erlang.mk.build'</span>
-awk <span style="color: #FF0000">'FNR==1 && NR!=1{print ""}1'</span> core/core<span style="color: #990000">.</span>mk index<span style="color: #990000">/*.</span>mk core/index<span style="color: #990000">.</span>mk core/deps<span style="color: #990000">.</span>mk plugins/protobuffs<span style="color: #990000">.</span>mk core/erlc<span style="color: #990000">.</span>mk core/docs<span style="color: #990000">.</span>mk core/test<span style="color: #990000">.</span>mk plugins/asciidoc<span style="color: #990000">.</span>mk plugins/bootstrap<span style="color: #990000">.</span>mk plugins/c_src<span style="color: #990000">.</span>mk plugins/ci<span style="color: #990000">.</span>mk plugins/ct<span style="color: #990000">.</span>mk plugins/dialyzer<span style="color: #990000">.</span>mk plugins/edoc<span style="color: #990000">.</span>mk plugins/elvis<span style="color: #990000">.</span>mk plugins/erlydtl<span style="color: #990000">.</span>mk plugins/escript<span style="color: #990000">.</span>mk plugins/eunit<span style="color: #990000">.</span>mk plugins/relx<span style="color: #990000">.</span>mk plugins/shell<span style="color: #990000">.</span>mk plugins/triq<span style="color: #990000">.</span>mk plugins/xref<span style="color: #990000">.</span>mk plugins/cover<span style="color: #990000">.</span>mk <span style="color: #990000">\</span>
- <span style="color: #990000">|</span> sed <span style="color: #FF0000">'s/^ERLANG_MK_VERSION = .*/ERLANG_MK_VERSION = 1.2.0-642-gccd2b9f/'</span> <span style="color: #990000">></span> erlang<span style="color: #990000">.</span>mk
-make<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]:</span> Leaving directory <span style="color: #FF0000">'/home/essen/tmp/emkg/hello_joe/.erlang.mk.build'</span>
-cp <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build/erlang<span style="color: #990000">.</span>mk <span style="color: #990000">.</span>/erlang<span style="color: #990000">.</span>mk
-rm -rf <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build</tt></pre></div></div>
-<div class="paragraph"><p>All that’s left to do is to commit the file!</p></div>
-<div class="paragraph"><p>Yep, it’s that easy.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_customizing_the_build">Customizing the build</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk allows you to customize which components are to be included
-in the <em>erlang.mk</em> file. The <code>WITHOUT</code> variable allows you to
-remove components from the default Erlang.mk build. The <em>build.config</em>
-file lets you define exactly what goes in (including your own code!),
-and in what order.</p></div>
-<div class="paragraph"><p>The <code>WITHOUT</code> file contains the list of components to exclude from
-the build. For example, to exclude the package index and the EDoc
-plugin when bootstrapping your 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>$ make -f erlang<span style="color: #990000">.</span>mk bootstrap <span style="color: #009900">WITHOUT</span><span style="color: #990000">=</span><span style="color: #FF0000">"index plugins/edoc"</span></tt></pre></div></div>
-<div class="paragraph"><p>The generated Erlang.mk will never include those components when
-you update it, until you change your mind and use the <code>WITHOUT</code>
-variable again when you upgrade:</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 erlang-mk <span style="color: #009900">WITHOUT</span><span style="color: #990000">=</span>index</tt></pre></div></div>
-<div class="paragraph"><p>The <em>build.config</em> file is automatically used when you bootstrap
-Erlang.mk or when you update it with <code>make erlang-mk</code>.</p></div>
-<div class="paragraph"><p>The <em>build.config</em> file contains the list of all files that will
-be built into the resulting <em>erlang.mk</em> file. You can start from
-the <a href="https://github.com/ninenines/erlang.mk/blob/master/build.config">most recent version</a>
-and customize to your needs.</p></div>
-<div class="paragraph"><p>You can also name the file differently or put it in a separate folder
-by modifying the value for <code>ERLANG_MK_BUILD_CONFIG</code>. You can also
-tell Erlang.mk to use a different temporary directory by changing
-the <code>ERLANG_MK_BUILD_DIR</code> variable.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter describes how to update the <em>erlang.mk</em> file +in your repository.</p></div> +<div class="sect1"> +<h2 id="_initial_bootstrap">Initial bootstrap</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The first time you use Erlang.mk, it will bootstrap itself. +It always uses the most recent version for this, so you don’t +have to update after creating your project.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_updating">Updating</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Later on though, updating becomes a necessity. Erlang.mk +developers and contributors relentlessly improve the project +and add new features; it would be a waste not to benefit +from this.</p></div> +<div class="paragraph"><p>That’s why updating Erlang.mk is so simple. All you need +to do is to call <code>make erlang-mk</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>$ make erlang-mk +git clone https<span style="color: #990000">:</span>//github<span style="color: #990000">.</span>com/ninenines/erlang<span style="color: #990000">.</span>mk <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build +Cloning into <span style="color: #FF0000">'.erlang.mk.build'</span><span style="color: #990000">...</span> +remote<span style="color: #990000">:</span> Counting objects<span style="color: #990000">:</span> <span style="color: #993399">4035</span><span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +remote<span style="color: #990000">:</span> Compressing objects<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">12</span><span style="color: #990000">/</span><span style="color: #993399">12</span><span style="color: #990000">),</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +remote<span style="color: #990000">:</span> Total <span style="color: #993399">4035</span> <span style="color: #990000">(</span>delta <span style="color: #993399">8</span><span style="color: #990000">),</span> reused <span style="color: #993399">4</span> <span style="color: #990000">(</span>delta <span style="color: #993399">4</span><span style="color: #990000">),</span> pack-reused <span style="color: #993399">4019</span> +Receiving objects<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">4035</span><span style="color: #990000">/</span><span style="color: #993399">4035</span><span style="color: #990000">),</span> <span style="color: #993399">1.10</span> MiB <span style="color: #990000">|</span> <span style="color: #993399">1000.00</span> KiB/s<span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +Resolving deltas<span style="color: #990000">:</span> <span style="color: #993399">100</span><span style="color: #990000">%</span> <span style="color: #990000">(</span><span style="color: #993399">2442</span><span style="color: #990000">/</span><span style="color: #993399">2442</span><span style="color: #990000">),</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +Checking connectivity<span style="color: #990000">...</span> <span style="font-weight: bold"><span style="color: #0000FF">done</span></span><span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">[</span> -f build<span style="color: #990000">.</span>config <span style="color: #990000">];</span> <span style="font-weight: bold"><span style="color: #0000FF">then</span></span> cp build<span style="color: #990000">.</span>config <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build<span style="color: #990000">;</span> <span style="font-weight: bold"><span style="color: #0000FF">fi</span></span> +cd <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build <span style="color: #990000">&&</span> make +make<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]:</span> Entering directory <span style="color: #FF0000">'/home/essen/tmp/emkg/hello_joe/.erlang.mk.build'</span> +awk <span style="color: #FF0000">'FNR==1 && NR!=1{print ""}1'</span> core/core<span style="color: #990000">.</span>mk index<span style="color: #990000">/*.</span>mk core/index<span style="color: #990000">.</span>mk core/deps<span style="color: #990000">.</span>mk plugins/protobuffs<span style="color: #990000">.</span>mk core/erlc<span style="color: #990000">.</span>mk core/docs<span style="color: #990000">.</span>mk core/test<span style="color: #990000">.</span>mk plugins/asciidoc<span style="color: #990000">.</span>mk plugins/bootstrap<span style="color: #990000">.</span>mk plugins/c_src<span style="color: #990000">.</span>mk plugins/ci<span style="color: #990000">.</span>mk plugins/ct<span style="color: #990000">.</span>mk plugins/dialyzer<span style="color: #990000">.</span>mk plugins/edoc<span style="color: #990000">.</span>mk plugins/elvis<span style="color: #990000">.</span>mk plugins/erlydtl<span style="color: #990000">.</span>mk plugins/escript<span style="color: #990000">.</span>mk plugins/eunit<span style="color: #990000">.</span>mk plugins/relx<span style="color: #990000">.</span>mk plugins/shell<span style="color: #990000">.</span>mk plugins/triq<span style="color: #990000">.</span>mk plugins/xref<span style="color: #990000">.</span>mk plugins/cover<span style="color: #990000">.</span>mk <span style="color: #990000">\</span> + <span style="color: #990000">|</span> sed <span style="color: #FF0000">'s/^ERLANG_MK_VERSION = .*/ERLANG_MK_VERSION = 1.2.0-642-gccd2b9f/'</span> <span style="color: #990000">></span> erlang<span style="color: #990000">.</span>mk +make<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]:</span> Leaving directory <span style="color: #FF0000">'/home/essen/tmp/emkg/hello_joe/.erlang.mk.build'</span> +cp <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build/erlang<span style="color: #990000">.</span>mk <span style="color: #990000">.</span>/erlang<span style="color: #990000">.</span>mk +rm -rf <span style="color: #990000">.</span>erlang<span style="color: #990000">.</span>mk<span style="color: #990000">.</span>build</tt></pre></div></div> +<div class="paragraph"><p>All that’s left to do is to commit the file!</p></div> +<div class="paragraph"><p>Yep, it’s that easy.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_customizing_the_build">Customizing the build</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk allows you to customize which components are to be included +in the <em>erlang.mk</em> file. The <code>WITHOUT</code> variable allows you to +remove components from the default Erlang.mk build. The <em>build.config</em> +file lets you define exactly what goes in (including your own code!), +and in what order.</p></div> +<div class="paragraph"><p>The <code>WITHOUT</code> file contains the list of components to exclude from +the build. For example, to exclude the package index and the EDoc +plugin when bootstrapping your 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>$ make -f erlang<span style="color: #990000">.</span>mk bootstrap <span style="color: #009900">WITHOUT</span><span style="color: #990000">=</span><span style="color: #FF0000">"index plugins/edoc"</span></tt></pre></div></div> +<div class="paragraph"><p>The generated Erlang.mk will never include those components when +you update it, until you change your mind and use the <code>WITHOUT</code> +variable again when you upgrade:</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 erlang-mk <span style="color: #009900">WITHOUT</span><span style="color: #990000">=</span>index</tt></pre></div></div> +<div class="paragraph"><p>The <em>build.config</em> file is automatically used when you bootstrap +Erlang.mk or when you update it with <code>make erlang-mk</code>.</p></div> +<div class="paragraph"><p>The <em>build.config</em> file contains the list of all files that will +be built into the resulting <em>erlang.mk</em> file. You can start from +the <a href="https://github.com/ninenines/erlang.mk/blob/master/build.config">most recent version</a> +and customize to your needs.</p></div> +<div class="paragraph"><p>You can also name the file differently or put it in a separate folder +by modifying the value for <code>ERLANG_MK_BUILD_CONFIG</code>. You can also +tell Erlang.mk to use a different temporary directory by changing +the <code>ERLANG_MK_BUILD_DIR</code> variable.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/why/index.html b/docs/en/erlang.mk/1/guide/why/index.html index bc1881cf..0c73daaf 100644 --- a/docs/en/erlang.mk/1/guide/why/index.html +++ b/docs/en/erlang.mk/1/guide/why/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Why Erlang.mk</title> @@ -67,92 +67,95 @@ <h1 class="lined-header"><span>Why Erlang.mk</span></h1> -<div class="paragraph"><p>Why would you choose Erlang.mk, if not for its
-<a href="../overview">many features</a>? This chapter will
-attempt to answer that.</p></div>
-<div class="sect1">
-<h2 id="_erlang_mk_is_fast">Erlang.mk is fast</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk is as fast as it gets.</p></div>
-<div class="paragraph"><p>Erlang.mk will group the compilation of files so as to avoid
-running the BEAM more than necessary. This saves many seconds
-compared to traditional Makefiles, even on small projects.</p></div>
-<div class="paragraph"><p>Erlang.mk will not try to be too smart. It provides a simple
-solution that works for most people, and gives additional
-options for projects that run into edge cases, often in the
-form of extra variables or rules to be defined.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_erlang_mk_gives_you_the_full_power_of_unix">Erlang.mk gives you the full power of Unix</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk is a Makefile.</p></div>
-<div class="paragraph"><p>You could use Erlang.mk directly without configuring anything
-and it would just work. But you can also extend it greatly
-either through configuration or hooks, and you can of course
-add your own rules to the Makefile.</p></div>
-<div class="paragraph"><p>In all cases: for configuration, hooks or custom rules, you
-have all the power of Unix at your disposal, and can call
-any utility <em>or even any language interpreter</em> you want,
-every time you need to. Erlang.mk also allows you to write
-scripts in this small language called Erlang directly inside
-your Makefile if you ever need to…</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_erlang_mk_is_a_text_file">Erlang.mk is a text file</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk is a Makefile.</p></div>
-<div class="paragraph"><p>Which means Erlang.mk is a simple text file. You can edit a
-text file. Nothing stops you. If you run into any bug, or
-behavior that does not suit you, you can just open the
-<em>erlang.mk</em> file in your favorite editor, fix and/or comment
-a few lines, save, and try again. It’s as simple as it gets.</p></div>
-<div class="paragraph"><p>Currently using a binary build tool? Good luck with that.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_erlang_mk_can_manage_erlang_itself">Erlang.mk can manage Erlang itself</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk isn’t written in Erlang.</p></div>
-<div class="paragraph"><p>That’s not a good thing, you say? Well, here’s one thing
-that Erlang.mk and Makefiles can do for you that Erlang
-build tool can’t easily: choose what version of Erlang is
-to be used for compiling the project.</p></div>
-<div class="paragraph"><p>This really is a one-liner in Erlang.mk (a few more lines
-if you also let it download and build Erlang directly)
-and allows for even greater things, like testing your
-project across all supported Erlang versions in one small
-command: <code>make -k ci</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_erlang_mk_can_do_more_than_erlang">Erlang.mk can do more than Erlang</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Erlang.mk doesn’t care what your dependencies are written in.</p></div>
-<div class="paragraph"><p>Erlang.mk will happily compile any dependency, as long as
-they come with a Makefile. The dependency can be written
-in C, C++ or even Javascript… Who cares, really? If you
-need Erlang.mk to fetch it, then Erlang.mk will fetch it
-and compile it as needed.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_erlang_mk_integrates_nicely_in_make_and_automake_projects">Erlang.mk integrates nicely in Make and Automake projects</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>If you are planning to put your project in the middle of
-a Make or Automake-based build environment, then the most
-logical thing to do is to use a Makefile.</p></div>
-<div class="paragraph"><p>Erlang.mk will happily sit in such an environment and behave
-as you expect it to.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Why would you choose Erlang.mk, if not for its +<a href="../overview">many features</a>? This chapter will +attempt to answer that.</p></div> +<div class="sect1"> +<h2 id="_erlang_mk_is_fast">Erlang.mk is fast</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk is as fast as it gets.</p></div> +<div class="paragraph"><p>Erlang.mk will group the compilation of files so as to avoid +running the BEAM more than necessary. This saves many seconds +compared to traditional Makefiles, even on small projects.</p></div> +<div class="paragraph"><p>Erlang.mk will not try to be too smart. It provides a simple +solution that works for most people, and gives additional +options for projects that run into edge cases, often in the +form of extra variables or rules to be defined.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_erlang_mk_gives_you_the_full_power_of_unix">Erlang.mk gives you the full power of Unix</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk is a Makefile.</p></div> +<div class="paragraph"><p>You could use Erlang.mk directly without configuring anything +and it would just work. But you can also extend it greatly +either through configuration or hooks, and you can of course +add your own rules to the Makefile.</p></div> +<div class="paragraph"><p>In all cases: for configuration, hooks or custom rules, you +have all the power of Unix at your disposal, and can call +any utility <em>or even any language interpreter</em> you want, +every time you need to. Erlang.mk also allows you to write +scripts in this small language called Erlang directly inside +your Makefile if you ever need to…</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_erlang_mk_is_a_text_file">Erlang.mk is a text file</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk is a Makefile.</p></div> +<div class="paragraph"><p>Which means Erlang.mk is a simple text file. You can edit a +text file. Nothing stops you. If you run into any bug, or +behavior that does not suit you, you can just open the +<em>erlang.mk</em> file in your favorite editor, fix and/or comment +a few lines, save, and try again. It’s as simple as it gets.</p></div> +<div class="paragraph"><p>Currently using a binary build tool? Good luck with that.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_erlang_mk_can_manage_erlang_itself">Erlang.mk can manage Erlang itself</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk isn’t written in Erlang.</p></div> +<div class="paragraph"><p>That’s not a good thing, you say? Well, here’s one thing +that Erlang.mk and Makefiles can do for you that Erlang +build tool can’t easily: choose what version of Erlang is +to be used for compiling the project.</p></div> +<div class="paragraph"><p>This really is a one-liner in Erlang.mk (a few more lines +if you also let it download and build Erlang directly) +and allows for even greater things, like testing your +project across all supported Erlang versions in one small +command: <code>make -k ci</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_erlang_mk_can_do_more_than_erlang">Erlang.mk can do more than Erlang</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Erlang.mk doesn’t care what your dependencies are written in.</p></div> +<div class="paragraph"><p>Erlang.mk will happily compile any dependency, as long as +they come with a Makefile. The dependency can be written +in C, C++ or even Javascript… Who cares, really? If you +need Erlang.mk to fetch it, then Erlang.mk will fetch it +and compile it as needed.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_erlang_mk_integrates_nicely_in_make_and_automake_projects">Erlang.mk integrates nicely in Make and Automake projects</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you are planning to put your project in the middle of +a Make or Automake-based build environment, then the most +logical thing to do is to use a Makefile.</p></div> +<div class="paragraph"><p>Erlang.mk will happily sit in such an environment and behave +as you expect it to.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/guide/xref/index.html b/docs/en/erlang.mk/1/guide/xref/index.html index 6cb0e2ec..7913e3d9 100644 --- a/docs/en/erlang.mk/1/guide/xref/index.html +++ b/docs/en/erlang.mk/1/guide/xref/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Xref</title> @@ -67,13 +67,16 @@ <h1 class="lined-header"><span>Xref</span></h1> -<div class="paragraph"><p>Placeholder chapter.</p></div>
+<div class="paragraph"><p>Placeholder chapter.</p></div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/erlang.mk/1/index.html b/docs/en/erlang.mk/1/index.html index d87c4243..0194031a 100644 --- a/docs/en/erlang.mk/1/index.html +++ b/docs/en/erlang.mk/1/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file diff --git a/docs/en/erlang.mk/index.html b/docs/en/erlang.mk/index.html index d87c4243..0194031a 100644 --- a/docs/en/erlang.mk/index.html +++ b/docs/en/erlang.mk/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file diff --git a/docs/en/gun/1.0/guide/connect/index.html b/docs/en/gun/1.0/guide/connect/index.html index 50035be4..62b1619d 100644 --- a/docs/en/gun/1.0/guide/connect/index.html +++ b/docs/en/gun/1.0/guide/connect/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Connection</title> @@ -67,174 +67,177 @@ <h1 class="lined-header"><span>Connection</span></h1> -<div class="paragraph"><p>This chapter describes how to open, monitor and close
-a connection using the Gun client.</p></div>
-<div class="sect1">
-<h2 id="_gun_connections">Gun connections</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Gun is designed with the HTTP/2 and Websocket protocols in mind.
-They are built for long-running connections that allow concurrent
-exchange of data, either in the form of request/responses for
-HTTP/2 or in the form of messages for Websocket.</p></div>
-<div class="paragraph"><p>A Gun connection is an Erlang process that manages a socket to
-a remote endpoint. This Gun connection is owned by a user
-process that is called the <em>owner</em> of the connection, and is
-managed by the supervision tree of the <code>gun</code> application.</p></div>
-<div class="paragraph"><p>The owner process communicates with the Gun connection
-by calling functions from the module <code>gun</code>. All functions
-perform their respective operations asynchronously. The Gun
-connection will send Erlang messages to the owner process
-whenever needed.</p></div>
-<div class="paragraph"><p>When the remote endpoint closes the connection, Gun attempts
-to reconnect automatically.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_opening_a_new_connection">Opening a new connection</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>gun:open/{2,3}</code> function must be used to open a connection.</p></div>
-<div class="listingblock">
-<div class="title">Opening a connection to example.org on port 443</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: #FF6600">ok</span>, <span style="color: #009900">ConnPid</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:open</span></span>(<span style="color: #FF0000">"example.org"</span>, <span style="color: #993399">443</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>If the port given is 443, Gun will attempt to connect using
-SSL. The protocol will be selected automatically using the
-ALPN extension for TLS. By default Gun supports HTTP/2
-and HTTP/1.1 when connecting using SSL.</p></div>
-<div class="paragraph"><p>For any other port, Gun will attempt to connect using TCP
-and will use the HTTP/1.1 protocol.</p></div>
-<div class="paragraph"><p>The transport and protocol used can be overriden using
-options. The manual documents all available options.</p></div>
-<div class="paragraph"><p>Options can be provided as a third argument, and take the
-form of a map.</p></div>
-<div class="listingblock">
-<div class="title">Opening an SSL connection to example.org on port 8443</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: #FF6600">ok</span>, <span style="color: #009900">ConnPid</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:open</span></span>(<span style="color: #FF0000">"example.org"</span>, <span style="color: #993399">8443</span>, #{<span style="color: #0000FF">transport</span><span style="color: #990000">=></span><span style="color: #FF6600">ssl</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_waiting_for_the_connection_to_be_established">Waiting for the connection to be established</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>When Gun successfully connects to the server, it sends a
-<code>gun_up</code> message with the protocol that has been selected
-for the connection.</p></div>
-<div class="paragraph"><p>Gun provides the functions <code>gun:await_up/{1,2,3}</code> that wait
-for the <code>gun_up</code> message. They can optionally take a monitor
-reference and/or timeout value. If no monitor is provided,
-one will be created for the duration of the function call.</p></div>
-<div class="listingblock">
-<div class="title">Synchronous opening of a connection</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: #FF6600">ok</span>, <span style="color: #009900">ConnPid</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:open</span></span>(<span style="color: #FF0000">"example.org"</span>, <span style="color: #993399">443</span>),
-{<span style="color: #FF6600">ok</span>, <span style="color: #009900">Protocol</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:await_up</span></span>(<span style="color: #009900">ConnPid</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_handling_connection_loss">Handling connection loss</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>When the connection is lost, Gun will send a <code>gun_down</code>
-message indicating the current protocol, the reason the
-connection was lost and two list of stream references.</p></div>
-<div class="paragraph"><p>The first list indicates open streams that <em>may</em> have been
-processed by the server. The second list indicates open
-streams that the server did not process.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_monitoring_the_connection_process">Monitoring the connection process</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>@todo Gun should detect the owner process being killed</p></div>
-<div class="paragraph"><p>Because software errors are unavoidable, it is important to
-detect when the Gun process crashes. It is also important
-to detect when it exits normally. Erlang provides two ways
-to do that: links and monitors.</p></div>
-<div class="paragraph"><p>Gun leaves you the choice as to which one will be used.
-However, if you use the <code>gun:await/{2,3}</code> or <code>gun:await_body/{2,3}</code>
-functions, a monitor may be used for you to avoid getting
-stuck waiting for a message that will never come.</p></div>
-<div class="paragraph"><p>If you choose to monitor yourself you can do it on a permanent
-basis rather than on every message you will receive, saving
-resources. Indeed, the <code>gun:await/{3,4}</code> and <code>gun:await_body/{3,4}</code>
-functions both accept a monitor argument if you have one already.</p></div>
-<div class="listingblock">
-<div class="title">Monitoring the connection process</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: #FF6600">ok</span>, <span style="color: #009900">ConnPid</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:open</span></span>(<span style="color: #FF0000">"example.org"</span>, <span style="color: #993399">443</span>)<span style="color: #990000">.</span>
-<span style="color: #009900">MRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">monitor</span></span>(<span style="font-weight: bold"><span style="color: #000080">process</span></span>, <span style="color: #009900">ConnPid</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>This monitor reference can be kept and used until the connection
-process exits.</p></div>
-<div class="listingblock">
-<div class="title">Handling <code>DOWN</code> messages</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="font-weight: bold"><span style="color: #0000FF">receive</span></span>
- <span style="font-style: italic"><span style="color: #9A1900">%% Receive Gun messages here...</span></span>
- {<span style="color: #FF6600">'DOWN'</span>, <span style="color: #009900">Mref</span>, <span style="font-weight: bold"><span style="color: #000080">process</span></span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">error_logger:error_msg</span></span>(<span style="color: #FF0000">"Oops!"</span>),
- <span style="font-weight: bold"><span style="color: #000080">exit</span></span>(<span style="color: #009900">Reason</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>What to do when you receive a <code>DOWN</code> message is entirely up to you.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_closing_the_connection_abruptly">Closing the connection abruptly</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The connection can be stopped abruptly at any time by calling
-the <code>gun:close/1</code> function.</p></div>
-<div class="listingblock">
-<div class="title">Immediate closing of the connection</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="font-weight: bold"><span style="color: #000000">gun:close</span></span>(<span style="color: #009900">ConnPid</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The process is stopped immediately without having a chance to
-perform the protocol’s closing handshake, if any.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_closing_the_connection_gracefully">Closing the connection gracefully</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The connection can also be stopped gracefully by calling the
-<code>gun:shutdown/1</code> function.</p></div>
-<div class="listingblock">
-<div class="title">Graceful shutdown of the connection</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="font-weight: bold"><span style="color: #000000">gun:shutdown</span></span>(<span style="color: #009900">ConnPid</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Gun will refuse any new requests or messages after you call
-this function. It will however continue to send you messages
-for existing streams until they are all completed.</p></div>
-<div class="paragraph"><p>For example if you performed a GET request just before calling
-<code>gun:shutdown/1</code>, you will still receive the response before
-Gun closes the connection.</p></div>
-<div class="paragraph"><p>If you set a monitor beforehand, you will receive a message
-when the connection has been closed.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter describes how to open, monitor and close +a connection using the Gun client.</p></div> +<div class="sect1"> +<h2 id="_gun_connections">Gun connections</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Gun is designed with the HTTP/2 and Websocket protocols in mind. +They are built for long-running connections that allow concurrent +exchange of data, either in the form of request/responses for +HTTP/2 or in the form of messages for Websocket.</p></div> +<div class="paragraph"><p>A Gun connection is an Erlang process that manages a socket to +a remote endpoint. This Gun connection is owned by a user +process that is called the <em>owner</em> of the connection, and is +managed by the supervision tree of the <code>gun</code> application.</p></div> +<div class="paragraph"><p>The owner process communicates with the Gun connection +by calling functions from the module <code>gun</code>. All functions +perform their respective operations asynchronously. The Gun +connection will send Erlang messages to the owner process +whenever needed.</p></div> +<div class="paragraph"><p>When the remote endpoint closes the connection, Gun attempts +to reconnect automatically.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_opening_a_new_connection">Opening a new connection</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>gun:open/{2,3}</code> function must be used to open a connection.</p></div> +<div class="listingblock"> +<div class="title">Opening a connection to example.org on port 443</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: #FF6600">ok</span>, <span style="color: #009900">ConnPid</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:open</span></span>(<span style="color: #FF0000">"example.org"</span>, <span style="color: #993399">443</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>If the port given is 443, Gun will attempt to connect using +SSL. The protocol will be selected automatically using the +ALPN extension for TLS. By default Gun supports HTTP/2 +and HTTP/1.1 when connecting using SSL.</p></div> +<div class="paragraph"><p>For any other port, Gun will attempt to connect using TCP +and will use the HTTP/1.1 protocol.</p></div> +<div class="paragraph"><p>The transport and protocol used can be overriden using +options. The manual documents all available options.</p></div> +<div class="paragraph"><p>Options can be provided as a third argument, and take the +form of a map.</p></div> +<div class="listingblock"> +<div class="title">Opening an SSL connection to example.org on port 8443</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: #FF6600">ok</span>, <span style="color: #009900">ConnPid</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:open</span></span>(<span style="color: #FF0000">"example.org"</span>, <span style="color: #993399">8443</span>, #{<span style="color: #0000FF">transport</span><span style="color: #990000">=></span><span style="color: #FF6600">ssl</span>})<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_waiting_for_the_connection_to_be_established">Waiting for the connection to be established</h2> +<div class="sectionbody"> +<div class="paragraph"><p>When Gun successfully connects to the server, it sends a +<code>gun_up</code> message with the protocol that has been selected +for the connection.</p></div> +<div class="paragraph"><p>Gun provides the functions <code>gun:await_up/{1,2,3}</code> that wait +for the <code>gun_up</code> message. They can optionally take a monitor +reference and/or timeout value. If no monitor is provided, +one will be created for the duration of the function call.</p></div> +<div class="listingblock"> +<div class="title">Synchronous opening of a connection</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: #FF6600">ok</span>, <span style="color: #009900">ConnPid</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:open</span></span>(<span style="color: #FF0000">"example.org"</span>, <span style="color: #993399">443</span>), +{<span style="color: #FF6600">ok</span>, <span style="color: #009900">Protocol</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:await_up</span></span>(<span style="color: #009900">ConnPid</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_handling_connection_loss">Handling connection loss</h2> +<div class="sectionbody"> +<div class="paragraph"><p>When the connection is lost, Gun will send a <code>gun_down</code> +message indicating the current protocol, the reason the +connection was lost and two list of stream references.</p></div> +<div class="paragraph"><p>The first list indicates open streams that <em>may</em> have been +processed by the server. The second list indicates open +streams that the server did not process.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_monitoring_the_connection_process">Monitoring the connection process</h2> +<div class="sectionbody"> +<div class="paragraph"><p>@todo Gun should detect the owner process being killed</p></div> +<div class="paragraph"><p>Because software errors are unavoidable, it is important to +detect when the Gun process crashes. It is also important +to detect when it exits normally. Erlang provides two ways +to do that: links and monitors.</p></div> +<div class="paragraph"><p>Gun leaves you the choice as to which one will be used. +However, if you use the <code>gun:await/{2,3}</code> or <code>gun:await_body/{2,3}</code> +functions, a monitor may be used for you to avoid getting +stuck waiting for a message that will never come.</p></div> +<div class="paragraph"><p>If you choose to monitor yourself you can do it on a permanent +basis rather than on every message you will receive, saving +resources. Indeed, the <code>gun:await/{3,4}</code> and <code>gun:await_body/{3,4}</code> +functions both accept a monitor argument if you have one already.</p></div> +<div class="listingblock"> +<div class="title">Monitoring the connection process</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: #FF6600">ok</span>, <span style="color: #009900">ConnPid</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:open</span></span>(<span style="color: #FF0000">"example.org"</span>, <span style="color: #993399">443</span>)<span style="color: #990000">.</span> +<span style="color: #009900">MRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">monitor</span></span>(<span style="font-weight: bold"><span style="color: #000080">process</span></span>, <span style="color: #009900">ConnPid</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>This monitor reference can be kept and used until the connection +process exits.</p></div> +<div class="listingblock"> +<div class="title">Handling <code>DOWN</code> messages</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="font-weight: bold"><span style="color: #0000FF">receive</span></span> + <span style="font-style: italic"><span style="color: #9A1900">%% Receive Gun messages here...</span></span> + {<span style="color: #FF6600">'DOWN'</span>, <span style="color: #009900">Mref</span>, <span style="font-weight: bold"><span style="color: #000080">process</span></span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">error_logger:error_msg</span></span>(<span style="color: #FF0000">"Oops!"</span>), + <span style="font-weight: bold"><span style="color: #000080">exit</span></span>(<span style="color: #009900">Reason</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>What to do when you receive a <code>DOWN</code> message is entirely up to you.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_closing_the_connection_abruptly">Closing the connection abruptly</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The connection can be stopped abruptly at any time by calling +the <code>gun:close/1</code> function.</p></div> +<div class="listingblock"> +<div class="title">Immediate closing of the connection</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="font-weight: bold"><span style="color: #000000">gun:close</span></span>(<span style="color: #009900">ConnPid</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The process is stopped immediately without having a chance to +perform the protocol’s closing handshake, if any.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_closing_the_connection_gracefully">Closing the connection gracefully</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The connection can also be stopped gracefully by calling the +<code>gun:shutdown/1</code> function.</p></div> +<div class="listingblock"> +<div class="title">Graceful shutdown of the connection</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="font-weight: bold"><span style="color: #000000">gun:shutdown</span></span>(<span style="color: #009900">ConnPid</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Gun will refuse any new requests or messages after you call +this function. It will however continue to send you messages +for existing streams until they are all completed.</p></div> +<div class="paragraph"><p>For example if you performed a GET request just before calling +<code>gun:shutdown/1</code>, you will still receive the response before +Gun closes the connection.</p></div> +<div class="paragraph"><p>If you set a monitor beforehand, you will receive a message +when the connection has been closed.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/gun/1.0/guide/http/index.html b/docs/en/gun/1.0/guide/http/index.html index 668d3ff6..bbdb81ed 100644 --- a/docs/en/gun/1.0/guide/http/index.html +++ b/docs/en/gun/1.0/guide/http/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: HTTP</title> @@ -67,402 +67,405 @@ <h1 class="lined-header"><span>HTTP</span></h1> -<div class="paragraph"><p>This chapter describes how to use the Gun client for
-communicating with an HTTP/1.1 or HTTP/2 server.</p></div>
-<div class="sect1">
-<h2 id="_streams">Streams</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Every time a request is initiated, Gun creates a <em>stream</em>.
-A <em>stream reference</em> uniquely identifies a set of request and
-response(s) and must be used to perform additional operations
-with a stream or to identify its messages.</p></div>
-<div class="paragraph"><p>Stream references use the Erlang <em>reference</em> data type and
-are therefore unique.</p></div>
-<div class="paragraph"><p>Streams can be canceled at any time. This will stop any further
-messages from being sent to the owner process. Depending on
-its capabilities, the server will also be instructed to cancel
-the request.</p></div>
-<div class="paragraph"><p>Canceling a stream may result in Gun dropping the connection
-temporarily, to avoid uploading or downloading data that will
-not be used.</p></div>
-<div class="listingblock">
-<div class="title">Cancelling a stream</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="font-weight: bold"><span style="color: #000000">gun:cancel</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_sending_requests">Sending requests</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Gun provides many convenient functions for performing common
-operations, like GET, POST or DELETE. It also provides a
-general purpose function in case you need other methods.</p></div>
-<div class="paragraph"><p>The availability of these methods on the server can vary
-depending on the software used but also on a per-resource
-basis.</p></div>
-<div class="paragraph"><p>Gun will automatically set a few headers depending on the
-method used. For all methods however it will set the host
-header if it has not been provided in the request arguments.</p></div>
-<div class="paragraph"><p>This section focuses on the act of sending a request. The
-handling of responses will be explained further on.</p></div>
-<div class="sect3">
-<h4 id="_get_and_head">GET and HEAD</h4>
-<div class="paragraph"><p>Use <code>gun:get/{2,3,4}</code> to request a resource.</p></div>
-<div class="listingblock">
-<div class="title">GET "/organizations/ninenines"</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">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:get</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">GET "/organizations/ninenines" with custom headers</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">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:get</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>, [
- {<span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"application/json"</span>},
- {<span style="color: #990000"><<</span><span style="color: #FF0000">"user-agent"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"revolver/1.0"</span>}
-])<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Note that the list of headers has the field name as a binary.
-The field value is iodata, which is either a binary or an
-iolist.</p></div>
-<div class="paragraph"><p>Use <code>gun:head/{2,3,4}</code> if you don’t need the response body.</p></div>
-<div class="listingblock">
-<div class="title">HEAD "/organizations/ninenines"</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">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:head</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">HEAD "/organizations/ninenines" with custom headers</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">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:head</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>, [
- {<span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"application/json"</span>},
- {<span style="color: #990000"><<</span><span style="color: #FF0000">"user-agent"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"revolver/1.0"</span>}
-])<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>It is not possible to send a request body with a GET or HEAD
-request.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_post_put_and_patch">POST, PUT and PATCH</h4>
-<div class="paragraph"><p>HTTP defines three methods to create or update a resource.</p></div>
-<div class="paragraph"><p>POST is generally used when the resource identifier (URI) isn’t known
-in advance when creating the resource. POST can also be used to
-replace an existing resource, although PUT is more appropriate
-in that situation.</p></div>
-<div class="paragraph"><p>PUT creates or replaces a resource identified by the URI.</p></div>
-<div class="paragraph"><p>PATCH provides instructions on how to modify the resource.</p></div>
-<div class="paragraph"><p>Both POST and PUT send the entire resource representation in their
-request body. The PATCH method can be used when this is not
-desirable. The request body of a PATCH method may be a partial
-representation or a list of instructions on how to update the
-resource.</p></div>
-<div class="paragraph"><p>The <code>gun:post/{4,5}</code>, <code>gun:put/{4,5}</code> and <code>gun:patch/{4,5}</code> functions
-take a body as their fourth argument. These functions do
-not require any body-specific header to be set, although
-it is always recommended to set the content-type header.
-Gun will set the other headers automatically.</p></div>
-<div class="paragraph"><p>In this and the following examples in this section, <code>gun:post</code>
-can be replaced by <code>gun:put</code> or <code>gun:patch</code> for performing
-a PUT or PATCH request, respectively.</p></div>
-<div class="listingblock">
-<div class="title">POST "/organizations/ninenines"</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">Body</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"{\"msg\": \"Hello world!\"}"</span>,
-<span style="color: #009900">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:post</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>, [
- {<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"application/json"</span>}
-], <span style="color: #009900">Body</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The <code>gun:post/3</code>, <code>gun:put/3</code> and <code>gun:patch/3</code> functions
-do not take a body in their arguments. If a body is to be
-provided later on, using the <code>gun:data/4</code> function, then
-the request headers must indicate this. This can be done
-by setting the content-length or content-type request
-headers. If these headers are not set then Gun will assume
-the request has no body.</p></div>
-<div class="paragraph"><p>It is recommended to send the content-length header if you
-know it in advance, although this is not required. If it
-is not set, HTTP/1.1 will use the chunked transfer-encoding,
-and HTTP/2 will continue normally as it is chunked by design.</p></div>
-<div class="listingblock">
-<div class="title">POST "/organizations/ninenines" with delayed body</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">Body</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"{\"msg\": \"Hello world!\"}"</span>,
-<span style="color: #009900">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:post</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>, [
- {<span style="color: #990000"><<</span><span style="color: #FF0000">"content-length"</span><span style="color: #990000">>></span>, <span style="font-weight: bold"><span style="color: #000000">integer_to_binary</span></span>(<span style="font-weight: bold"><span style="color: #000080">length</span></span>(<span style="color: #009900">Body</span>))},
- {<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"application/json"</span>}
-]),
-<span style="font-weight: bold"><span style="color: #000000">gun:data</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Body</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The atom <code>fin</code> indicates this is the last chunk of data to
-be sent. You can call the <code>gun:data/4</code> function as many
-times as needed until you have sent the entire body. The
-last call must use <code>fin</code> and all the previous calls must
-use <code>nofin</code>. The last chunk may be empty.</p></div>
-<div class="paragraph"><p>@todo what to do about empty chunk, ignore?</p></div>
-<div class="listingblock">
-<div class="title">Streaming the request body</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="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #009900">Filepath</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">IoDevice</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:open</span></span>(<span style="color: #009900">Filepath</span>, [<span style="color: #FF6600">read</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #FF6600">raw</span>]),
- <span style="font-weight: bold"><span style="color: #000000">do_sendfile</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #009900">IoDevice</span>)<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">do_sendfile</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #009900">IoDevice</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">file:read</span></span>(<span style="color: #009900">IoDevice</span>, <span style="color: #993399">8000</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- <span style="color: #FF6600">eof</span> <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">gun:data</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #FF6600">fin</span>, <span style="color: #990000"><<>></span>),
- <span style="font-weight: bold"><span style="color: #000000">file:close</span></span>(<span style="color: #009900">IoDevice</span>);
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Bin</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">gun:data</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Bin</span>),
- <span style="font-weight: bold"><span style="color: #000000">do_sendfile</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #009900">IoDevice</span>)
- <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-<div class="sect3">
-<h4 id="_delete">DELETE</h4>
-<div class="paragraph"><p>Use <code>gun:delete/{2,3,4}</code> to delete a resource.</p></div>
-<div class="listingblock">
-<div class="title">DELETE "/organizations/ninenines"</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">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:delete</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">DELETE "/organizations/ninenines" with custom headers</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">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:delete</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>, [
- {<span style="color: #990000"><<</span><span style="color: #FF0000">"user-agent"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"revolver/1.0"</span>}
-])<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-<div class="sect3">
-<h4 id="_options">OPTIONS</h4>
-<div class="paragraph"><p>Use <code>gun:options/{2,3}</code> to request information about a resource.</p></div>
-<div class="listingblock">
-<div class="title">OPTIONS "/organizations/ninenines"</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">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:options</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">OPTIONS "/organizations/ninenines" with custom headers</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">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:options</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>, [
- {<span style="color: #990000"><<</span><span style="color: #FF0000">"user-agent"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"revolver/1.0"</span>}
-])<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can also use this function to request information about
-the server itself.</p></div>
-<div class="listingblock">
-<div class="title">OPTIONS "*"</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">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:options</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"*"</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-<div class="sect3">
-<h4 id="_requests_with_an_arbitrary_method">Requests with an arbitrary method</h4>
-<div class="paragraph"><p>The <code>gun:request/{4,5,6}</code> function can be used to send requests
-with a configurable method name. It is mostly useful when you
-need a method that Gun does not understand natively.</p></div>
-<div class="listingblock">
-<div class="title">Example of a TRACE request</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="font-weight: bold"><span style="color: #000000">gun:request</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"TRACE"</span>, <span style="color: #FF0000">"/"</span>, [
- {<span style="color: #990000"><<</span><span style="color: #FF0000">"max-forwards"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"30"</span>}
-])<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_processing_responses">Processing responses</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>All data received from the server is sent to the owner
-process as a message. First a <code>gun_response</code> message is sent,
-followed by zero or more <code>gun_data</code> messages. If something goes wrong,
-a <code>gun_error</code> message is sent instead.</p></div>
-<div class="paragraph"><p>The response message will inform you whether there will be
-data messages following. If it contains <code>fin</code> there will be
-no data messages. If it contains <code>nofin</code> then one or more data
-messages will follow.</p></div>
-<div class="paragraph"><p>When using HTTP/2 this value is sent with the frame and simply
-passed on in the message. When using HTTP/1.1 however Gun must
-guess whether data will follow by looking at the response headers.</p></div>
-<div class="paragraph"><p>You can receive messages directly, or you can use the <em>await</em>
-functions to let Gun receive them for you.</p></div>
-<div class="listingblock">
-<div class="title">Receiving a response using receive</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="font-weight: bold"><span style="color: #000000">print_body</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">MRef</span>) <span style="color: #990000">-></span>
- <span style="color: #009900">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:get</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/"</span>),
- <span style="font-weight: bold"><span style="color: #0000FF">receive</span></span>
- {<span style="color: #FF6600">gun_response</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span>
- <span style="color: #FF6600">no_data</span>;
- {<span style="color: #FF6600">gun_response</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">receive_data</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">MRef</span>, <span style="color: #009900">StreamRef</span>);
- {<span style="color: #FF6600">'DOWN'</span>, <span style="color: #009900">MRef</span>, <span style="font-weight: bold"><span style="color: #000080">process</span></span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">error_logger:error_msg</span></span>(<span style="color: #FF0000">"Oops!"</span>),
- <span style="font-weight: bold"><span style="color: #000080">exit</span></span>(<span style="color: #009900">Reason</span>)
- <span style="font-weight: bold"><span style="color: #0000FF">after</span></span> <span style="color: #993399">1000</span> <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000080">exit</span></span>(<span style="color: #FF6600">timeout</span>)
- <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">receive_data</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">MRef</span>, <span style="color: #009900">StreamRef</span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #0000FF">receive</span></span>
- {<span style="color: #FF6600">gun_data</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"~s~n"</span>, [<span style="color: #009900">Data</span>]),
- <span style="font-weight: bold"><span style="color: #000000">receive_data</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">MRef</span>, <span style="color: #009900">StreamRef</span>);
- {<span style="color: #FF6600">gun_data</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"~s~n"</span>, [<span style="color: #009900">Data</span>]);
- {<span style="color: #FF6600">'DOWN'</span>, <span style="color: #009900">MRef</span>, <span style="font-weight: bold"><span style="color: #000080">process</span></span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">error_logger:error_msg</span></span>(<span style="color: #FF0000">"Oops!"</span>),
- <span style="font-weight: bold"><span style="color: #000080">exit</span></span>(<span style="color: #009900">Reason</span>)
- <span style="font-weight: bold"><span style="color: #0000FF">after</span></span> <span style="color: #993399">1000</span> <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000080">exit</span></span>(<span style="color: #FF6600">timeout</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>While it may seem verbose, using messages like this has the
-advantage of never locking your process, allowing you to
-easily debug your code. It also allows you to start more than
-one connection and concurrently perform queries on all of them
-at the same time.</p></div>
-<div class="paragraph"><p>You can also use Gun in a synchronous manner by using the <em>await</em>
-functions.</p></div>
-<div class="paragraph"><p>The <code>gun:await/{2,3,4}</code> function will wait until it receives
-a response to, a pushed resource related to, or data from
-the given stream.</p></div>
-<div class="paragraph"><p>When calling <code>gun:await/{2,3}</code> and not passing a monitor
-reference, one is automatically created for you for the
-duration of the call.</p></div>
-<div class="paragraph"><p>The <code>gun:await_body/{2,3,4}</code> works similarly, but returns the
-body received. Both functions can be combined to receive the
-response and its body sequentially.</p></div>
-<div class="listingblock">
-<div class="title">Receiving a response using await</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">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:get</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/"</span>),
-<span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">gun:await</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- {<span style="color: #FF6600">response</span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span>
- <span style="color: #FF6600">no_data</span>;
- {<span style="color: #FF6600">response</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Body</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:await_body</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>),
- <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"~s~n"</span>, [<span style="color: #009900">Body</span>])
-<span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_handling_streams_pushed_by_the_server">Handling streams pushed by the server</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The HTTP/2 protocol allows the server to push more than one
-resource for every request. It will start sending those
-extra resources before it starts sending the response itself,
-so Gun will send you <code>gun_push</code> messages before <code>gun_response</code>
-when that happens.</p></div>
-<div class="paragraph"><p>You can safely choose to ignore <code>gun_push</code> messages, or
-you can handle them. If you do, you can either receive the
-messages directly or use <em>await</em> functions.</p></div>
-<div class="paragraph"><p>The <code>gun_push</code> message contains both the new stream reference
-and the stream reference of the original request.</p></div>
-<div class="listingblock">
-<div class="title">Receiving a pushed response using receive</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="font-weight: bold"><span style="color: #0000FF">receive</span></span>
- {<span style="color: #FF6600">gun_push</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">OriginalStreamRef</span>, <span style="color: #009900">PushedStreamRef</span>,
- <span style="color: #009900">Method</span>, <span style="color: #009900">Host</span>, <span style="color: #009900">Path</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">enjoy</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>If you use the <code>gun:await/{2,3,4}</code> function, however, Gun
-will use the original reference to identify the message but
-will return a tuple that doesn’t contain it.</p></div>
-<div class="listingblock">
-<div class="title">Receiving a pushed response using await</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: #FF6600">push</span>, <span style="color: #009900">PushedStreamRef</span>, <span style="color: #009900">Method</span>, <span style="color: #009900">Host</span>, <span style="color: #009900">Path</span>, <span style="color: #009900">Headers</span>}
- <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:await</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">OriginalStreamRef</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The <code>PushedStreamRef</code> variable can then be used with <code>gun:await_body/{2,3,4}</code>
-if needed.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_flushing_unwanted_messages">Flushing unwanted messages</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Gun provides the function <code>gun:flush/1</code> to quickly get rid
-of unwanted messages sitting in the process mailbox. You
-can use it to get rid of all messages related to a connection,
-or just the messages related to a stream.</p></div>
-<div class="listingblock">
-<div class="title">Flush all messages from a Gun connection</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="font-weight: bold"><span style="color: #000000">gun:flush</span></span>(<span style="color: #009900">ConnPid</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Flush all messages from a specific stream</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="font-weight: bold"><span style="color: #000000">gun:flush</span></span>(<span style="color: #009900">StreamRef</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_redirecting_responses_to_a_different_process">Redirecting responses to a different process</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Gun allows you to specify which process will handle responses
-to a request via the <code>reply_to</code> request option.</p></div>
-<div class="listingblock">
-<div class="title">GET "/organizations/ninenines" to a different process</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">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:get</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>, [],
- #{<span style="color: #0000FF">reply_to</span> <span style="color: #990000">=></span> <span style="color: #009900">Pid</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter describes how to use the Gun client for +communicating with an HTTP/1.1 or HTTP/2 server.</p></div> +<div class="sect1"> +<h2 id="_streams">Streams</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Every time a request is initiated, Gun creates a <em>stream</em>. +A <em>stream reference</em> uniquely identifies a set of request and +response(s) and must be used to perform additional operations +with a stream or to identify its messages.</p></div> +<div class="paragraph"><p>Stream references use the Erlang <em>reference</em> data type and +are therefore unique.</p></div> +<div class="paragraph"><p>Streams can be canceled at any time. This will stop any further +messages from being sent to the owner process. Depending on +its capabilities, the server will also be instructed to cancel +the request.</p></div> +<div class="paragraph"><p>Canceling a stream may result in Gun dropping the connection +temporarily, to avoid uploading or downloading data that will +not be used.</p></div> +<div class="listingblock"> +<div class="title">Cancelling a stream</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="font-weight: bold"><span style="color: #000000">gun:cancel</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_sending_requests">Sending requests</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Gun provides many convenient functions for performing common +operations, like GET, POST or DELETE. It also provides a +general purpose function in case you need other methods.</p></div> +<div class="paragraph"><p>The availability of these methods on the server can vary +depending on the software used but also on a per-resource +basis.</p></div> +<div class="paragraph"><p>Gun will automatically set a few headers depending on the +method used. For all methods however it will set the host +header if it has not been provided in the request arguments.</p></div> +<div class="paragraph"><p>This section focuses on the act of sending a request. The +handling of responses will be explained further on.</p></div> +<div class="sect3"> +<h4 id="_get_and_head">GET and HEAD</h4> +<div class="paragraph"><p>Use <code>gun:get/{2,3,4}</code> to request a resource.</p></div> +<div class="listingblock"> +<div class="title">GET "/organizations/ninenines"</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">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:get</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">GET "/organizations/ninenines" with custom headers</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">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:get</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>, [ + {<span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"application/json"</span>}, + {<span style="color: #990000"><<</span><span style="color: #FF0000">"user-agent"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"revolver/1.0"</span>} +])<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Note that the list of headers has the field name as a binary. +The field value is iodata, which is either a binary or an +iolist.</p></div> +<div class="paragraph"><p>Use <code>gun:head/{2,3,4}</code> if you don’t need the response body.</p></div> +<div class="listingblock"> +<div class="title">HEAD "/organizations/ninenines"</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">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:head</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">HEAD "/organizations/ninenines" with custom headers</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">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:head</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>, [ + {<span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"application/json"</span>}, + {<span style="color: #990000"><<</span><span style="color: #FF0000">"user-agent"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"revolver/1.0"</span>} +])<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>It is not possible to send a request body with a GET or HEAD +request.</p></div> +</div> +<div class="sect3"> +<h4 id="_post_put_and_patch">POST, PUT and PATCH</h4> +<div class="paragraph"><p>HTTP defines three methods to create or update a resource.</p></div> +<div class="paragraph"><p>POST is generally used when the resource identifier (URI) isn’t known +in advance when creating the resource. POST can also be used to +replace an existing resource, although PUT is more appropriate +in that situation.</p></div> +<div class="paragraph"><p>PUT creates or replaces a resource identified by the URI.</p></div> +<div class="paragraph"><p>PATCH provides instructions on how to modify the resource.</p></div> +<div class="paragraph"><p>Both POST and PUT send the entire resource representation in their +request body. The PATCH method can be used when this is not +desirable. The request body of a PATCH method may be a partial +representation or a list of instructions on how to update the +resource.</p></div> +<div class="paragraph"><p>The <code>gun:post/{4,5}</code>, <code>gun:put/{4,5}</code> and <code>gun:patch/{4,5}</code> functions +take a body as their fourth argument. These functions do +not require any body-specific header to be set, although +it is always recommended to set the content-type header. +Gun will set the other headers automatically.</p></div> +<div class="paragraph"><p>In this and the following examples in this section, <code>gun:post</code> +can be replaced by <code>gun:put</code> or <code>gun:patch</code> for performing +a PUT or PATCH request, respectively.</p></div> +<div class="listingblock"> +<div class="title">POST "/organizations/ninenines"</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">Body</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"{\"msg\": \"Hello world!\"}"</span>, +<span style="color: #009900">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:post</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>, [ + {<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"application/json"</span>} +], <span style="color: #009900">Body</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The <code>gun:post/3</code>, <code>gun:put/3</code> and <code>gun:patch/3</code> functions +do not take a body in their arguments. If a body is to be +provided later on, using the <code>gun:data/4</code> function, then +the request headers must indicate this. This can be done +by setting the content-length or content-type request +headers. If these headers are not set then Gun will assume +the request has no body.</p></div> +<div class="paragraph"><p>It is recommended to send the content-length header if you +know it in advance, although this is not required. If it +is not set, HTTP/1.1 will use the chunked transfer-encoding, +and HTTP/2 will continue normally as it is chunked by design.</p></div> +<div class="listingblock"> +<div class="title">POST "/organizations/ninenines" with delayed body</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">Body</span> <span style="color: #990000">=</span> <span style="color: #FF0000">"{\"msg\": \"Hello world!\"}"</span>, +<span style="color: #009900">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:post</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>, [ + {<span style="color: #990000"><<</span><span style="color: #FF0000">"content-length"</span><span style="color: #990000">>></span>, <span style="font-weight: bold"><span style="color: #000000">integer_to_binary</span></span>(<span style="font-weight: bold"><span style="color: #000080">length</span></span>(<span style="color: #009900">Body</span>))}, + {<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"application/json"</span>} +]), +<span style="font-weight: bold"><span style="color: #000000">gun:data</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Body</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The atom <code>fin</code> indicates this is the last chunk of data to +be sent. You can call the <code>gun:data/4</code> function as many +times as needed until you have sent the entire body. The +last call must use <code>fin</code> and all the previous calls must +use <code>nofin</code>. The last chunk may be empty.</p></div> +<div class="paragraph"><p>@todo what to do about empty chunk, ignore?</p></div> +<div class="listingblock"> +<div class="title">Streaming the request body</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="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #009900">Filepath</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">IoDevice</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:open</span></span>(<span style="color: #009900">Filepath</span>, [<span style="color: #FF6600">read</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #FF6600">raw</span>]), + <span style="font-weight: bold"><span style="color: #000000">do_sendfile</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #009900">IoDevice</span>)<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">do_sendfile</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #009900">IoDevice</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">file:read</span></span>(<span style="color: #009900">IoDevice</span>, <span style="color: #993399">8000</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + <span style="color: #FF6600">eof</span> <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">gun:data</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #FF6600">fin</span>, <span style="color: #990000"><<>></span>), + <span style="font-weight: bold"><span style="color: #000000">file:close</span></span>(<span style="color: #009900">IoDevice</span>); + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Bin</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">gun:data</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Bin</span>), + <span style="font-weight: bold"><span style="color: #000000">do_sendfile</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #009900">IoDevice</span>) + <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> +</div> +<div class="sect3"> +<h4 id="_delete">DELETE</h4> +<div class="paragraph"><p>Use <code>gun:delete/{2,3,4}</code> to delete a resource.</p></div> +<div class="listingblock"> +<div class="title">DELETE "/organizations/ninenines"</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">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:delete</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">DELETE "/organizations/ninenines" with custom headers</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">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:delete</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>, [ + {<span style="color: #990000"><<</span><span style="color: #FF0000">"user-agent"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"revolver/1.0"</span>} +])<span style="color: #990000">.</span></tt></pre></div></div> +</div> +<div class="sect3"> +<h4 id="_options">OPTIONS</h4> +<div class="paragraph"><p>Use <code>gun:options/{2,3}</code> to request information about a resource.</p></div> +<div class="listingblock"> +<div class="title">OPTIONS "/organizations/ninenines"</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">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:options</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">OPTIONS "/organizations/ninenines" with custom headers</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">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:options</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>, [ + {<span style="color: #990000"><<</span><span style="color: #FF0000">"user-agent"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"revolver/1.0"</span>} +])<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You can also use this function to request information about +the server itself.</p></div> +<div class="listingblock"> +<div class="title">OPTIONS "*"</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">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:options</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"*"</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +<div class="sect3"> +<h4 id="_requests_with_an_arbitrary_method">Requests with an arbitrary method</h4> +<div class="paragraph"><p>The <code>gun:request/{4,5,6}</code> function can be used to send requests +with a configurable method name. It is mostly useful when you +need a method that Gun does not understand natively.</p></div> +<div class="listingblock"> +<div class="title">Example of a TRACE request</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="font-weight: bold"><span style="color: #000000">gun:request</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"TRACE"</span>, <span style="color: #FF0000">"/"</span>, [ + {<span style="color: #990000"><<</span><span style="color: #FF0000">"max-forwards"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"30"</span>} +])<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_processing_responses">Processing responses</h2> +<div class="sectionbody"> +<div class="paragraph"><p>All data received from the server is sent to the owner +process as a message. First a <code>gun_response</code> message is sent, +followed by zero or more <code>gun_data</code> messages. If something goes wrong, +a <code>gun_error</code> message is sent instead.</p></div> +<div class="paragraph"><p>The response message will inform you whether there will be +data messages following. If it contains <code>fin</code> there will be +no data messages. If it contains <code>nofin</code> then one or more data +messages will follow.</p></div> +<div class="paragraph"><p>When using HTTP/2 this value is sent with the frame and simply +passed on in the message. When using HTTP/1.1 however Gun must +guess whether data will follow by looking at the response headers.</p></div> +<div class="paragraph"><p>You can receive messages directly, or you can use the <em>await</em> +functions to let Gun receive them for you.</p></div> +<div class="listingblock"> +<div class="title">Receiving a response using receive</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="font-weight: bold"><span style="color: #000000">print_body</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">MRef</span>) <span style="color: #990000">-></span> + <span style="color: #009900">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:get</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/"</span>), + <span style="font-weight: bold"><span style="color: #0000FF">receive</span></span> + {<span style="color: #FF6600">gun_response</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span> + <span style="color: #FF6600">no_data</span>; + {<span style="color: #FF6600">gun_response</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">receive_data</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">MRef</span>, <span style="color: #009900">StreamRef</span>); + {<span style="color: #FF6600">'DOWN'</span>, <span style="color: #009900">MRef</span>, <span style="font-weight: bold"><span style="color: #000080">process</span></span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">error_logger:error_msg</span></span>(<span style="color: #FF0000">"Oops!"</span>), + <span style="font-weight: bold"><span style="color: #000080">exit</span></span>(<span style="color: #009900">Reason</span>) + <span style="font-weight: bold"><span style="color: #0000FF">after</span></span> <span style="color: #993399">1000</span> <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000080">exit</span></span>(<span style="color: #FF6600">timeout</span>) + <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">receive_data</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">MRef</span>, <span style="color: #009900">StreamRef</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #0000FF">receive</span></span> + {<span style="color: #FF6600">gun_data</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"~s~n"</span>, [<span style="color: #009900">Data</span>]), + <span style="font-weight: bold"><span style="color: #000000">receive_data</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">MRef</span>, <span style="color: #009900">StreamRef</span>); + {<span style="color: #FF6600">gun_data</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"~s~n"</span>, [<span style="color: #009900">Data</span>]); + {<span style="color: #FF6600">'DOWN'</span>, <span style="color: #009900">MRef</span>, <span style="font-weight: bold"><span style="color: #000080">process</span></span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">error_logger:error_msg</span></span>(<span style="color: #FF0000">"Oops!"</span>), + <span style="font-weight: bold"><span style="color: #000080">exit</span></span>(<span style="color: #009900">Reason</span>) + <span style="font-weight: bold"><span style="color: #0000FF">after</span></span> <span style="color: #993399">1000</span> <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000080">exit</span></span>(<span style="color: #FF6600">timeout</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>While it may seem verbose, using messages like this has the +advantage of never locking your process, allowing you to +easily debug your code. It also allows you to start more than +one connection and concurrently perform queries on all of them +at the same time.</p></div> +<div class="paragraph"><p>You can also use Gun in a synchronous manner by using the <em>await</em> +functions.</p></div> +<div class="paragraph"><p>The <code>gun:await/{2,3,4}</code> function will wait until it receives +a response to, a pushed resource related to, or data from +the given stream.</p></div> +<div class="paragraph"><p>When calling <code>gun:await/{2,3}</code> and not passing a monitor +reference, one is automatically created for you for the +duration of the call.</p></div> +<div class="paragraph"><p>The <code>gun:await_body/{2,3,4}</code> works similarly, but returns the +body received. Both functions can be combined to receive the +response and its body sequentially.</p></div> +<div class="listingblock"> +<div class="title">Receiving a response using await</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">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:get</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/"</span>), +<span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">gun:await</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + {<span style="color: #FF6600">response</span>, <span style="color: #FF6600">fin</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span> + <span style="color: #FF6600">no_data</span>; + {<span style="color: #FF6600">response</span>, <span style="color: #FF6600">nofin</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Body</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:await_body</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>), + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"~s~n"</span>, [<span style="color: #009900">Body</span>]) +<span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_handling_streams_pushed_by_the_server">Handling streams pushed by the server</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The HTTP/2 protocol allows the server to push more than one +resource for every request. It will start sending those +extra resources before it starts sending the response itself, +so Gun will send you <code>gun_push</code> messages before <code>gun_response</code> +when that happens.</p></div> +<div class="paragraph"><p>You can safely choose to ignore <code>gun_push</code> messages, or +you can handle them. If you do, you can either receive the +messages directly or use <em>await</em> functions.</p></div> +<div class="paragraph"><p>The <code>gun_push</code> message contains both the new stream reference +and the stream reference of the original request.</p></div> +<div class="listingblock"> +<div class="title">Receiving a pushed response using receive</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="font-weight: bold"><span style="color: #0000FF">receive</span></span> + {<span style="color: #FF6600">gun_push</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">OriginalStreamRef</span>, <span style="color: #009900">PushedStreamRef</span>, + <span style="color: #009900">Method</span>, <span style="color: #009900">Host</span>, <span style="color: #009900">Path</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">enjoy</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>If you use the <code>gun:await/{2,3,4}</code> function, however, Gun +will use the original reference to identify the message but +will return a tuple that doesn’t contain it.</p></div> +<div class="listingblock"> +<div class="title">Receiving a pushed response using await</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: #FF6600">push</span>, <span style="color: #009900">PushedStreamRef</span>, <span style="color: #009900">Method</span>, <span style="color: #009900">Host</span>, <span style="color: #009900">Path</span>, <span style="color: #009900">Headers</span>} + <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:await</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">OriginalStreamRef</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The <code>PushedStreamRef</code> variable can then be used with <code>gun:await_body/{2,3,4}</code> +if needed.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_flushing_unwanted_messages">Flushing unwanted messages</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Gun provides the function <code>gun:flush/1</code> to quickly get rid +of unwanted messages sitting in the process mailbox. You +can use it to get rid of all messages related to a connection, +or just the messages related to a stream.</p></div> +<div class="listingblock"> +<div class="title">Flush all messages from a Gun connection</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="font-weight: bold"><span style="color: #000000">gun:flush</span></span>(<span style="color: #009900">ConnPid</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Flush all messages from a specific stream</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="font-weight: bold"><span style="color: #000000">gun:flush</span></span>(<span style="color: #009900">StreamRef</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_redirecting_responses_to_a_different_process">Redirecting responses to a different process</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Gun allows you to specify which process will handle responses +to a request via the <code>reply_to</code> request option.</p></div> +<div class="listingblock"> +<div class="title">GET "/organizations/ninenines" to a different process</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">StreamRef</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">gun:get</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/organizations/ninenines"</span>, [], + #{<span style="color: #0000FF">reply_to</span> <span style="color: #990000">=></span> <span style="color: #009900">Pid</span>})<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/gun/1.0/guide/index.html b/docs/en/gun/1.0/guide/index.html index 8ad8284c..d243d71c 100644 --- a/docs/en/gun/1.0/guide/index.html +++ b/docs/en/gun/1.0/guide/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Gun User Guide</title> @@ -67,38 +67,38 @@ <h1 class="lined-header"><span>Gun User Guide</span></h1> -<div class="ulist"><ul>
-<li>
-<p>
-<a href="introduction/">Introduction</a>
-</p>
-</li>
-<li>
-<p>
-<a href="start/">Starting and stopping</a>
-</p>
-</li>
-<li>
-<p>
-<a href="protocols/">Supported protocols</a>
-</p>
-</li>
-<li>
-<p>
-<a href="connect/">Connection</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http/">Using HTTP</a>
-</p>
-</li>
-<li>
-<p>
-<a href="websocket/">Using Websocket</a>
-</p>
-</li>
-</ul></div>
+<div class="ulist"><ul> +<li> +<p> +<a href="introduction/">Introduction</a> +</p> +</li> +<li> +<p> +<a href="start/">Starting and stopping</a> +</p> +</li> +<li> +<p> +<a href="protocols/">Supported protocols</a> +</p> +</li> +<li> +<p> +<a href="connect/">Connection</a> +</p> +</li> +<li> +<p> +<a href="http/">Using HTTP</a> +</p> +</li> +<li> +<p> +<a href="websocket/">Using Websocket</a> +</p> +</li> +</ul></div> diff --git a/docs/en/gun/1.0/guide/introduction/index.html b/docs/en/gun/1.0/guide/introduction/index.html index 46d1fc33..271dfbc9 100644 --- a/docs/en/gun/1.0/guide/introduction/index.html +++ b/docs/en/gun/1.0/guide/introduction/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Introduction</title> @@ -67,46 +67,49 @@ <h1 class="lined-header"><span>Introduction</span></h1> -<div class="paragraph"><p>Gun is an Erlang HTTP client with support for HTTP/1.1, HTTP/2 and Websocket.</p></div>
-<div class="sect1">
-<h2 id="_prerequisites">Prerequisites</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Knowledge of Erlang, but also of the HTTP/1.1, HTTP/2 and Websocket
-protocols is required in order to read this guide.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_supported_platforms">Supported platforms</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Gun is tested and supported on Linux.</p></div>
-<div class="paragraph"><p>Gun is developed for Erlang 18+.</p></div>
-<div class="paragraph"><p>Gun may be compiled on earlier Erlang versions with small source code
-modifications but there is no guarantee that it will work as intended.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_conventions">Conventions</h2>
-<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. Gun converts all the header names
-to lowercase, and expects your application to provide lowercase header
-names.</p></div>
-<div class="paragraph"><p>The same applies to any other case insensitive value.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_versioning">Versioning</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Gun uses [Semantic Versioning 2.0.0](<a href="http://semver.org/">http://semver.org/</a>).</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Gun is an Erlang HTTP client with support for HTTP/1.1, HTTP/2 and Websocket.</p></div> +<div class="sect1"> +<h2 id="_prerequisites">Prerequisites</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Knowledge of Erlang, but also of the HTTP/1.1, HTTP/2 and Websocket +protocols is required in order to read this guide.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_supported_platforms">Supported platforms</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Gun is tested and supported on Linux.</p></div> +<div class="paragraph"><p>Gun is developed for Erlang 18+.</p></div> +<div class="paragraph"><p>Gun may be compiled on earlier Erlang versions with small source code +modifications but there is no guarantee that it will work as intended.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_conventions">Conventions</h2> +<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. Gun converts all the header names +to lowercase, and expects your application to provide lowercase header +names.</p></div> +<div class="paragraph"><p>The same applies to any other case insensitive value.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_versioning">Versioning</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Gun uses [Semantic Versioning 2.0.0](<a href="http://semver.org/">http://semver.org/</a>).</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/gun/1.0/guide/protocols/index.html b/docs/en/gun/1.0/guide/protocols/index.html index 38b05bfd..36f9b62f 100644 --- a/docs/en/gun/1.0/guide/protocols/index.html +++ b/docs/en/gun/1.0/guide/protocols/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Supported protocols</title> @@ -67,265 +67,268 @@ <h1 class="lined-header"><span>Supported protocols</span></h1> -<div class="paragraph"><p>This chapter describes the protocols supported and the
-operations available to them.</p></div>
-<div class="sect1">
-<h2 id="_http_1_1">HTTP/1.1</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>HTTP/1.1 is a text request-response protocol. The client
-sends a request, the server sends back a response.</p></div>
-<div class="paragraph"><p>Gun provides convenience functions for performing GET, HEAD,
-OPTIONS, POST, PATCH, PUT, and DELETE requests. All these
-functions are aliases of <code>gun:request/{4,5,6}</code> for each respective
-methods. Gun also provides a <code>gun:data/4</code> function for streaming
-the request body.</p></div>
-<div class="paragraph"><p>Gun will send a <code>gun_response</code> message for every response
-received, followed by zero or more <code>gun_data</code> messages for
-the response body. If something goes wrong, a <code>gun_error</code>
-will be sent instead.</p></div>
-<div class="paragraph"><p>Gun provides convenience functions for dealing with messages.
-The <code>gun:await/{2,3,4}</code> function waits for a response to the given
-request, and the <code>gun:await_body/{2,3,4}</code> function for the
-response’s body. The <code>gun:flush/1</code> function can be used to clear all
-messages related to a request or a connection from the mailbox
-of the process.</p></div>
-<div class="paragraph"><p>The function <code>gun:cancel/2</code> can be used to silence the
-response to a request previously sent if it is no longer
-needed. When using HTTP/1.1 there is no multiplexing so
-Gun will have to receive the response fully before any
-other response can be received.</p></div>
-<div class="paragraph"><p>Finally, Gun can upgrade an HTTP/1.1 connection to Websocket.
-It provides the <code>gun:ws_upgrade/{2,3,4}</code> function for that
-purpose. A <code>gun_ws_upgrade</code> message will be sent on success;
-a <code>gun_response</code> message otherwise.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_http_2">HTTP/2</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>HTTP/2 is a binary protocol based on HTTP, compatible with
-the HTTP semantics, that reduces the complexity of parsing
-requests and responses, compresses the HTTP headers and
-allows the server to push multiple responses to a single
-request.</p></div>
-<div class="paragraph"><p>The HTTP/2 interface is very similar to HTTP/1.1, so this
-section instead focuses on the differences in the interface
-for the two protocols.</p></div>
-<div class="paragraph"><p>Because a HTTP/2 server can push multiple responses to a
-single request, Gun might send <code>gun_push</code> messages for
-every push received. They can be ignored safely if they
-are not needed.</p></div>
-<div class="paragraph"><p>The <code>gun:cancel/2</code> function will use the HTTP/2 stream
-cancellation mechanism which allows Gun to inform the
-server to stop sending a response for this particular
-request, saving resources.</p></div>
-<div class="paragraph"><p>It is not possible to upgrade an HTTP/2 connection to Websocket
-due to protocol limitations.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_websocket">Websocket</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Websocket is a binary protocol built on top of HTTP that
-allows asynchronous concurrent communication between the
-client and the server. A Websocket server can push data to
-the client at any time.</p></div>
-<div class="paragraph"><p>Websocket is only available as a connection upgrade over
-an HTTP/1.1 connection.</p></div>
-<div class="paragraph"><p>Once the Websocket connection is established, the only
-operation available on this connection is sending Websocket
-frames using <code>gun:ws_send/2</code>.</p></div>
-<div class="paragraph"><p>Gun will send a <code>gun_ws</code> message for every frame received.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_summary">Summary</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The two following tables summarize the supported operations
-and the messages Gun sends depending on the connection’s
-current protocol.</p></div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="border"
-cellspacing="0" cellpadding="4">
-<col width="25%" />
-<col width="25%" />
-<col width="25%" />
-<col width="25%" />
-<thead>
-<tr>
-<th align="left" valign="top"> Operation </th>
-<th align="center" valign="top"> HTTP/1.1 </th>
-<th align="center" valign="top"> HTTP/2 </th>
-<th align="center" valign="top"> Websocket</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table">delete</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">no</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">get</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">no</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">head</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">no</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">options</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">no</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">patch</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">no</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">post</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">no</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">put</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">no</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">request</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">no</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">data</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">no</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">await</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">no</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">await_body</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">no</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">flush</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">no</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">cancel</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">no</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">ws_upgrade</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">no</p></td>
-<td align="center" valign="top"><p class="table">no</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">ws_send</p></td>
-<td align="center" valign="top"><p class="table">no</p></td>
-<td align="center" valign="top"><p class="table">no</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-</tr>
-</tbody>
-</table>
-</div>
-<div class="tableblock">
-<table rules="all"
-width="100%"
-frame="border"
-cellspacing="0" cellpadding="4">
-<col width="25%" />
-<col width="25%" />
-<col width="25%" />
-<col width="25%" />
-<thead>
-<tr>
-<th align="left" valign="top"> Message </th>
-<th align="center" valign="top"> HTTP/1.1 </th>
-<th align="center" valign="top"> HTTP/2 </th>
-<th align="center" valign="top"> Websocket</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td align="left" valign="top"><p class="table">gun_push</p></td>
-<td align="center" valign="top"><p class="table">no</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">no</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">gun_response</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">no</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">gun_data</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">no</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">gun_error (StreamRef)</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">no</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">gun_error</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">gun_ws_upgrade</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-<td align="center" valign="top"><p class="table">no</p></td>
-<td align="center" valign="top"><p class="table">no</p></td>
-</tr>
-<tr>
-<td align="left" valign="top"><p class="table">gun_ws</p></td>
-<td align="center" valign="top"><p class="table">no</p></td>
-<td align="center" valign="top"><p class="table">no</p></td>
-<td align="center" valign="top"><p class="table">yes</p></td>
-</tr>
-</tbody>
-</table>
-</div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter describes the protocols supported and the +operations available to them.</p></div> +<div class="sect1"> +<h2 id="_http_1_1">HTTP/1.1</h2> +<div class="sectionbody"> +<div class="paragraph"><p>HTTP/1.1 is a text request-response protocol. The client +sends a request, the server sends back a response.</p></div> +<div class="paragraph"><p>Gun provides convenience functions for performing GET, HEAD, +OPTIONS, POST, PATCH, PUT, and DELETE requests. All these +functions are aliases of <code>gun:request/{4,5,6}</code> for each respective +methods. Gun also provides a <code>gun:data/4</code> function for streaming +the request body.</p></div> +<div class="paragraph"><p>Gun will send a <code>gun_response</code> message for every response +received, followed by zero or more <code>gun_data</code> messages for +the response body. If something goes wrong, a <code>gun_error</code> +will be sent instead.</p></div> +<div class="paragraph"><p>Gun provides convenience functions for dealing with messages. +The <code>gun:await/{2,3,4}</code> function waits for a response to the given +request, and the <code>gun:await_body/{2,3,4}</code> function for the +response’s body. The <code>gun:flush/1</code> function can be used to clear all +messages related to a request or a connection from the mailbox +of the process.</p></div> +<div class="paragraph"><p>The function <code>gun:cancel/2</code> can be used to silence the +response to a request previously sent if it is no longer +needed. When using HTTP/1.1 there is no multiplexing so +Gun will have to receive the response fully before any +other response can be received.</p></div> +<div class="paragraph"><p>Finally, Gun can upgrade an HTTP/1.1 connection to Websocket. +It provides the <code>gun:ws_upgrade/{2,3,4}</code> function for that +purpose. A <code>gun_ws_upgrade</code> message will be sent on success; +a <code>gun_response</code> message otherwise.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_http_2">HTTP/2</h2> +<div class="sectionbody"> +<div class="paragraph"><p>HTTP/2 is a binary protocol based on HTTP, compatible with +the HTTP semantics, that reduces the complexity of parsing +requests and responses, compresses the HTTP headers and +allows the server to push multiple responses to a single +request.</p></div> +<div class="paragraph"><p>The HTTP/2 interface is very similar to HTTP/1.1, so this +section instead focuses on the differences in the interface +for the two protocols.</p></div> +<div class="paragraph"><p>Because a HTTP/2 server can push multiple responses to a +single request, Gun might send <code>gun_push</code> messages for +every push received. They can be ignored safely if they +are not needed.</p></div> +<div class="paragraph"><p>The <code>gun:cancel/2</code> function will use the HTTP/2 stream +cancellation mechanism which allows Gun to inform the +server to stop sending a response for this particular +request, saving resources.</p></div> +<div class="paragraph"><p>It is not possible to upgrade an HTTP/2 connection to Websocket +due to protocol limitations.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_websocket">Websocket</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Websocket is a binary protocol built on top of HTTP that +allows asynchronous concurrent communication between the +client and the server. A Websocket server can push data to +the client at any time.</p></div> +<div class="paragraph"><p>Websocket is only available as a connection upgrade over +an HTTP/1.1 connection.</p></div> +<div class="paragraph"><p>Once the Websocket connection is established, the only +operation available on this connection is sending Websocket +frames using <code>gun:ws_send/2</code>.</p></div> +<div class="paragraph"><p>Gun will send a <code>gun_ws</code> message for every frame received.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_summary">Summary</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The two following tables summarize the supported operations +and the messages Gun sends depending on the connection’s +current protocol.</p></div> +<div class="tableblock"> +<table rules="all" +width="100%" +frame="border" +cellspacing="0" cellpadding="4"> +<col width="25%" /> +<col width="25%" /> +<col width="25%" /> +<col width="25%" /> +<thead> +<tr> +<th align="left" valign="top"> Operation </th> +<th align="center" valign="top"> HTTP/1.1 </th> +<th align="center" valign="top"> HTTP/2 </th> +<th align="center" valign="top"> Websocket</th> +</tr> +</thead> +<tbody> +<tr> +<td align="left" valign="top"><p class="table">delete</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">no</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">get</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">no</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">head</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">no</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">options</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">no</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">patch</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">no</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">post</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">no</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">put</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">no</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">request</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">no</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">data</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">no</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">await</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">no</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">await_body</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">no</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">flush</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">no</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">cancel</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">no</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">ws_upgrade</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">no</p></td> +<td align="center" valign="top"><p class="table">no</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">ws_send</p></td> +<td align="center" valign="top"><p class="table">no</p></td> +<td align="center" valign="top"><p class="table">no</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +</tr> +</tbody> +</table> +</div> +<div class="tableblock"> +<table rules="all" +width="100%" +frame="border" +cellspacing="0" cellpadding="4"> +<col width="25%" /> +<col width="25%" /> +<col width="25%" /> +<col width="25%" /> +<thead> +<tr> +<th align="left" valign="top"> Message </th> +<th align="center" valign="top"> HTTP/1.1 </th> +<th align="center" valign="top"> HTTP/2 </th> +<th align="center" valign="top"> Websocket</th> +</tr> +</thead> +<tbody> +<tr> +<td align="left" valign="top"><p class="table">gun_push</p></td> +<td align="center" valign="top"><p class="table">no</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">no</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">gun_response</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">no</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">gun_data</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">no</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">gun_error (StreamRef)</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">no</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">gun_error</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">gun_ws_upgrade</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +<td align="center" valign="top"><p class="table">no</p></td> +<td align="center" valign="top"><p class="table">no</p></td> +</tr> +<tr> +<td align="left" valign="top"><p class="table">gun_ws</p></td> +<td align="center" valign="top"><p class="table">no</p></td> +<td align="center" valign="top"><p class="table">no</p></td> +<td align="center" valign="top"><p class="table">yes</p></td> +</tr> +</tbody> +</table> +</div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/gun/1.0/guide/start/index.html b/docs/en/gun/1.0/guide/start/index.html index b0345edf..e7df8d53 100644 --- a/docs/en/gun/1.0/guide/start/index.html +++ b/docs/en/gun/1.0/guide/start/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Starting and stopping</title> @@ -67,84 +67,91 @@ <h1 class="lined-header"><span>Starting and stopping</span></h1> -<div class="paragraph"><p>This chapter describes how to start and stop the Gun application.</p></div>
-<div class="sect1">
-<h2 id="_setting_up">Setting up</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Before Gun can be used it needs to be in Erlang’s <code>ERL_LIBS</code> path variable.
-If you use <code>erlang.mk</code> or a similar build tool, you only need to specify
-Gun as a dependency to your application and the tool will take care
-of downloading Gun and setting up paths.</p></div>
-<div class="paragraph"><p>With <code>erlang.mk</code> this is done by adding <code>gun</code> to the <code>DEPS</code> variable
-in your Makefile.</p></div>
-<div class="listingblock">
-<div class="title">Adding Gun as an erlang.mk dependency</div>
-<div class="content"></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_starting">Starting</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Gun is an <em>OTP application</em>. It needs to be started before you can
-use it.</p></div>
-<div class="listingblock">
-<div class="title">Starting Gun in an Erlang shell</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: #993399">1</span><span style="color: #990000">></span> <span style="font-weight: bold"><span style="color: #000000">application:ensure_all_started</span></span>(<span style="color: #FF6600">gun</span>)<span style="color: #990000">.</span>
-{<span style="color: #FF6600">ok</span>,[<span style="color: #FF6600">ranch</span>,<span style="color: #FF6600">crypto</span>,<span style="color: #FF6600">cowlib</span>,<span style="color: #FF6600">asn1</span>,<span style="color: #FF6600">public_key</span>,<span style="color: #FF6600">ssl</span>,<span style="color: #FF6600">gun</span>]}</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_stopping">Stopping</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can stop Gun using the <code>application:stop/1</code> function, however
-only Gun will be stopped. This is the equivalent of <code>application:start/1</code>.
-The <code>application_ensure_all_started/1</code> function has no equivalent for
-stopping all applications.</p></div>
-<div class="listingblock">
-<div class="title">Stopping Gun</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="font-weight: bold"><span style="color: #000000">application:stop</span></span>(<span style="color: #FF6600">gun</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_using_gun_with_releases">Using Gun with releases</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An <em>OTP release</em> starts applications automatically. All you need
-to do is to set up your application resource file so that Gun can
-be included in the release. The application resource file can be
-found in <code>ebin/your_application.app</code>, or in <code>src/your_application.app.src</code>
-if you are using a build tool like <code>erlang.mk</code>.</p></div>
-<div class="paragraph"><p>The key you need to change is the <code>applications</code> key. By default
-it only includes <code>kernel</code> and <code>stdlib</code>. You need to add <code>gun</code> to
-that list.</p></div>
-<div class="listingblock">
-<div class="title">Adding Gun to the application resource file</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: #FF6600">applications</span>, [
- <span style="color: #FF6600">kernel</span>,
- <span style="color: #FF6600">stdlib</span>,
- <span style="color: #FF6600">gun</span>
-]}</tt></pre></div></div>
-<div class="paragraph"><p>Do not put an extra comma at the end, the comma is a separator
-between the elements of the list.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter describes how to start and stop the Gun application.</p></div> +<div class="sect1"> +<h2 id="_setting_up">Setting up</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Before Gun can be used it needs to be in Erlang’s <code>ERL_LIBS</code> path variable. +If you use <code>erlang.mk</code> or a similar build tool, you only need to specify +Gun as a dependency to your application and the tool will take care +of downloading Gun and setting up paths.</p></div> +<div class="paragraph"><p>With <code>erlang.mk</code> this is done by adding <code>gun</code> to the <code>DEPS</code> variable +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> +</div> +<div class="sect1"> +<h2 id="_starting">Starting</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Gun is an <em>OTP application</em>. It needs to be started before you can +use it.</p></div> +<div class="listingblock"> +<div class="title">Starting Gun in an Erlang shell</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: #993399">1</span><span style="color: #990000">></span> <span style="font-weight: bold"><span style="color: #000000">application:ensure_all_started</span></span>(<span style="color: #FF6600">gun</span>)<span style="color: #990000">.</span> +{<span style="color: #FF6600">ok</span>,[<span style="color: #FF6600">ranch</span>,<span style="color: #FF6600">crypto</span>,<span style="color: #FF6600">cowlib</span>,<span style="color: #FF6600">asn1</span>,<span style="color: #FF6600">public_key</span>,<span style="color: #FF6600">ssl</span>,<span style="color: #FF6600">gun</span>]}</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_stopping">Stopping</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You can stop Gun using the <code>application:stop/1</code> function, however +only Gun will be stopped. This is the equivalent of <code>application:start/1</code>. +The <code>application_ensure_all_started/1</code> function has no equivalent for +stopping all applications.</p></div> +<div class="listingblock"> +<div class="title">Stopping Gun</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="font-weight: bold"><span style="color: #000000">application:stop</span></span>(<span style="color: #FF6600">gun</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_using_gun_with_releases">Using Gun with releases</h2> +<div class="sectionbody"> +<div class="paragraph"><p>An <em>OTP release</em> starts applications automatically. All you need +to do is to set up your application resource file so that Gun can +be included in the release. The application resource file can be +found in <code>ebin/your_application.app</code>, or in <code>src/your_application.app.src</code> +if you are using a build tool like <code>erlang.mk</code>.</p></div> +<div class="paragraph"><p>The key you need to change is the <code>applications</code> key. By default +it only includes <code>kernel</code> and <code>stdlib</code>. You need to add <code>gun</code> to +that list.</p></div> +<div class="listingblock"> +<div class="title">Adding Gun to the application resource file</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: #FF6600">applications</span>, [ + <span style="color: #FF6600">kernel</span>, + <span style="color: #FF6600">stdlib</span>, + <span style="color: #FF6600">gun</span> +]}</tt></pre></div></div> +<div class="paragraph"><p>Do not put an extra comma at the end, the comma is a separator +between the elements of the list.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/gun/1.0/guide/websocket/index.html b/docs/en/gun/1.0/guide/websocket/index.html index 4f162488..b10064cf 100644 --- a/docs/en/gun/1.0/guide/websocket/index.html +++ b/docs/en/gun/1.0/guide/websocket/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Websocket</title> @@ -67,134 +67,137 @@ <h1 class="lined-header"><span>Websocket</span></h1> -<div class="paragraph"><p>This chapter describes how to use the Gun client for
-communicating with a Websocket server.</p></div>
-<div class="paragraph"><p>@todo recovering from connection failure
-reconnecting to Websocket etc.</p></div>
-<div class="sect1">
-<h2 id="_http_upgrade">HTTP upgrade</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Websocket is a protocol built on top of HTTP. To use Websocket,
-you must first request for the connection to be upgraded. Only
-HTTP/1.1 connections can be upgraded to Websocket, so you might
-need to restrict the protocol to HTTP/1.1 if you are planning
-to use Websocket over TLS.</p></div>
-<div class="paragraph"><p>You must use the <code>gun_ws:upgrade/{2,3,4}</code> function to upgrade
-to Websocket. This function can be called anytime after connection,
-so you can send HTTP requests before upgrading to Websocket.</p></div>
-<div class="listingblock">
-<div class="title">Upgrade to Websocket</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="font-weight: bold"><span style="color: #000000">gun:ws_upgrade</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/websocket"</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Gun will set all the necessary headers for performing the
-Websocket upgrade, but you can specify additional headers
-if needed. For example you can request a custom sub-protocol.</p></div>
-<div class="listingblock">
-<div class="title">Upgrade to Websocket and request a protocol</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="font-weight: bold"><span style="color: #000000">gun:ws_upgrade</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/websocket"</span>, [
- {<span style="color: #990000"><<</span><span style="color: #FF0000">"sec-websocket-protocol"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"mychat"</span>}
-])<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can pass the Websocket options as part of the <code>gun:open/{2,3}</code>
-call when opening the connection, or using the <code>gun:ws_upgrade/4</code>.
-The fourth argument is those same options. This function call
-will crash if the options are incorrect, unlike when passing
-them through <code>gun:open/{2,3}</code>.</p></div>
-<div class="paragraph"><p>When the upgrade succeeds, a <code>gun_ws_upgrade</code> message is sent.
-If the server does not understand Websocket or refused the
-upgrade, a <code>gun_response</code> message is sent. If Gun couldn’t
-perform the upgrade due to an error (for example attempting
-to upgrade to Websocket on an HTTP/1.0 connection) then a
-<code>gun_error</code> message is sent.</p></div>
-<div class="paragraph"><p>When the server does not understand Websocket, it may send
-a meaningful response which should be processed. In the
-following example we however ignore 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="font-weight: bold"><span style="color: #0000FF">receive</span></span>
- {<span style="color: #FF6600">gun_ws_upgrade</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #FF6600">ok</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">upgrade_success</span></span>(<span style="color: #009900">ConnPid</span>);
- {<span style="color: #FF6600">gun_response</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #990000">_</span>, <span style="color: #990000">_</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000080">exit</span></span>({<span style="color: #FF6600">ws_upgrade_failed</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>});
- {<span style="color: #FF6600">gun_error</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000080">exit</span></span>({<span style="color: #FF6600">ws_upgrade_failed</span>, <span style="color: #009900">Reason</span>})
- <span style="font-style: italic"><span style="color: #9A1900">%% More clauses here as needed.</span></span>
-<span style="font-weight: bold"><span style="color: #0000FF">after</span></span> <span style="color: #993399">1000</span> <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000080">exit</span></span>(<span style="color: #FF6600">timeout</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>Note that you shouldn’t use the <code>reply_to</code> request option
-for connections you plan to upgrade, because only the
-owner of the connection will receive messages about it.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_sending_data">Sending data</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Once the Websocket upgrade has completed successfully, you no
-longer have access to functions for performing requests. You
-can only send and receive Websocket messages.</p></div>
-<div class="paragraph"><p>Use <code>gun:ws_send/2</code> to send one or more messages to the server.</p></div>
-<div class="paragraph"><p>@todo Implement sending of N frames</p></div>
-<div class="listingblock">
-<div class="title">Send a text frame</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="font-weight: bold"><span style="color: #000000">gun:ws_send</span></span>(<span style="color: #009900">ConnPid</span>, {<span style="color: #FF6600">text</span>, <span style="color: #FF0000">"Hello!"</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Send a text frame, a binary frame and then close the connection</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="font-weight: bold"><span style="color: #000000">gun:ws_send</span></span>(<span style="color: #009900">ConnPid</span>, [
- {<span style="color: #FF6600">text</span>, <span style="color: #FF0000">"Hello!"</span>},
- {<span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">BinaryValue</span>},
- <span style="color: #FF6600">close</span>
-])<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Note that if you send a close frame, Gun will close the connection
-cleanly and will not attempt to reconnect afterwards, similar to
-calling <code>gun:shutdown/1</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_receiving_data">Receiving data</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Gun sends an Erlang message to the owner process for every
-Websocket message it receives.</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: #0000FF">receive</span></span>
- {<span style="color: #FF6600">gun_ws</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">Frame</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">handle_frame</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">Frame</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>@todo auto ping has not been implemented yet</p></div>
-<div class="paragraph"><p>Gun will automatically send ping messages to the server to keep
-the connection alive, however if the connection dies and Gun has
-to reconnect it will not upgrade to Websocket automatically, you
-need to perform the operation when you receive the <code>gun_error</code>
-message.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter describes how to use the Gun client for +communicating with a Websocket server.</p></div> +<div class="paragraph"><p>@todo recovering from connection failure +reconnecting to Websocket etc.</p></div> +<div class="sect1"> +<h2 id="_http_upgrade">HTTP upgrade</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Websocket is a protocol built on top of HTTP. To use Websocket, +you must first request for the connection to be upgraded. Only +HTTP/1.1 connections can be upgraded to Websocket, so you might +need to restrict the protocol to HTTP/1.1 if you are planning +to use Websocket over TLS.</p></div> +<div class="paragraph"><p>You must use the <code>gun_ws:upgrade/{2,3,4}</code> function to upgrade +to Websocket. This function can be called anytime after connection, +so you can send HTTP requests before upgrading to Websocket.</p></div> +<div class="listingblock"> +<div class="title">Upgrade to Websocket</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="font-weight: bold"><span style="color: #000000">gun:ws_upgrade</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/websocket"</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Gun will set all the necessary headers for performing the +Websocket upgrade, but you can specify additional headers +if needed. For example you can request a custom sub-protocol.</p></div> +<div class="listingblock"> +<div class="title">Upgrade to Websocket and request a protocol</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="font-weight: bold"><span style="color: #000000">gun:ws_upgrade</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #FF0000">"/websocket"</span>, [ + {<span style="color: #990000"><<</span><span style="color: #FF0000">"sec-websocket-protocol"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"mychat"</span>} +])<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You can pass the Websocket options as part of the <code>gun:open/{2,3}</code> +call when opening the connection, or using the <code>gun:ws_upgrade/4</code>. +The fourth argument is those same options. This function call +will crash if the options are incorrect, unlike when passing +them through <code>gun:open/{2,3}</code>.</p></div> +<div class="paragraph"><p>When the upgrade succeeds, a <code>gun_ws_upgrade</code> message is sent. +If the server does not understand Websocket or refused the +upgrade, a <code>gun_response</code> message is sent. If Gun couldn’t +perform the upgrade due to an error (for example attempting +to upgrade to Websocket on an HTTP/1.0 connection) then a +<code>gun_error</code> message is sent.</p></div> +<div class="paragraph"><p>When the server does not understand Websocket, it may send +a meaningful response which should be processed. In the +following example we however ignore 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="font-weight: bold"><span style="color: #0000FF">receive</span></span> + {<span style="color: #FF6600">gun_ws_upgrade</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #FF6600">ok</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">upgrade_success</span></span>(<span style="color: #009900">ConnPid</span>); + {<span style="color: #FF6600">gun_response</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #990000">_</span>, <span style="color: #990000">_</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000080">exit</span></span>({<span style="color: #FF6600">ws_upgrade_failed</span>, <span style="color: #009900">Status</span>, <span style="color: #009900">Headers</span>}); + {<span style="color: #FF6600">gun_error</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">StreamRef</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000080">exit</span></span>({<span style="color: #FF6600">ws_upgrade_failed</span>, <span style="color: #009900">Reason</span>}) + <span style="font-style: italic"><span style="color: #9A1900">%% More clauses here as needed.</span></span> +<span style="font-weight: bold"><span style="color: #0000FF">after</span></span> <span style="color: #993399">1000</span> <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000080">exit</span></span>(<span style="color: #FF6600">timeout</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>Note that you shouldn’t use the <code>reply_to</code> request option +for connections you plan to upgrade, because only the +owner of the connection will receive messages about it.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_sending_data">Sending data</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Once the Websocket upgrade has completed successfully, you no +longer have access to functions for performing requests. You +can only send and receive Websocket messages.</p></div> +<div class="paragraph"><p>Use <code>gun:ws_send/2</code> to send one or more messages to the server.</p></div> +<div class="paragraph"><p>@todo Implement sending of N frames</p></div> +<div class="listingblock"> +<div class="title">Send a text frame</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="font-weight: bold"><span style="color: #000000">gun:ws_send</span></span>(<span style="color: #009900">ConnPid</span>, {<span style="color: #FF6600">text</span>, <span style="color: #FF0000">"Hello!"</span>})<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Send a text frame, a binary frame and then close the connection</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="font-weight: bold"><span style="color: #000000">gun:ws_send</span></span>(<span style="color: #009900">ConnPid</span>, [ + {<span style="color: #FF6600">text</span>, <span style="color: #FF0000">"Hello!"</span>}, + {<span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">BinaryValue</span>}, + <span style="color: #FF6600">close</span> +])<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Note that if you send a close frame, Gun will close the connection +cleanly and will not attempt to reconnect afterwards, similar to +calling <code>gun:shutdown/1</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_receiving_data">Receiving data</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Gun sends an Erlang message to the owner process for every +Websocket message it receives.</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: #0000FF">receive</span></span> + {<span style="color: #FF6600">gun_ws</span>, <span style="color: #009900">ConnPid</span>, <span style="color: #009900">Frame</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">handle_frame</span></span>(<span style="color: #009900">ConnPid</span>, <span style="color: #009900">Frame</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>@todo auto ping has not been implemented yet</p></div> +<div class="paragraph"><p>Gun will automatically send ping messages to the server to keep +the connection alive, however if the connection dies and Gun has +to reconnect it will not upgrade to Websocket automatically, you +need to perform the operation when you receive the <code>gun_error</code> +message.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/gun/1.0/index.html b/docs/en/gun/1.0/index.html index d87c4243..0194031a 100644 --- a/docs/en/gun/1.0/index.html +++ b/docs/en/gun/1.0/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file diff --git a/docs/en/gun/1.0/manual/gun/index.html b/docs/en/gun/1.0/manual/gun/index.html index 9fedee7e..aad74371 100644 --- a/docs/en/gun/1.0/manual/gun/index.html +++ b/docs/en/gun/1.0/manual/gun/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: gun(3)</title> @@ -67,1731 +67,1731 @@ <h1 class="lined-header"><span>gun(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>gun - asynchronous HTTP client</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>gun</code> module provides an asynchronous interface for
-connecting and communicating with Web servers over HTTP,
-HTTP/2 or Websocket.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_opts_map">opts() = map()</h3>
-<div class="paragraph"><p>Configuration for the connection.</p></div>
-<div class="paragraph"><p>The following keys are defined:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-connect_timeout ⇒ timeout()
-</dt>
-<dd>
-<p>
- Connection timeout. Defaults to <code>infinity</code>.
-</p>
-</dd>
-<dt class="hdlist1">
-http_opts ⇒ http_opts()
-</dt>
-<dd>
-<p>
- Options specific to the HTTP protocol. See below.
-</p>
-</dd>
-<dt class="hdlist1">
-http2_opts ⇒ http2_opts()
-</dt>
-<dd>
-<p>
- Options specific to the HTTP/2 protocol. See below.
-</p>
-</dd>
-<dt class="hdlist1">
-protocols ⇒ [http | http2]
-</dt>
-<dd>
-<p>
- Ordered list of preferred protocols. When the transport is tcp,
- this list must contain exactly one protocol. When the transport
- is ssl, this list must contain at least one protocol and will be
- used using the ALPN protocol negotiation method. When the server
- does not support ALPN then http will always be used. Defaults to
- [http] when the transport is tcp, and [http2, http] when the
- transport is ssl.
-</p>
-</dd>
-<dt class="hdlist1">
-retry ⇒ non_neg_integer()
-</dt>
-<dd>
-<p>
- Number of times Gun will try to reconnect on failure before giving up.
- Defaults to 5.
-</p>
-</dd>
-<dt class="hdlist1">
-retry_timeout ⇒ pos_integer()
-</dt>
-<dd>
-<p>
- Time between retries in milliseconds. Defaults to 5000.
-</p>
-</dd>
-<dt class="hdlist1">
-trace ⇒ boolean()
-</dt>
-<dd>
-<p>
- Whether to enable <code>dbg</code> tracing of the connection process. Should
- only be used during debugging. Defaults to false.
-</p>
-</dd>
-<dt class="hdlist1">
-transport ⇒ tcp | ssl
-</dt>
-<dd>
-<p>
- Whether to use SSL or plain TCP. The default varies depending on the
- port used. Port 443 defaults to ssl. All other ports default to tcp.
-</p>
-</dd>
-<dt class="hdlist1">
-transport_opts ⇒ proplists:proplist()
-</dt>
-<dd>
-<p>
- Transport options. They are TCP options or SSL options depending on
- the selected transport.
-</p>
-</dd>
-<dt class="hdlist1">
-ws_opts ⇒ ws_opts()
-</dt>
-<dd>
-<p>
- Options specific to the Websocket protocol. See below.
-</p>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<h3 id="_http_opts_map">http_opts() = map()</h3>
-<div class="paragraph"><p>Configuration for the HTTP protocol.</p></div>
-<div class="paragraph"><p>The following keys are defined:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-keepalive ⇒ timeout()
-</dt>
-<dd>
-<p>
- Time between pings in milliseconds. Since the HTTP protocol has
- no standardized way to ping the server, Gun will simply send an
- empty line when the connection is idle. Gun only makes a best
- effort here as servers usually have configurable limits to drop
- idle connections. Use <code>infinity</code> to disable. Defaults to 5000.
-</p>
-</dd>
-<dt class="hdlist1">
-transform_header_name ⇒ funLowercaseName :: binary( → TransformedName :: binary()) | undefined
-</dt>
-<dd>
-<p>
- A function that will be applied to all header names before they
- are sent to the server. Gun assumes that all header names are in
- lower case. This function is useful if you, for example, need to
- re-case header names in the event that the server incorrectly
- considers header name case to be significant.
-</p>
-</dd>
-<dt class="hdlist1">
-version ⇒ <em>HTTP/1.1</em> | <em>HTTP/1.0</em>
-</dt>
-<dd>
-<p>
- HTTP version to use. Defaults to <em>HTTP/1.1</em>.
-</p>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<h3 id="_http2_opts_map">http2_opts() = map()</h3>
-<div class="paragraph"><p>Configuration for the HTTP/2 protocol.</p></div>
-<div class="paragraph"><p>The following keys are defined:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-keepalive ⇒ pos_integer()
-</dt>
-<dd>
-<p>
- Time between pings in milliseconds. Defaults to 5000.
-</p>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<h3 id="_req_opts_map">req_opts() = map()</h3>
-<div class="paragraph"><p>Configuration for a particular request.</p></div>
-<div class="paragraph"><p>The following keys are defined:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-reply_to ⇒ pid()
-</dt>
-<dd>
-<p>
- The pid of a process that is responsible for the response handling.
-</p>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<h3 id="_ws_opts_map">ws_opts() = map()</h3>
-<div class="paragraph"><p>Configuration for the Websocket protocol.</p></div>
-<div class="paragraph"><p>The following keys are defined:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-compress ⇒ boolean()
-</dt>
-<dd>
-<p>
- Whether to enable permessage-deflate compression. This does
- not guarantee that compression will be used as it is the
- server that ultimately decides. Defaults to false.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_messages">Messages</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Calling functions from this module may result in the following
-messages being sent.</p></div>
-<div class="sect2">
-<h3 id="_gun_up_connpid_protocol">{gun_up, ConnPid, Protocol}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Protocol = http | http2
-</dt>
-<dd>
-<p>
-The protocol selected for this connection.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>The connection is up.</p></div>
-<div class="paragraph"><p>This message informs the owner process that the connection or
-reconnection completed.</p></div>
-<div class="paragraph"><p>The protocol selected during the connection is sent in this
-message. It can be used to determine the capabilities of the
-server.</p></div>
-<div class="paragraph"><p>Gun will now start processing the messages it received while
-waiting for the connection to be up. If this is a reconnection,
-then this may not be desirable for all requests. Those requests
-should be cancelled when the connection goes down, and any
-subsequent messages ignored.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_gun_down_connpid_protocol_reason_killedstreams_unprocessedstreams">{gun_down, ConnPid, Protocol, Reason, KilledStreams, UnprocessedStreams}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Protocol = http | http2 | ws
-</dt>
-<dd>
-<p>
-The protocol in use when the connection was lost.
-</p>
-</dd>
-<dt class="hdlist1">
-Reason = normal | closed | {error, atom()}
-</dt>
-<dd>
-<p>
-The reason for the loss of the connection.
-</p>
-</dd>
-<dt class="hdlist1">
-KilledStreams = [reference()]
-</dt>
-<dd>
-<p>
-List of streams that have been brutally terminated.
-</p>
-</dd>
-<dt class="hdlist1">
-UnprocessedStreams = [reference()]
-</dt>
-<dd>
-<p>
-List of streams that have not been processed by the server.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>The connection is down.</p></div>
-<div class="paragraph"><p>This message informs the owner process that the connection is
-currently down. Gun will automatically attempt to reconnect
-depending on the <code>retry</code> and <code>retry_timeout</code> options.</p></div>
-<div class="paragraph"><p>The reason of the termination is there for debugging purposes
-only. You should not rely on this value to know what streams
-were processed or completed.</p></div>
-<div class="paragraph"><p>The <em>killed streams</em> are the active streams that did not complete
-before the closing of the connection. Whether they can be retried
-safely depends on the protocol used and the idempotence property
-of the requests.</p></div>
-<div class="paragraph"><p>The <em>unprocessed streams</em> are streams that the server did not
-start processing yet. They may be retried safely depending on
-what streams were killed before.</p></div>
-<div class="paragraph"><p>When the connection goes back up, Gun will not attempt to retry
-requests. It will also not upgrade to Websocket automatically
-if that was the protocol in use when the connection was lost.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_gun_push_connpid_streamref_newstreamref_uri_headers">{gun_push, ConnPid, StreamRef, NewStreamRef, URI, Headers}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream initiated by the owner process.
-</p>
-</dd>
-<dt class="hdlist1">
-NewStreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream being pushed.
-</p>
-</dd>
-<dt class="hdlist1">
-URI = binary()
-</dt>
-<dd>
-<p>
-URI of the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), binary()}]
-</dt>
-<dd>
-<p>
-Headers @todo
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>A resource pushed alongside an HTTP response.</p></div>
-<div class="paragraph"><p>This message can only be sent when the protocol is HTTP/2.</p></div>
-<div class="paragraph"><p>@todo I fear we also need the scheme; resource is identified by URI
-@todo Perhaps we really should send the URI entirely, because cache
-@todo relies on URI to work and this feature is for caching…
-@todo Not sure why Method is there, spec says it is only for GET</p></div>
-</div>
-<div class="sect2">
-<h3 id="_gun_response_connpid_streamref_isfin_status_headers">{gun_response, ConnPid, StreamRef, IsFin, Status, Headers}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream initiated by the owner process.
-</p>
-</dd>
-<dt class="hdlist1">
-IsFin = fin | nofin
-</dt>
-<dd>
-<p>
-Whether this message terminates the response.
-</p>
-</dd>
-<dt class="hdlist1">
-Status = binary()
-</dt>
-<dd>
-<p>
-Status line for the response.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), binary()}]
-</dt>
-<dd>
-<p>
-Headers sent with the response.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>A response to an HTTP request.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_gun_data_connpid_streamref_isfin_data">{gun_data, ConnPid, StreamRef, IsFin, Data}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream this data belongs to.
-</p>
-</dd>
-<dt class="hdlist1">
-IsFin = fin | nofin
-</dt>
-<dd>
-<p>
-Whether this message terminates the response.
-</p>
-</dd>
-<dt class="hdlist1">
-Data = binary()
-</dt>
-<dd>
-<p>
-Data from the stream.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Data associated with a stream.</p></div>
-<div class="paragraph"><p>The stream in question can be either one initiated by the owner
-process or a stream initiated by the server through the push
-mechanism. In any case a <code>gun_response</code> or a <code>gun_push</code> message
-will be sent before any <code>gun_data</code> message.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_gun_error_connpid_streamref_reason">{gun_error, ConnPid, StreamRef, Reason}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream this error relates to.
-</p>
-</dd>
-<dt class="hdlist1">
-Reason = any()
-</dt>
-<dd>
-<p>
-Error reason.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Stream-specific error.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_gun_error_connpid_reason">{gun_error, ConnPid, Reason}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Reason = any()
-</dt>
-<dd>
-<p>
-Error reason.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>General error.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_gun_ws_upgrade_connpid_ok_headers">{gun_ws_upgrade, ConnPid, ok, Headers}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), binary()}]
-</dt>
-<dd>
-<p>
-Headers sent with the response.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Successful upgrade to the Websocket protocol.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_gun_ws_connpid_frame">{gun_ws, ConnPid, Frame}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Frame = @todo
-</dt>
-<dd>
-<p>
-Frame.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Websocket frame.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exports">Exports</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_open_host_port_8594_open_host_port">open(Host, Port) → open(Host, Port, [])</h3>
-<div class="paragraph"><p>Alias of <code>gun:open/3</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_open_host_port_opts_8594_ok_connpid_error_reason">open(Host, Port, Opts) → {ok, ConnPid} | {error, Reason}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Host = inet:hostname()
-</dt>
-<dd>
-<p>
-Host to connect to.
-</p>
-</dd>
-<dt class="hdlist1">
-Port = inet:port_number()
-</dt>
-<dd>
-<p>
-Port to connect to.
-</p>
-</dd>
-<dt class="hdlist1">
-Opts = opts()
-</dt>
-<dd>
-<p>
-Options for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Reason = any()
-</dt>
-<dd>
-<p>
-Error reason. @todo really any?
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Open a connection to the given host and port.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_close_connpid_8594_ok">close(ConnPid) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Brutally close the connection.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_shutdown_connpid_8594_ok">shutdown(ConnPid) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Gracefully close the connection.</p></div>
-<div class="paragraph"><p>A monitor can be used to be notified when the connection is
-effectively closed.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_delete_connpid_path_8594_delete_connpid_path">delete(ConnPid, Path) → delete(ConnPid, Path, [], #{})</h3>
-<div class="paragraph"><p>Alias of <code>gun:delete/4</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_delete_connpid_path_headers_8594_delete_connpid_path_headers">delete(ConnPid, Path, Headers) → delete(ConnPid, Path, Headers, #{})</h3>
-<div class="paragraph"><p>Alias of <code>gun:delete/4</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_delete_connpid_path_headers_reqopts_8594_streamref">delete(ConnPid, Path, Headers, ReqOpts) → StreamRef</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Path = iodata()
-</dt>
-<dd>
-<p>
-Path to the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), iodata()}]
-</dt>
-<dd>
-<p>
-Additional request headers.
-</p>
-</dd>
-<dt class="hdlist1">
-ReqOpts = req_opts()
-</dt>
-<dd>
-<p>
-Request options.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream for this request.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Delete a resource.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_get_connpid_path_8594_get_connpid_path">get(ConnPid, Path) → get(ConnPid, Path, [], #{})</h3>
-<div class="paragraph"><p>Alias of <code>gun:get/4</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_get_connpid_path_headers_8594_get_connpid_path_headers">get(ConnPid, Path, Headers) → get(ConnPid, Path, Headers, #{})</h3>
-<div class="paragraph"><p>Alias of <code>gun:get/4</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_get_connpid_path_headers_reqopts_8594_streamref">get(ConnPid, Path, Headers, ReqOpts) → StreamRef</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Path = iodata()
-</dt>
-<dd>
-<p>
-Path to the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), iodata()}]
-</dt>
-<dd>
-<p>
-Additional request headers.
-</p>
-</dd>
-<dt class="hdlist1">
-ReqOpts = req_opts()
-</dt>
-<dd>
-<p>
-Request options.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream for this request.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Get a resource.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_head_connpid_path_8594_head_connpid_path">head(ConnPid, Path) → head(ConnPid, Path, [], #{})</h3>
-<div class="paragraph"><p>Alias of <code>gun:head/4</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_head_connpid_path_headers_8594_head_connpid_path_headers">head(ConnPid, Path, Headers) → head(ConnPid, Path, Headers, #{})</h3>
-<div class="paragraph"><p>Alias of <code>gun:head/4</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_head_connpid_path_headers_reqopts_8594_streamref">head(ConnPid, Path, Headers, ReqOpts) → StreamRef</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Path = iodata()
-</dt>
-<dd>
-<p>
-Path to the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), iodata()}]
-</dt>
-<dd>
-<p>
-Additional request headers.
-</p>
-</dd>
-<dt class="hdlist1">
-ReqOpts = req_opts()
-</dt>
-<dd>
-<p>
-Request options.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream for this request.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Get headers of a resource.</p></div>
-<div class="paragraph"><p>This function performs the same operation as <code>get/{2,3}</code> except
-the server will not send the resource representation, only the
-response’s status line and headers.</p></div>
-<div class="paragraph"><p>While servers should send the same headers they would if the
-request was a GET, like <code>content-length</code>, it is not always
-the case and differences may exist.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_options_connpid_path_8594_options_connpid_path">options(ConnPid, Path) → options(ConnPid, Path, [], #{})</h3>
-<div class="paragraph"><p>Alias of <code>gun:options/4</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_options_connpid_path_headers_8594_options_connpid_path_headers">options(ConnPid, Path, Headers) → options(ConnPid, Path, Headers, #{})</h3>
-<div class="paragraph"><p>Alias of <code>gun:options/4</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_options_connpid_path_headers_reqopts_8594_streamref">options(ConnPid, Path, Headers, ReqOpts) → StreamRef</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Path = iodata()
-</dt>
-<dd>
-<p>
-Path to the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), iodata()}]
-</dt>
-<dd>
-<p>
-Additional request headers.
-</p>
-</dd>
-<dt class="hdlist1">
-ReqOpts = req_opts()
-</dt>
-<dd>
-<p>
-Request options.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream for this request.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Obtain information about the capabilities of the server or of a resource.</p></div>
-<div class="paragraph"><p>The special path <code>"*"</code> can be used to obtain information about
-the server as a whole. Any other path will return information
-about the resource only.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_patch_connpid_path_headers_8594_streamref">patch(ConnPid, Path, Headers) → StreamRef</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Path = iodata()
-</dt>
-<dd>
-<p>
-Path to the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), iodata()}]
-</dt>
-<dd>
-<p>
-Additional request headers.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream for this request.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Request that a set of changes be applied to the resource.</p></div>
-<div class="paragraph"><p>This function expects either <code>content-length</code> or <code>content-type</code>
-to be set to know a body is going to be sent afterwards.
-Gun will assume the request has no body otherwise. It is
-highly recommended to set both when possible.</p></div>
-<div class="paragraph"><p>The body sent in this request should be a patch document
-with instructions on how to update the resource.</p></div>
-<div class="paragraph"><p>You can use the <code>gun:data/4</code> function to send the body, if any.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_patch_connpid_path_headers_body_8594_patch_connpid_path_headers_body">patch(ConnPid, Path, Headers, Body) → patch(ConnPid, Path, Headers, Body, #{})</h3>
-<div class="paragraph"><p>Alias of <code>gun:patch/5</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_patch_connpid_path_headers_body_reqopts_8594_streamref">patch(ConnPid, Path, Headers, Body, ReqOpts) → StreamRef</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Path = iodata()
-</dt>
-<dd>
-<p>
-Path to the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), iodata()}]
-</dt>
-<dd>
-<p>
-Additional request headers.
-</p>
-</dd>
-<dt class="hdlist1">
-Body = iodata()
-</dt>
-<dd>
-<p>
-Body of the request.
-</p>
-</dd>
-<dt class="hdlist1">
-ReqOpts = req_opts()
-</dt>
-<dd>
-<p>
-Request options.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream for this request.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Request that a set of changes be applied to the resource.</p></div>
-<div class="paragraph"><p>It is highly recommended to set the <code>content-type</code> header
-to inform the server what media type the body contains.
-Gun will automatically set the <code>content-length</code> header.</p></div>
-<div class="paragraph"><p>The body sent in this request should be a patch document
-with instructions on how to update the resource.</p></div>
-<div class="paragraph"><p>The complete request is sent when calling this function.
-It is not possible to stream more of the body after
-calling it.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_post_connpid_path_headers_8594_streamref">post(ConnPid, Path, Headers) → StreamRef</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Path = iodata()
-</dt>
-<dd>
-<p>
-Path to the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), iodata()}]
-</dt>
-<dd>
-<p>
-Additional request headers.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream for this request.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Process the enclosed representation according to the resource’s own semantics.</p></div>
-<div class="paragraph"><p>This function expects either <code>content-length</code> or <code>content-type</code>
-to be set to know a body is going to be sent afterwards.
-Gun will assume the request has no body otherwise. It is
-highly recommended to set both when possible.</p></div>
-<div class="paragraph"><p>The body sent in this request will be processed
-according to the resource’s own semantics. A new
-resource may be created as a result, and may be
-located at a different URI.</p></div>
-<div class="paragraph"><p>You can use the <code>gun:data/4</code> function to send the body, if any.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_post_connpid_path_headers_body_8594_post_connpid_path_headers_body">post(ConnPid, Path, Headers, Body) → post(ConnPid, Path, Headers, Body, #{})</h3>
-<div class="paragraph"><p>Alias of <code>gun:post/5</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_post_connpid_path_headers_body_reqopts_8594_streamref">post(ConnPid, Path, Headers, Body, ReqOpts) → StreamRef</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Path = iodata()
-</dt>
-<dd>
-<p>
-Path to the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), iodata()}]
-</dt>
-<dd>
-<p>
-Additional request headers.
-</p>
-</dd>
-<dt class="hdlist1">
-Body = iodata()
-</dt>
-<dd>
-<p>
-Body of the request.
-</p>
-</dd>
-<dt class="hdlist1">
-ReqOpts = req_opts()
-</dt>
-<dd>
-<p>
-Request options.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream for this request.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Process the enclosed representation according to the resource’s own semantics.</p></div>
-<div class="paragraph"><p>It is highly recommended to set the <code>content-type</code> header
-to inform the server what media type the body contains.
-Gun will automatically set the <code>content-length</code> header.</p></div>
-<div class="paragraph"><p>The body sent in this request will be processed
-according to the resource’s own semantics. A new
-resource may be created as a result, and may be
-located at a different URI.</p></div>
-<div class="paragraph"><p>The complete request is sent when calling this function.
-It is not possible to stream more of the body after
-calling it.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_put_connpid_path_headers_8594_streamref">put(ConnPid, Path, Headers) → StreamRef</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Path = iodata()
-</dt>
-<dd>
-<p>
-Path to the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), iodata()}]
-</dt>
-<dd>
-<p>
-Additional request headers.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream for this request.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Create or replace a resource.</p></div>
-<div class="paragraph"><p>The body of the request is the entire representation of the resource.</p></div>
-<div class="paragraph"><p>This function expects either <code>content-length</code> or <code>content-type</code>
-to be set to know a body is going to be sent afterwards.
-Gun will assume the request has no body otherwise. It is
-highly recommended to set both when possible.</p></div>
-<div class="paragraph"><p>You can use the <code>gun:data/4</code> function to send the body, if any.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_put_connpid_path_headers_body_8594_put_connpid_path_headers_body">put(ConnPid, Path, Headers, Body) → put(ConnPid, Path, Headers, Body, #{})</h3>
-<div class="paragraph"><p>Alias of <code>gun:put/5</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_put_connpid_path_headers_body_reqopts_8594_streamref">put(ConnPid, Path, Headers, Body, ReqOpts) → StreamRef</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Path = iodata()
-</dt>
-<dd>
-<p>
-Path to the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), iodata()}]
-</dt>
-<dd>
-<p>
-Additional request headers.
-</p>
-</dd>
-<dt class="hdlist1">
-Body = iodata()
-</dt>
-<dd>
-<p>
-Body of the request.
-</p>
-</dd>
-<dt class="hdlist1">
-ReqOpts = req_opts()
-</dt>
-<dd>
-<p>
-Request options.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream for this request.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Create or replace a resource.</p></div>
-<div class="paragraph"><p>The body of the request is the entire representation of the resource.</p></div>
-<div class="paragraph"><p>It is highly recommended to set the <code>content-type</code> header
-to inform the server what media type the body contains.
-Gun will automatically set the <code>content-length</code> header.</p></div>
-<div class="paragraph"><p>The complete request is sent when calling this function.
-It is not possible to stream more of the body after
-calling it.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_request_connpid_method_path_headers_8594_streamref">request(ConnPid, Method, Path, Headers) → StreamRef</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Method = iodata()
-</dt>
-<dd>
-<p>
-Request method.
-</p>
-</dd>
-<dt class="hdlist1">
-Path = iodata()
-</dt>
-<dd>
-<p>
-Path of the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), iodata()}]
-</dt>
-<dd>
-<p>
-Additional request headers.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream for this request.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Perform the given request.</p></div>
-<div class="paragraph"><p>This is a general purpose function that should only be used
-when existing method-specific functions don’t apply.</p></div>
-<div class="paragraph"><p>This function expects either <code>content-length</code> or <code>content-type</code>
-to be set to know a body is going to be sent afterwards.
-Gun will assume the request has no body otherwise. It is
-highly recommended to set both when possible.</p></div>
-<div class="paragraph"><p>You can use the <code>gun:data/4</code> function to send the body, if any.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_request_connpid_method_path_headers_body_8594_request_connpid_method_path_headers_body">request(ConnPid, Method, Path, Headers, Body) → request(ConnPid, Method, Path, Headers, Body, #{})</h3>
-<div class="paragraph"><p>Alias of <code>gun:request/6</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_request_connpid_method_path_headers_body_reqopts_8594_streamref">request(ConnPid, Method, Path, Headers, Body, ReqOpts) → StreamRef</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Method = iodata()
-</dt>
-<dd>
-<p>
-Request method.
-</p>
-</dd>
-<dt class="hdlist1">
-Path = iodata()
-</dt>
-<dd>
-<p>
-Path of the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), iodata()}]
-</dt>
-<dd>
-<p>
-Additional request headers.
-</p>
-</dd>
-<dt class="hdlist1">
-Body = iodata()
-</dt>
-<dd>
-<p>
-Body of the request.
-</p>
-</dd>
-<dt class="hdlist1">
-ReqOpts = req_opts()
-</dt>
-<dd>
-<p>
-Request options.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream for this request.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Perform the given request.</p></div>
-<div class="paragraph"><p>This is a general purpose function that should only be used
-when existing method-specific functions don’t apply.</p></div>
-<div class="paragraph"><p>It is highly recommended to set the <code>content-type</code> header
-to inform the server what media type the body contains.
-Gun will automatically set the <code>content-length</code> header.</p></div>
-<div class="paragraph"><p>The complete request is sent when calling this function.
-It is not possible to stream more of the body after
-calling it.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_data_connpid_streamref_isfin_data_8594_ok">data(ConnPid, StreamRef, IsFin, Data) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream this data belongs to.
-</p>
-</dd>
-<dt class="hdlist1">
-IsFin = fin | nofin
-</dt>
-<dd>
-<p>
-Whether this message terminates the request.
-</p>
-</dd>
-<dt class="hdlist1">
-Data = iodata()
-</dt>
-<dd>
-<p>
-Data to be sent with the request.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Stream the body of a request.</p></div>
-<div class="paragraph"><p>@todo empty chunks</p></div>
-<div class="paragraph"><p>This function can only be used if the request identified by
-<code>StreamRef</code> came with headers indicating the presence of a
-body and that body not being given when creating the request.</p></div>
-<div class="paragraph"><p>All calls to this function must use <code>nofin</code> except for the
-last which must use <code>fin</code> to indicate the end of the request
-body.</p></div>
-<div class="paragraph"><p>Empty data is allowed regardless of the value of <code>IsFin</code>.
-Gun will not send empty data chunks unless required to
-indicate the request body is finished, however.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_await_connpid_streamref_8594_await_connpid_streamref_5000_monitorref">await(ConnPid, StreamRef) → await(ConnPid, StreamRef, 5000, MonitorRef)</h3>
-<div class="paragraph"><p>Alias of <code>gun:await/4</code>.</p></div>
-<div class="paragraph"><p>A monitor <code>MonitorRef</code> is automatically created for the duration of
-this call and an error will be returned if the Gun connection process
-terminates.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_await_connpid_streamref_monitorref_8594_await_connpid_streamref_5000_monitorref">await(ConnPid, StreamRef, MonitorRef) → await(ConnPid, StreamRef, 5000, MonitorRef)</h3>
-<div class="paragraph"><p>Alias of <code>gun:await/4</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_await_connpid_streamref_timeout_8594_await_connpid_streamref_timeout_monitorref">await(ConnPid, StreamRef, Timeout) → await(ConnPid, StreamRef, Timeout, MonitorRef)</h3>
-<div class="paragraph"><p>Alias of <code>gun:await/4</code>.</p></div>
-<div class="paragraph"><p>A monitor <code>MonitorRef</code> is automatically created for the duration of
-this call and an error will be returned if the Gun connection process
-terminates.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_await_connpid_streamref_timeout_monitorref_8594_tuple_8201_8212_8201_see_below">await(ConnPid, StreamRef, Timeout, MonitorRef) → tuple() — see below</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream to await messages from.
-</p>
-</dd>
-<dt class="hdlist1">
-Timeout = timeout()
-</dt>
-<dd>
-<p>
-How long this function will wait for messages.
-</p>
-</dd>
-<dt class="hdlist1">
-MonitorRef = reference()
-</dt>
-<dd>
-<p>
-Monitor reference for the Gun connection process.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Wait for a response message.</p></div>
-<div class="paragraph"><p>This function can be used when a synchronous handling of
-responses is desired. It will only return when a message
-for the given stream is received, on error or on timeout.</p></div>
-<div class="paragraph"><p>The return values are described in the next few subsections.</p></div>
-<div class="sect3">
-<h4 id="_response_isfin_status_headers">{response, IsFin, Status, Headers}</h4>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-IsFin = fin | nofin
-</dt>
-<dd>
-<p>
-Whether this message terminates the response.
-</p>
-</dd>
-<dt class="hdlist1">
-Status = binary()
-</dt>
-<dd>
-<p>
-Status line for the response.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), binary()}]
-</dt>
-<dd>
-<p>
-Headers sent with the response.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Equivalent of a <code>gun_response</code> message.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_data_isfin_data">{data, IsFin, Data}</h4>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-IsFin = fin | nofin
-</dt>
-<dd>
-<p>
-Whether this message terminates the response.
-</p>
-</dd>
-<dt class="hdlist1">
-Data = binary()
-</dt>
-<dd>
-<p>
-Data from the stream.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Equivalent of a <code>gun_data</code> message.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_push_newstreamref_uri_headers">{push, NewStreamRef, URI, Headers}</h4>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-NewStreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream being pushed.
-</p>
-</dd>
-<dt class="hdlist1">
-URI = binary()
-</dt>
-<dd>
-<p>
-URI of the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), binary()}]
-</dt>
-<dd>
-<p>
-Headers @todo
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Equivalent of a <code>gun_push</code> message.</p></div>
-<div class="paragraph"><p>@todo Same changes as gun_push</p></div>
-</div>
-<div class="sect3">
-<h4 id="_error_reason">{error, Reason}</h4>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Reason = any()
-</dt>
-<dd>
-<p>
-Error reason. @todo any?
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Equivalent of a <code>gun_error</code> message.</p></div>
-<div class="paragraph"><p>@todo I think we want to distinguish a stream error, a general error,
-@todo a DOWN and a timeout error</p></div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_await_body_connpid_streamref_8594_await_body_connpid_streamref_5000_monitorref">await_body(ConnPid, StreamRef) → await_body(ConnPid, StreamRef, 5000, MonitorRef)</h3>
-<div class="paragraph"><p>Alias of <code>gun:await_body/4</code>.</p></div>
-<div class="paragraph"><p>A monitor <code>MonitorRef</code> is automatically created for the duration of
-this call and an error will be returned if the Gun connection process
-terminates.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_await_body_connpid_streamref_monitorref_8594_await_body_connpid_streamref_5000_monitorref">await_body(ConnPid, StreamRef, MonitorRef) → await_body(ConnPid, StreamRef, 5000, MonitorRef)</h3>
-<div class="paragraph"><p>Alias of <code>gun:await_body/4</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_await_body_connpid_streamref_timeout_8594_await_body_connpid_streamref_timeout_monitorref">await_body(ConnPid, StreamRef, Timeout) → await_body(ConnPid, StreamRef, Timeout, MonitorRef)</h3>
-<div class="paragraph"><p>Alias of <code>gun:await_body/4</code>.</p></div>
-<div class="paragraph"><p>A monitor <code>MonitorRef</code> is automatically created for the duration of
-this call and an error will be returned if the Gun connection process
-terminates.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_await_body_connpid_streamref_timeout_monitorref_8594_ok_body_error_reason">await_body(ConnPid, StreamRef, Timeout, MonitorRef) → {ok, Body} | {error, Reason}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream to await messages from.
-</p>
-</dd>
-<dt class="hdlist1">
-Timeout = timeout()
-</dt>
-<dd>
-<p>
-How long this function will wait for each message.
-</p>
-</dd>
-<dt class="hdlist1">
-MonitorRef = reference()
-</dt>
-<dd>
-<p>
-Monitor reference for the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Body = binary()
-</dt>
-<dd>
-<p>
-Body for the given stream.
-</p>
-</dd>
-<dt class="hdlist1">
-Reason = any()
-</dt>
-<dd>
-<p>
-Error reason. @todo any?
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Wait for a response body.</p></div>
-<div class="paragraph"><p>This function can be used when a synchronous handling of
-responses is desired. It will only return when it has
-finished fetching the entire response body.</p></div>
-<div class="paragraph"><p>The timeout value is <strong>per message</strong>. The actual function call
-can last much longer for large bodies.</p></div>
-<div class="paragraph"><p>@todo I think we want to distinguish a stream error, a general error,
-@todo a DOWN and a timeout error</p></div>
-<div class="paragraph"><p>@todo guide might be a little incorrect about await/await_body</p></div>
-</div>
-<div class="sect2">
-<h3 id="_flush_connpid_8594_ok">flush(ConnPid) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Flush all messages from the Gun connection process from the mailbox.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_flush_streamref_8594_ok">flush(StreamRef) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Stream identifier.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Flush all messages related to the given stream.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_cancel_connpid_streamref_8594_ok">cancel(ConnPid, StreamRef) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-StreamRef = reference()
-</dt>
-<dd>
-<p>
-Identifier of the stream to cancel.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Cancel the given stream.</p></div>
-<div class="paragraph"><p>HTTP/1.1 streams can’t be cancelled. Gun will simply silence
-the stream and stop relaying messages.</p></div>
-<div class="paragraph"><p>@todo Depending on the length
-@todo of a response Gun may also attempt to reconnect rather than
-@todo receive the entire response body.</p></div>
-<div class="paragraph"><p>HTTP/2 streams can however be cancelled at any time.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_ws_upgrade_connpid_path_8594_ws_upgrade_connpid_path">ws_upgrade(ConnPid, Path) → ws_upgrade(ConnPid, Path, [], #{})</h3>
-<div class="paragraph"><p>Alias of <code>gun:ws_upgrade/3</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_ws_upgrade_connpid_path_headers_8594_ok">ws_upgrade(ConnPid, Path, Headers) → ok</h3>
-<div class="paragraph"><p>Similar to <code>gun:ws_upgrade/4</code>, except <code>WsOpts</code> is taken from
-the options given in the <code>gun:open/{2,3}</code> call when opening
-the connection.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_ws_upgrade_connpid_path_headers_wsopts_8594_ok">ws_upgrade(ConnPid, Path, Headers, WsOpts) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Path = iodata()
-</dt>
-<dd>
-<p>
-Path to the resource.
-</p>
-</dd>
-<dt class="hdlist1">
-Headers = [{binary(), iodata()}]
-</dt>
-<dd>
-<p>
-Additional request headers.
-</p>
-</dd>
-<dt class="hdlist1">
-WsOpts = map()
-</dt>
-<dd>
-<p>
-Options for the Websocket connection.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Request the connection to be upgraded to the Websocket protocol.</p></div>
-<div class="paragraph"><p>This function can only be used when the current protocol is <code>http</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_ws_send_connpid_frames_8594_ok">ws_send(ConnPid, Frames) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ConnPid = pid()
-</dt>
-<dd>
-<p>
-The pid of the Gun connection process.
-</p>
-</dd>
-<dt class="hdlist1">
-Frames = @todo
-</dt>
-<dd>
-<p>
-@todo
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Send one or more Websocket frames.</p></div>
-<div class="paragraph"><p>This function can only be used following a successful <code>ws_upgrade</code> call.</p></div>
-</div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>gun - asynchronous HTTP client</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>gun</code> module provides an asynchronous interface for +connecting and communicating with Web servers over HTTP, +HTTP/2 or Websocket.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_opts_map">opts() = map()</h3> +<div class="paragraph"><p>Configuration for the connection.</p></div> +<div class="paragraph"><p>The following keys are defined:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +connect_timeout ⇒ timeout() +</dt> +<dd> +<p> + Connection timeout. Defaults to <code>infinity</code>. +</p> +</dd> +<dt class="hdlist1"> +http_opts ⇒ http_opts() +</dt> +<dd> +<p> + Options specific to the HTTP protocol. See below. +</p> +</dd> +<dt class="hdlist1"> +http2_opts ⇒ http2_opts() +</dt> +<dd> +<p> + Options specific to the HTTP/2 protocol. See below. +</p> +</dd> +<dt class="hdlist1"> +protocols ⇒ [http | http2] +</dt> +<dd> +<p> + Ordered list of preferred protocols. When the transport is tcp, + this list must contain exactly one protocol. When the transport + is ssl, this list must contain at least one protocol and will be + used using the ALPN protocol negotiation method. When the server + does not support ALPN then http will always be used. Defaults to + [http] when the transport is tcp, and [http2, http] when the + transport is ssl. +</p> +</dd> +<dt class="hdlist1"> +retry ⇒ non_neg_integer() +</dt> +<dd> +<p> + Number of times Gun will try to reconnect on failure before giving up. + Defaults to 5. +</p> +</dd> +<dt class="hdlist1"> +retry_timeout ⇒ pos_integer() +</dt> +<dd> +<p> + Time between retries in milliseconds. Defaults to 5000. +</p> +</dd> +<dt class="hdlist1"> +trace ⇒ boolean() +</dt> +<dd> +<p> + Whether to enable <code>dbg</code> tracing of the connection process. Should + only be used during debugging. Defaults to false. +</p> +</dd> +<dt class="hdlist1"> +transport ⇒ tcp | ssl +</dt> +<dd> +<p> + Whether to use SSL or plain TCP. The default varies depending on the + port used. Port 443 defaults to ssl. All other ports default to tcp. +</p> +</dd> +<dt class="hdlist1"> +transport_opts ⇒ proplists:proplist() +</dt> +<dd> +<p> + Transport options. They are TCP options or SSL options depending on + the selected transport. +</p> +</dd> +<dt class="hdlist1"> +ws_opts ⇒ ws_opts() +</dt> +<dd> +<p> + Options specific to the Websocket protocol. See below. +</p> +</dd> +</dl></div> +</div> +<div class="sect2"> +<h3 id="_http_opts_map">http_opts() = map()</h3> +<div class="paragraph"><p>Configuration for the HTTP protocol.</p></div> +<div class="paragraph"><p>The following keys are defined:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +keepalive ⇒ timeout() +</dt> +<dd> +<p> + Time between pings in milliseconds. Since the HTTP protocol has + no standardized way to ping the server, Gun will simply send an + empty line when the connection is idle. Gun only makes a best + effort here as servers usually have configurable limits to drop + idle connections. Use <code>infinity</code> to disable. Defaults to 5000. +</p> +</dd> +<dt class="hdlist1"> +transform_header_name ⇒ funLowercaseName :: binary( → TransformedName :: binary()) | undefined +</dt> +<dd> +<p> + A function that will be applied to all header names before they + are sent to the server. Gun assumes that all header names are in + lower case. This function is useful if you, for example, need to + re-case header names in the event that the server incorrectly + considers header name case to be significant. +</p> +</dd> +<dt class="hdlist1"> +version ⇒ <em>HTTP/1.1</em> | <em>HTTP/1.0</em> +</dt> +<dd> +<p> + HTTP version to use. Defaults to <em>HTTP/1.1</em>. +</p> +</dd> +</dl></div> +</div> +<div class="sect2"> +<h3 id="_http2_opts_map">http2_opts() = map()</h3> +<div class="paragraph"><p>Configuration for the HTTP/2 protocol.</p></div> +<div class="paragraph"><p>The following keys are defined:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +keepalive ⇒ pos_integer() +</dt> +<dd> +<p> + Time between pings in milliseconds. Defaults to 5000. +</p> +</dd> +</dl></div> +</div> +<div class="sect2"> +<h3 id="_req_opts_map">req_opts() = map()</h3> +<div class="paragraph"><p>Configuration for a particular request.</p></div> +<div class="paragraph"><p>The following keys are defined:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +reply_to ⇒ pid() +</dt> +<dd> +<p> + The pid of a process that is responsible for the response handling. +</p> +</dd> +</dl></div> +</div> +<div class="sect2"> +<h3 id="_ws_opts_map">ws_opts() = map()</h3> +<div class="paragraph"><p>Configuration for the Websocket protocol.</p></div> +<div class="paragraph"><p>The following keys are defined:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +compress ⇒ boolean() +</dt> +<dd> +<p> + Whether to enable permessage-deflate compression. This does + not guarantee that compression will be used as it is the + server that ultimately decides. Defaults to false. +</p> +</dd> +</dl></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_messages">Messages</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Calling functions from this module may result in the following +messages being sent.</p></div> +<div class="sect2"> +<h3 id="_gun_up_connpid_protocol">{gun_up, ConnPid, Protocol}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Protocol = http | http2 +</dt> +<dd> +<p> +The protocol selected for this connection. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>The connection is up.</p></div> +<div class="paragraph"><p>This message informs the owner process that the connection or +reconnection completed.</p></div> +<div class="paragraph"><p>The protocol selected during the connection is sent in this +message. It can be used to determine the capabilities of the +server.</p></div> +<div class="paragraph"><p>Gun will now start processing the messages it received while +waiting for the connection to be up. If this is a reconnection, +then this may not be desirable for all requests. Those requests +should be cancelled when the connection goes down, and any +subsequent messages ignored.</p></div> +</div> +<div class="sect2"> +<h3 id="_gun_down_connpid_protocol_reason_killedstreams_unprocessedstreams">{gun_down, ConnPid, Protocol, Reason, KilledStreams, UnprocessedStreams}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Protocol = http | http2 | ws +</dt> +<dd> +<p> +The protocol in use when the connection was lost. +</p> +</dd> +<dt class="hdlist1"> +Reason = normal | closed | {error, atom()} +</dt> +<dd> +<p> +The reason for the loss of the connection. +</p> +</dd> +<dt class="hdlist1"> +KilledStreams = [reference()] +</dt> +<dd> +<p> +List of streams that have been brutally terminated. +</p> +</dd> +<dt class="hdlist1"> +UnprocessedStreams = [reference()] +</dt> +<dd> +<p> +List of streams that have not been processed by the server. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>The connection is down.</p></div> +<div class="paragraph"><p>This message informs the owner process that the connection is +currently down. Gun will automatically attempt to reconnect +depending on the <code>retry</code> and <code>retry_timeout</code> options.</p></div> +<div class="paragraph"><p>The reason of the termination is there for debugging purposes +only. You should not rely on this value to know what streams +were processed or completed.</p></div> +<div class="paragraph"><p>The <em>killed streams</em> are the active streams that did not complete +before the closing of the connection. Whether they can be retried +safely depends on the protocol used and the idempotence property +of the requests.</p></div> +<div class="paragraph"><p>The <em>unprocessed streams</em> are streams that the server did not +start processing yet. They may be retried safely depending on +what streams were killed before.</p></div> +<div class="paragraph"><p>When the connection goes back up, Gun will not attempt to retry +requests. It will also not upgrade to Websocket automatically +if that was the protocol in use when the connection was lost.</p></div> +</div> +<div class="sect2"> +<h3 id="_gun_push_connpid_streamref_newstreamref_uri_headers">{gun_push, ConnPid, StreamRef, NewStreamRef, URI, Headers}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream initiated by the owner process. +</p> +</dd> +<dt class="hdlist1"> +NewStreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream being pushed. +</p> +</dd> +<dt class="hdlist1"> +URI = binary() +</dt> +<dd> +<p> +URI of the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), binary()}] +</dt> +<dd> +<p> +Headers @todo +</p> +</dd> +</dl></div> +<div class="paragraph"><p>A resource pushed alongside an HTTP response.</p></div> +<div class="paragraph"><p>This message can only be sent when the protocol is HTTP/2.</p></div> +<div class="paragraph"><p>@todo I fear we also need the scheme; resource is identified by URI +@todo Perhaps we really should send the URI entirely, because cache +@todo relies on URI to work and this feature is for caching… +@todo Not sure why Method is there, spec says it is only for GET</p></div> +</div> +<div class="sect2"> +<h3 id="_gun_response_connpid_streamref_isfin_status_headers">{gun_response, ConnPid, StreamRef, IsFin, Status, Headers}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream initiated by the owner process. +</p> +</dd> +<dt class="hdlist1"> +IsFin = fin | nofin +</dt> +<dd> +<p> +Whether this message terminates the response. +</p> +</dd> +<dt class="hdlist1"> +Status = binary() +</dt> +<dd> +<p> +Status line for the response. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), binary()}] +</dt> +<dd> +<p> +Headers sent with the response. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>A response to an HTTP request.</p></div> +</div> +<div class="sect2"> +<h3 id="_gun_data_connpid_streamref_isfin_data">{gun_data, ConnPid, StreamRef, IsFin, Data}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream this data belongs to. +</p> +</dd> +<dt class="hdlist1"> +IsFin = fin | nofin +</dt> +<dd> +<p> +Whether this message terminates the response. +</p> +</dd> +<dt class="hdlist1"> +Data = binary() +</dt> +<dd> +<p> +Data from the stream. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Data associated with a stream.</p></div> +<div class="paragraph"><p>The stream in question can be either one initiated by the owner +process or a stream initiated by the server through the push +mechanism. In any case a <code>gun_response</code> or a <code>gun_push</code> message +will be sent before any <code>gun_data</code> message.</p></div> +</div> +<div class="sect2"> +<h3 id="_gun_error_connpid_streamref_reason">{gun_error, ConnPid, StreamRef, Reason}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream this error relates to. +</p> +</dd> +<dt class="hdlist1"> +Reason = any() +</dt> +<dd> +<p> +Error reason. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Stream-specific error.</p></div> +</div> +<div class="sect2"> +<h3 id="_gun_error_connpid_reason">{gun_error, ConnPid, Reason}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Reason = any() +</dt> +<dd> +<p> +Error reason. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>General error.</p></div> +</div> +<div class="sect2"> +<h3 id="_gun_ws_upgrade_connpid_ok_headers">{gun_ws_upgrade, ConnPid, ok, Headers}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), binary()}] +</dt> +<dd> +<p> +Headers sent with the response. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Successful upgrade to the Websocket protocol.</p></div> +</div> +<div class="sect2"> +<h3 id="_gun_ws_connpid_frame">{gun_ws, ConnPid, Frame}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Frame = @todo +</dt> +<dd> +<p> +Frame. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Websocket frame.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_open_host_port_8594_open_host_port">open(Host, Port) → open(Host, Port, [])</h3> +<div class="paragraph"><p>Alias of <code>gun:open/3</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_open_host_port_opts_8594_ok_connpid_error_reason">open(Host, Port, Opts) → {ok, ConnPid} | {error, Reason}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Host = inet:hostname() +</dt> +<dd> +<p> +Host to connect to. +</p> +</dd> +<dt class="hdlist1"> +Port = inet:port_number() +</dt> +<dd> +<p> +Port to connect to. +</p> +</dd> +<dt class="hdlist1"> +Opts = opts() +</dt> +<dd> +<p> +Options for this connection. +</p> +</dd> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Reason = any() +</dt> +<dd> +<p> +Error reason. @todo really any? +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Open a connection to the given host and port.</p></div> +</div> +<div class="sect2"> +<h3 id="_close_connpid_8594_ok">close(ConnPid) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Brutally close the connection.</p></div> +</div> +<div class="sect2"> +<h3 id="_shutdown_connpid_8594_ok">shutdown(ConnPid) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Gracefully close the connection.</p></div> +<div class="paragraph"><p>A monitor can be used to be notified when the connection is +effectively closed.</p></div> +</div> +<div class="sect2"> +<h3 id="_delete_connpid_path_8594_delete_connpid_path">delete(ConnPid, Path) → delete(ConnPid, Path, [], #{})</h3> +<div class="paragraph"><p>Alias of <code>gun:delete/4</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_delete_connpid_path_headers_8594_delete_connpid_path_headers">delete(ConnPid, Path, Headers) → delete(ConnPid, Path, Headers, #{})</h3> +<div class="paragraph"><p>Alias of <code>gun:delete/4</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_delete_connpid_path_headers_reqopts_8594_streamref">delete(ConnPid, Path, Headers, ReqOpts) → StreamRef</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Path = iodata() +</dt> +<dd> +<p> +Path to the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), iodata()}] +</dt> +<dd> +<p> +Additional request headers. +</p> +</dd> +<dt class="hdlist1"> +ReqOpts = req_opts() +</dt> +<dd> +<p> +Request options. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream for this request. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Delete a resource.</p></div> +</div> +<div class="sect2"> +<h3 id="_get_connpid_path_8594_get_connpid_path">get(ConnPid, Path) → get(ConnPid, Path, [], #{})</h3> +<div class="paragraph"><p>Alias of <code>gun:get/4</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_get_connpid_path_headers_8594_get_connpid_path_headers">get(ConnPid, Path, Headers) → get(ConnPid, Path, Headers, #{})</h3> +<div class="paragraph"><p>Alias of <code>gun:get/4</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_get_connpid_path_headers_reqopts_8594_streamref">get(ConnPid, Path, Headers, ReqOpts) → StreamRef</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Path = iodata() +</dt> +<dd> +<p> +Path to the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), iodata()}] +</dt> +<dd> +<p> +Additional request headers. +</p> +</dd> +<dt class="hdlist1"> +ReqOpts = req_opts() +</dt> +<dd> +<p> +Request options. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream for this request. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Get a resource.</p></div> +</div> +<div class="sect2"> +<h3 id="_head_connpid_path_8594_head_connpid_path">head(ConnPid, Path) → head(ConnPid, Path, [], #{})</h3> +<div class="paragraph"><p>Alias of <code>gun:head/4</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_head_connpid_path_headers_8594_head_connpid_path_headers">head(ConnPid, Path, Headers) → head(ConnPid, Path, Headers, #{})</h3> +<div class="paragraph"><p>Alias of <code>gun:head/4</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_head_connpid_path_headers_reqopts_8594_streamref">head(ConnPid, Path, Headers, ReqOpts) → StreamRef</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Path = iodata() +</dt> +<dd> +<p> +Path to the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), iodata()}] +</dt> +<dd> +<p> +Additional request headers. +</p> +</dd> +<dt class="hdlist1"> +ReqOpts = req_opts() +</dt> +<dd> +<p> +Request options. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream for this request. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Get headers of a resource.</p></div> +<div class="paragraph"><p>This function performs the same operation as <code>get/{2,3}</code> except +the server will not send the resource representation, only the +response’s status line and headers.</p></div> +<div class="paragraph"><p>While servers should send the same headers they would if the +request was a GET, like <code>content-length</code>, it is not always +the case and differences may exist.</p></div> +</div> +<div class="sect2"> +<h3 id="_options_connpid_path_8594_options_connpid_path">options(ConnPid, Path) → options(ConnPid, Path, [], #{})</h3> +<div class="paragraph"><p>Alias of <code>gun:options/4</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_options_connpid_path_headers_8594_options_connpid_path_headers">options(ConnPid, Path, Headers) → options(ConnPid, Path, Headers, #{})</h3> +<div class="paragraph"><p>Alias of <code>gun:options/4</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_options_connpid_path_headers_reqopts_8594_streamref">options(ConnPid, Path, Headers, ReqOpts) → StreamRef</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Path = iodata() +</dt> +<dd> +<p> +Path to the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), iodata()}] +</dt> +<dd> +<p> +Additional request headers. +</p> +</dd> +<dt class="hdlist1"> +ReqOpts = req_opts() +</dt> +<dd> +<p> +Request options. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream for this request. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Obtain information about the capabilities of the server or of a resource.</p></div> +<div class="paragraph"><p>The special path <code>"*"</code> can be used to obtain information about +the server as a whole. Any other path will return information +about the resource only.</p></div> +</div> +<div class="sect2"> +<h3 id="_patch_connpid_path_headers_8594_streamref">patch(ConnPid, Path, Headers) → StreamRef</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Path = iodata() +</dt> +<dd> +<p> +Path to the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), iodata()}] +</dt> +<dd> +<p> +Additional request headers. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream for this request. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Request that a set of changes be applied to the resource.</p></div> +<div class="paragraph"><p>This function expects either <code>content-length</code> or <code>content-type</code> +to be set to know a body is going to be sent afterwards. +Gun will assume the request has no body otherwise. It is +highly recommended to set both when possible.</p></div> +<div class="paragraph"><p>The body sent in this request should be a patch document +with instructions on how to update the resource.</p></div> +<div class="paragraph"><p>You can use the <code>gun:data/4</code> function to send the body, if any.</p></div> +</div> +<div class="sect2"> +<h3 id="_patch_connpid_path_headers_body_8594_patch_connpid_path_headers_body">patch(ConnPid, Path, Headers, Body) → patch(ConnPid, Path, Headers, Body, #{})</h3> +<div class="paragraph"><p>Alias of <code>gun:patch/5</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_patch_connpid_path_headers_body_reqopts_8594_streamref">patch(ConnPid, Path, Headers, Body, ReqOpts) → StreamRef</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Path = iodata() +</dt> +<dd> +<p> +Path to the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), iodata()}] +</dt> +<dd> +<p> +Additional request headers. +</p> +</dd> +<dt class="hdlist1"> +Body = iodata() +</dt> +<dd> +<p> +Body of the request. +</p> +</dd> +<dt class="hdlist1"> +ReqOpts = req_opts() +</dt> +<dd> +<p> +Request options. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream for this request. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Request that a set of changes be applied to the resource.</p></div> +<div class="paragraph"><p>It is highly recommended to set the <code>content-type</code> header +to inform the server what media type the body contains. +Gun will automatically set the <code>content-length</code> header.</p></div> +<div class="paragraph"><p>The body sent in this request should be a patch document +with instructions on how to update the resource.</p></div> +<div class="paragraph"><p>The complete request is sent when calling this function. +It is not possible to stream more of the body after +calling it.</p></div> +</div> +<div class="sect2"> +<h3 id="_post_connpid_path_headers_8594_streamref">post(ConnPid, Path, Headers) → StreamRef</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Path = iodata() +</dt> +<dd> +<p> +Path to the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), iodata()}] +</dt> +<dd> +<p> +Additional request headers. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream for this request. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Process the enclosed representation according to the resource’s own semantics.</p></div> +<div class="paragraph"><p>This function expects either <code>content-length</code> or <code>content-type</code> +to be set to know a body is going to be sent afterwards. +Gun will assume the request has no body otherwise. It is +highly recommended to set both when possible.</p></div> +<div class="paragraph"><p>The body sent in this request will be processed +according to the resource’s own semantics. A new +resource may be created as a result, and may be +located at a different URI.</p></div> +<div class="paragraph"><p>You can use the <code>gun:data/4</code> function to send the body, if any.</p></div> +</div> +<div class="sect2"> +<h3 id="_post_connpid_path_headers_body_8594_post_connpid_path_headers_body">post(ConnPid, Path, Headers, Body) → post(ConnPid, Path, Headers, Body, #{})</h3> +<div class="paragraph"><p>Alias of <code>gun:post/5</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_post_connpid_path_headers_body_reqopts_8594_streamref">post(ConnPid, Path, Headers, Body, ReqOpts) → StreamRef</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Path = iodata() +</dt> +<dd> +<p> +Path to the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), iodata()}] +</dt> +<dd> +<p> +Additional request headers. +</p> +</dd> +<dt class="hdlist1"> +Body = iodata() +</dt> +<dd> +<p> +Body of the request. +</p> +</dd> +<dt class="hdlist1"> +ReqOpts = req_opts() +</dt> +<dd> +<p> +Request options. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream for this request. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Process the enclosed representation according to the resource’s own semantics.</p></div> +<div class="paragraph"><p>It is highly recommended to set the <code>content-type</code> header +to inform the server what media type the body contains. +Gun will automatically set the <code>content-length</code> header.</p></div> +<div class="paragraph"><p>The body sent in this request will be processed +according to the resource’s own semantics. A new +resource may be created as a result, and may be +located at a different URI.</p></div> +<div class="paragraph"><p>The complete request is sent when calling this function. +It is not possible to stream more of the body after +calling it.</p></div> +</div> +<div class="sect2"> +<h3 id="_put_connpid_path_headers_8594_streamref">put(ConnPid, Path, Headers) → StreamRef</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Path = iodata() +</dt> +<dd> +<p> +Path to the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), iodata()}] +</dt> +<dd> +<p> +Additional request headers. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream for this request. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Create or replace a resource.</p></div> +<div class="paragraph"><p>The body of the request is the entire representation of the resource.</p></div> +<div class="paragraph"><p>This function expects either <code>content-length</code> or <code>content-type</code> +to be set to know a body is going to be sent afterwards. +Gun will assume the request has no body otherwise. It is +highly recommended to set both when possible.</p></div> +<div class="paragraph"><p>You can use the <code>gun:data/4</code> function to send the body, if any.</p></div> +</div> +<div class="sect2"> +<h3 id="_put_connpid_path_headers_body_8594_put_connpid_path_headers_body">put(ConnPid, Path, Headers, Body) → put(ConnPid, Path, Headers, Body, #{})</h3> +<div class="paragraph"><p>Alias of <code>gun:put/5</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_put_connpid_path_headers_body_reqopts_8594_streamref">put(ConnPid, Path, Headers, Body, ReqOpts) → StreamRef</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Path = iodata() +</dt> +<dd> +<p> +Path to the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), iodata()}] +</dt> +<dd> +<p> +Additional request headers. +</p> +</dd> +<dt class="hdlist1"> +Body = iodata() +</dt> +<dd> +<p> +Body of the request. +</p> +</dd> +<dt class="hdlist1"> +ReqOpts = req_opts() +</dt> +<dd> +<p> +Request options. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream for this request. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Create or replace a resource.</p></div> +<div class="paragraph"><p>The body of the request is the entire representation of the resource.</p></div> +<div class="paragraph"><p>It is highly recommended to set the <code>content-type</code> header +to inform the server what media type the body contains. +Gun will automatically set the <code>content-length</code> header.</p></div> +<div class="paragraph"><p>The complete request is sent when calling this function. +It is not possible to stream more of the body after +calling it.</p></div> +</div> +<div class="sect2"> +<h3 id="_request_connpid_method_path_headers_8594_streamref">request(ConnPid, Method, Path, Headers) → StreamRef</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Method = iodata() +</dt> +<dd> +<p> +Request method. +</p> +</dd> +<dt class="hdlist1"> +Path = iodata() +</dt> +<dd> +<p> +Path of the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), iodata()}] +</dt> +<dd> +<p> +Additional request headers. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream for this request. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Perform the given request.</p></div> +<div class="paragraph"><p>This is a general purpose function that should only be used +when existing method-specific functions don’t apply.</p></div> +<div class="paragraph"><p>This function expects either <code>content-length</code> or <code>content-type</code> +to be set to know a body is going to be sent afterwards. +Gun will assume the request has no body otherwise. It is +highly recommended to set both when possible.</p></div> +<div class="paragraph"><p>You can use the <code>gun:data/4</code> function to send the body, if any.</p></div> +</div> +<div class="sect2"> +<h3 id="_request_connpid_method_path_headers_body_8594_request_connpid_method_path_headers_body">request(ConnPid, Method, Path, Headers, Body) → request(ConnPid, Method, Path, Headers, Body, #{})</h3> +<div class="paragraph"><p>Alias of <code>gun:request/6</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_request_connpid_method_path_headers_body_reqopts_8594_streamref">request(ConnPid, Method, Path, Headers, Body, ReqOpts) → StreamRef</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Method = iodata() +</dt> +<dd> +<p> +Request method. +</p> +</dd> +<dt class="hdlist1"> +Path = iodata() +</dt> +<dd> +<p> +Path of the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), iodata()}] +</dt> +<dd> +<p> +Additional request headers. +</p> +</dd> +<dt class="hdlist1"> +Body = iodata() +</dt> +<dd> +<p> +Body of the request. +</p> +</dd> +<dt class="hdlist1"> +ReqOpts = req_opts() +</dt> +<dd> +<p> +Request options. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream for this request. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Perform the given request.</p></div> +<div class="paragraph"><p>This is a general purpose function that should only be used +when existing method-specific functions don’t apply.</p></div> +<div class="paragraph"><p>It is highly recommended to set the <code>content-type</code> header +to inform the server what media type the body contains. +Gun will automatically set the <code>content-length</code> header.</p></div> +<div class="paragraph"><p>The complete request is sent when calling this function. +It is not possible to stream more of the body after +calling it.</p></div> +</div> +<div class="sect2"> +<h3 id="_data_connpid_streamref_isfin_data_8594_ok">data(ConnPid, StreamRef, IsFin, Data) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream this data belongs to. +</p> +</dd> +<dt class="hdlist1"> +IsFin = fin | nofin +</dt> +<dd> +<p> +Whether this message terminates the request. +</p> +</dd> +<dt class="hdlist1"> +Data = iodata() +</dt> +<dd> +<p> +Data to be sent with the request. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Stream the body of a request.</p></div> +<div class="paragraph"><p>@todo empty chunks</p></div> +<div class="paragraph"><p>This function can only be used if the request identified by +<code>StreamRef</code> came with headers indicating the presence of a +body and that body not being given when creating the request.</p></div> +<div class="paragraph"><p>All calls to this function must use <code>nofin</code> except for the +last which must use <code>fin</code> to indicate the end of the request +body.</p></div> +<div class="paragraph"><p>Empty data is allowed regardless of the value of <code>IsFin</code>. +Gun will not send empty data chunks unless required to +indicate the request body is finished, however.</p></div> +</div> +<div class="sect2"> +<h3 id="_await_connpid_streamref_8594_await_connpid_streamref_5000_monitorref">await(ConnPid, StreamRef) → await(ConnPid, StreamRef, 5000, MonitorRef)</h3> +<div class="paragraph"><p>Alias of <code>gun:await/4</code>.</p></div> +<div class="paragraph"><p>A monitor <code>MonitorRef</code> is automatically created for the duration of +this call and an error will be returned if the Gun connection process +terminates.</p></div> +</div> +<div class="sect2"> +<h3 id="_await_connpid_streamref_monitorref_8594_await_connpid_streamref_5000_monitorref">await(ConnPid, StreamRef, MonitorRef) → await(ConnPid, StreamRef, 5000, MonitorRef)</h3> +<div class="paragraph"><p>Alias of <code>gun:await/4</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_await_connpid_streamref_timeout_8594_await_connpid_streamref_timeout_monitorref">await(ConnPid, StreamRef, Timeout) → await(ConnPid, StreamRef, Timeout, MonitorRef)</h3> +<div class="paragraph"><p>Alias of <code>gun:await/4</code>.</p></div> +<div class="paragraph"><p>A monitor <code>MonitorRef</code> is automatically created for the duration of +this call and an error will be returned if the Gun connection process +terminates.</p></div> +</div> +<div class="sect2"> +<h3 id="_await_connpid_streamref_timeout_monitorref_8594_tuple_8201_8212_8201_see_below">await(ConnPid, StreamRef, Timeout, MonitorRef) → tuple() — see below</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream to await messages from. +</p> +</dd> +<dt class="hdlist1"> +Timeout = timeout() +</dt> +<dd> +<p> +How long this function will wait for messages. +</p> +</dd> +<dt class="hdlist1"> +MonitorRef = reference() +</dt> +<dd> +<p> +Monitor reference for the Gun connection process. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Wait for a response message.</p></div> +<div class="paragraph"><p>This function can be used when a synchronous handling of +responses is desired. It will only return when a message +for the given stream is received, on error or on timeout.</p></div> +<div class="paragraph"><p>The return values are described in the next few subsections.</p></div> +<div class="sect3"> +<h4 id="_response_isfin_status_headers">{response, IsFin, Status, Headers}</h4> +<div class="dlist"><dl> +<dt class="hdlist1"> +IsFin = fin | nofin +</dt> +<dd> +<p> +Whether this message terminates the response. +</p> +</dd> +<dt class="hdlist1"> +Status = binary() +</dt> +<dd> +<p> +Status line for the response. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), binary()}] +</dt> +<dd> +<p> +Headers sent with the response. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Equivalent of a <code>gun_response</code> message.</p></div> +</div> +<div class="sect3"> +<h4 id="_data_isfin_data">{data, IsFin, Data}</h4> +<div class="dlist"><dl> +<dt class="hdlist1"> +IsFin = fin | nofin +</dt> +<dd> +<p> +Whether this message terminates the response. +</p> +</dd> +<dt class="hdlist1"> +Data = binary() +</dt> +<dd> +<p> +Data from the stream. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Equivalent of a <code>gun_data</code> message.</p></div> +</div> +<div class="sect3"> +<h4 id="_push_newstreamref_uri_headers">{push, NewStreamRef, URI, Headers}</h4> +<div class="dlist"><dl> +<dt class="hdlist1"> +NewStreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream being pushed. +</p> +</dd> +<dt class="hdlist1"> +URI = binary() +</dt> +<dd> +<p> +URI of the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), binary()}] +</dt> +<dd> +<p> +Headers @todo +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Equivalent of a <code>gun_push</code> message.</p></div> +<div class="paragraph"><p>@todo Same changes as gun_push</p></div> +</div> +<div class="sect3"> +<h4 id="_error_reason">{error, Reason}</h4> +<div class="dlist"><dl> +<dt class="hdlist1"> +Reason = any() +</dt> +<dd> +<p> +Error reason. @todo any? +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Equivalent of a <code>gun_error</code> message.</p></div> +<div class="paragraph"><p>@todo I think we want to distinguish a stream error, a general error, +@todo a DOWN and a timeout error</p></div> +</div> +</div> +<div class="sect2"> +<h3 id="_await_body_connpid_streamref_8594_await_body_connpid_streamref_5000_monitorref">await_body(ConnPid, StreamRef) → await_body(ConnPid, StreamRef, 5000, MonitorRef)</h3> +<div class="paragraph"><p>Alias of <code>gun:await_body/4</code>.</p></div> +<div class="paragraph"><p>A monitor <code>MonitorRef</code> is automatically created for the duration of +this call and an error will be returned if the Gun connection process +terminates.</p></div> +</div> +<div class="sect2"> +<h3 id="_await_body_connpid_streamref_monitorref_8594_await_body_connpid_streamref_5000_monitorref">await_body(ConnPid, StreamRef, MonitorRef) → await_body(ConnPid, StreamRef, 5000, MonitorRef)</h3> +<div class="paragraph"><p>Alias of <code>gun:await_body/4</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_await_body_connpid_streamref_timeout_8594_await_body_connpid_streamref_timeout_monitorref">await_body(ConnPid, StreamRef, Timeout) → await_body(ConnPid, StreamRef, Timeout, MonitorRef)</h3> +<div class="paragraph"><p>Alias of <code>gun:await_body/4</code>.</p></div> +<div class="paragraph"><p>A monitor <code>MonitorRef</code> is automatically created for the duration of +this call and an error will be returned if the Gun connection process +terminates.</p></div> +</div> +<div class="sect2"> +<h3 id="_await_body_connpid_streamref_timeout_monitorref_8594_ok_body_error_reason">await_body(ConnPid, StreamRef, Timeout, MonitorRef) → {ok, Body} | {error, Reason}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream to await messages from. +</p> +</dd> +<dt class="hdlist1"> +Timeout = timeout() +</dt> +<dd> +<p> +How long this function will wait for each message. +</p> +</dd> +<dt class="hdlist1"> +MonitorRef = reference() +</dt> +<dd> +<p> +Monitor reference for the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Body = binary() +</dt> +<dd> +<p> +Body for the given stream. +</p> +</dd> +<dt class="hdlist1"> +Reason = any() +</dt> +<dd> +<p> +Error reason. @todo any? +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Wait for a response body.</p></div> +<div class="paragraph"><p>This function can be used when a synchronous handling of +responses is desired. It will only return when it has +finished fetching the entire response body.</p></div> +<div class="paragraph"><p>The timeout value is <strong>per message</strong>. The actual function call +can last much longer for large bodies.</p></div> +<div class="paragraph"><p>@todo I think we want to distinguish a stream error, a general error, +@todo a DOWN and a timeout error</p></div> +<div class="paragraph"><p>@todo guide might be a little incorrect about await/await_body</p></div> +</div> +<div class="sect2"> +<h3 id="_flush_connpid_8594_ok">flush(ConnPid) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Flush all messages from the Gun connection process from the mailbox.</p></div> +</div> +<div class="sect2"> +<h3 id="_flush_streamref_8594_ok">flush(StreamRef) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Stream identifier. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Flush all messages related to the given stream.</p></div> +</div> +<div class="sect2"> +<h3 id="_cancel_connpid_streamref_8594_ok">cancel(ConnPid, StreamRef) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +StreamRef = reference() +</dt> +<dd> +<p> +Identifier of the stream to cancel. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Cancel the given stream.</p></div> +<div class="paragraph"><p>HTTP/1.1 streams can’t be cancelled. Gun will simply silence +the stream and stop relaying messages.</p></div> +<div class="paragraph"><p>@todo Depending on the length +@todo of a response Gun may also attempt to reconnect rather than +@todo receive the entire response body.</p></div> +<div class="paragraph"><p>HTTP/2 streams can however be cancelled at any time.</p></div> +</div> +<div class="sect2"> +<h3 id="_ws_upgrade_connpid_path_8594_ws_upgrade_connpid_path">ws_upgrade(ConnPid, Path) → ws_upgrade(ConnPid, Path, [], #{})</h3> +<div class="paragraph"><p>Alias of <code>gun:ws_upgrade/3</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_ws_upgrade_connpid_path_headers_8594_ok">ws_upgrade(ConnPid, Path, Headers) → ok</h3> +<div class="paragraph"><p>Similar to <code>gun:ws_upgrade/4</code>, except <code>WsOpts</code> is taken from +the options given in the <code>gun:open/{2,3}</code> call when opening +the connection.</p></div> +</div> +<div class="sect2"> +<h3 id="_ws_upgrade_connpid_path_headers_wsopts_8594_ok">ws_upgrade(ConnPid, Path, Headers, WsOpts) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Path = iodata() +</dt> +<dd> +<p> +Path to the resource. +</p> +</dd> +<dt class="hdlist1"> +Headers = [{binary(), iodata()}] +</dt> +<dd> +<p> +Additional request headers. +</p> +</dd> +<dt class="hdlist1"> +WsOpts = map() +</dt> +<dd> +<p> +Options for the Websocket connection. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Request the connection to be upgraded to the Websocket protocol.</p></div> +<div class="paragraph"><p>This function can only be used when the current protocol is <code>http</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_ws_send_connpid_frames_8594_ok">ws_send(ConnPid, Frames) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +ConnPid = pid() +</dt> +<dd> +<p> +The pid of the Gun connection process. +</p> +</dd> +<dt class="hdlist1"> +Frames = @todo +</dt> +<dd> +<p> +@todo +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Send one or more Websocket frames.</p></div> +<div class="paragraph"><p>This function can only be used following a successful <code>ws_upgrade</code> call.</p></div> +</div> +</div> +</div> diff --git a/docs/en/gun/1.0/manual/gun_app/index.html b/docs/en/gun/1.0/manual/gun_app/index.html index be525d51..5690ca2b 100644 --- a/docs/en/gun/1.0/manual/gun_app/index.html +++ b/docs/en/gun/1.0/manual/gun_app/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: gun(7)</title> @@ -67,34 +67,34 @@ <h1 class="lined-header"><span>gun(7)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>gun - Erlang HTTP client with support for HTTP/1.1, HTTP/2 and Websocket.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_dependencies">Dependencies</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>gun</code> application uses the Erlang applications <code>ranch</code>
-for abstracting TCP and TLS over a common interface, and
-the <code>ssl</code> application for TLS support, required for HTTPS
-and secure HTTP/2 support. In addition, Gun requires the <code>crypto</code>
-application (a dependency of <code>ssl</code>) for Websocket.</p></div>
-<div class="paragraph"><p>These dependencies must be started for the <code>gun</code>
-application to work. In an embedded environment
-this means that they need to be started with the
-<code>application:start/{1,2}</code> function before the <code>gun</code>
-application is started.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_environment">Environment</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>gun</code> application does not define any application
-environment configuration parameters.</p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>gun - Erlang HTTP client with support for HTTP/1.1, HTTP/2 and Websocket.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_dependencies">Dependencies</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>gun</code> application uses the Erlang applications <code>ranch</code> +for abstracting TCP and TLS over a common interface, and +the <code>ssl</code> application for TLS support, required for HTTPS +and secure HTTP/2 support. In addition, Gun requires the <code>crypto</code> +application (a dependency of <code>ssl</code>) for Websocket.</p></div> +<div class="paragraph"><p>These dependencies must be started for the <code>gun</code> +application to work. In an embedded environment +this means that they need to be started with the +<code>application:start/{1,2}</code> function before the <code>gun</code> +application is started.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_environment">Environment</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>gun</code> application does not define any application +environment configuration parameters.</p></div> +</div> +</div> diff --git a/docs/en/gun/1.0/manual/index.html b/docs/en/gun/1.0/manual/index.html index 411e92f0..c3851885 100644 --- a/docs/en/gun/1.0/manual/index.html +++ b/docs/en/gun/1.0/manual/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Gun Function Reference</title> @@ -67,18 +67,18 @@ <h1 class="lined-header"><span>Gun Function Reference</span></h1> -<div class="ulist"><ul>
-<li>
-<p>
-<a href="gun_app">gun(7)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="gun">gun(3)</a>
-</p>
-</li>
-</ul></div>
+<div class="ulist"><ul> +<li> +<p> +<a href="gun_app">gun(7)</a> +</p> +</li> +<li> +<p> +<a href="gun">gun(3)</a> +</p> +</li> +</ul></div> diff --git a/docs/en/gun/index.html b/docs/en/gun/index.html index d87c4243..0194031a 100644 --- a/docs/en/gun/index.html +++ b/docs/en/gun/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file diff --git a/docs/en/index.html b/docs/en/index.html index d87c4243..0194031a 100644 --- a/docs/en/index.html +++ b/docs/en/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file diff --git a/docs/en/ranch/1.2/guide/embedded/index.html b/docs/en/ranch/1.2/guide/embedded/index.html index ac94bf2a..ff2cf499 100644 --- a/docs/en/ranch/1.2/guide/embedded/index.html +++ b/docs/en/ranch/1.2/guide/embedded/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Embedded mode</title> @@ -67,54 +67,57 @@ <h1 class="lined-header"><span>Embedded mode</span></h1> -<div class="paragraph"><p>Embedded mode allows you to insert Ranch listeners directly
-in your supervision tree. This allows for greater fault tolerance
-control by permitting the shutdown of a listener due to the
-failure of another part of the application and vice versa.</p></div>
-<div class="sect1">
-<h2 id="_embedding">Embedding</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To embed Ranch in your application you can simply add the child specs
-to your supervision tree. This can all be done in the <code>init/1</code> function
-of one of your application supervisors.</p></div>
-<div class="paragraph"><p>Ranch requires at the minimum two kinds of child specs for embedding.
-First, you need to add <code>ranch_sup</code> to your supervision tree, only once,
-regardless of the number of listeners you will use. Then you need to
-add the child specs for each listener.</p></div>
-<div class="paragraph"><p>Ranch has a convenience function for getting the listeners child specs
-called <code>ranch:child_spec/6</code>, that works like <code>ranch:start_listener/6</code>,
-except that it doesn’t start anything, it only returns child specs.</p></div>
-<div class="paragraph"><p>As for <code>ranch_sup</code>, the child spec is simple enough to not require a
-convenience function.</p></div>
-<div class="paragraph"><p>The following example adds both <code>ranch_sup</code> and one listener to another
-application’s supervision tree.</p></div>
-<div class="listingblock">
-<div class="title">Embed Ranch directly in your supervision tree</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="font-weight: bold"><span style="color: #000000">init</span></span>([]) <span style="color: #990000">-></span>
- <span style="color: #009900">RanchSupSpec</span> <span style="color: #990000">=</span> {<span style="color: #FF6600">ranch_sup</span>, {<span style="color: #FF6600">ranch_sup</span>, <span style="color: #FF6600">start_link</span>, []},
- <span style="color: #FF6600">permanent</span>, <span style="color: #993399">5000</span>, <span style="color: #FF6600">supervisor</span>, [<span style="color: #FF6600">ranch_sup</span>]},
- <span style="color: #009900">ListenerSpec</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:child_spec</span></span>(<span style="color: #FF6600">echo</span>, <span style="color: #993399">100</span>,
- <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}],
- <span style="color: #FF6600">echo_protocol</span>, []
- ),
- {<span style="color: #FF6600">ok</span>, {{<span style="color: #FF6600">one_for_one</span>, <span style="color: #993399">10</span>, <span style="color: #993399">10</span>}, [<span style="color: #009900">RanchSupSpec</span>, <span style="color: #009900">ListenerSpec</span>]}}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Remember, you can add as many listener child specs as needed, but only
-one <code>ranch_sup</code> spec!</p></div>
-<div class="paragraph"><p>It is recommended that your architecture makes sure that all listeners
-are restarted if <code>ranch_sup</code> fails. See the Ranch internals chapter for
-more details on how Ranch does it.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Embedded mode allows you to insert Ranch listeners directly +in your supervision tree. This allows for greater fault tolerance +control by permitting the shutdown of a listener due to the +failure of another part of the application and vice versa.</p></div> +<div class="sect1"> +<h2 id="_embedding">Embedding</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To embed Ranch in your application you can simply add the child specs +to your supervision tree. This can all be done in the <code>init/1</code> function +of one of your application supervisors.</p></div> +<div class="paragraph"><p>Ranch requires at the minimum two kinds of child specs for embedding. +First, you need to add <code>ranch_sup</code> to your supervision tree, only once, +regardless of the number of listeners you will use. Then you need to +add the child specs for each listener.</p></div> +<div class="paragraph"><p>Ranch has a convenience function for getting the listeners child specs +called <code>ranch:child_spec/6</code>, that works like <code>ranch:start_listener/6</code>, +except that it doesn’t start anything, it only returns child specs.</p></div> +<div class="paragraph"><p>As for <code>ranch_sup</code>, the child spec is simple enough to not require a +convenience function.</p></div> +<div class="paragraph"><p>The following example adds both <code>ranch_sup</code> and one listener to another +application’s supervision tree.</p></div> +<div class="listingblock"> +<div class="title">Embed Ranch directly in your supervision tree</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="font-weight: bold"><span style="color: #000000">init</span></span>([]) <span style="color: #990000">-></span> + <span style="color: #009900">RanchSupSpec</span> <span style="color: #990000">=</span> {<span style="color: #FF6600">ranch_sup</span>, {<span style="color: #FF6600">ranch_sup</span>, <span style="color: #FF6600">start_link</span>, []}, + <span style="color: #FF6600">permanent</span>, <span style="color: #993399">5000</span>, <span style="color: #FF6600">supervisor</span>, [<span style="color: #FF6600">ranch_sup</span>]}, + <span style="color: #009900">ListenerSpec</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:child_spec</span></span>(<span style="color: #FF6600">echo</span>, <span style="color: #993399">100</span>, + <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}], + <span style="color: #FF6600">echo_protocol</span>, [] + ), + {<span style="color: #FF6600">ok</span>, {{<span style="color: #FF6600">one_for_one</span>, <span style="color: #993399">10</span>, <span style="color: #993399">10</span>}, [<span style="color: #009900">RanchSupSpec</span>, <span style="color: #009900">ListenerSpec</span>]}}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Remember, you can add as many listener child specs as needed, but only +one <code>ranch_sup</code> spec!</p></div> +<div class="paragraph"><p>It is recommended that your architecture makes sure that all listeners +are restarted if <code>ranch_sup</code> fails. See the Ranch internals chapter for +more details on how Ranch does it.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.2/guide/index.html b/docs/en/ranch/1.2/guide/index.html index 2b1b7e05..cd37ce05 100644 --- a/docs/en/ranch/1.2/guide/index.html +++ b/docs/en/ranch/1.2/guide/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Ranch User Guide</title> @@ -67,48 +67,48 @@ <h1 class="lined-header"><span>Ranch User Guide</span></h1> -<div class="ulist"><ul>
-<li>
-<p>
-<a href="introduction/">Introduction</a>
-</p>
-</li>
-<li>
-<p>
-<a href="listeners/">Listeners</a>
-</p>
-</li>
-<li>
-<p>
-<a href="transports/">Transports</a>
-</p>
-</li>
-<li>
-<p>
-<a href="protocols/">Protocols</a>
-</p>
-</li>
-<li>
-<p>
-<a href="embedded/">Embedded mode</a>
-</p>
-</li>
-<li>
-<p>
-<a href="parsers/">Writing parsers</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ssl_auth/">SSL client authentication</a>
-</p>
-</li>
-<li>
-<p>
-<a href="internals/">Internals</a>
-</p>
-</li>
-</ul></div>
+<div class="ulist"><ul> +<li> +<p> +<a href="introduction/">Introduction</a> +</p> +</li> +<li> +<p> +<a href="listeners/">Listeners</a> +</p> +</li> +<li> +<p> +<a href="transports/">Transports</a> +</p> +</li> +<li> +<p> +<a href="protocols/">Protocols</a> +</p> +</li> +<li> +<p> +<a href="embedded/">Embedded mode</a> +</p> +</li> +<li> +<p> +<a href="parsers/">Writing parsers</a> +</p> +</li> +<li> +<p> +<a href="ssl_auth/">SSL client authentication</a> +</p> +</li> +<li> +<p> +<a href="internals/">Internals</a> +</p> +</li> +</ul></div> diff --git a/docs/en/ranch/1.2/guide/internals/index.html b/docs/en/ranch/1.2/guide/internals/index.html index 88466f8e..0f731816 100644 --- a/docs/en/ranch/1.2/guide/internals/index.html +++ b/docs/en/ranch/1.2/guide/internals/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Internals</title> @@ -67,99 +67,102 @@ <h1 class="lined-header"><span>Internals</span></h1> -<div class="paragraph"><p>This chapter may not apply to embedded Ranch as embedding allows you
-to use an architecture specific to your application, which may or may
-not be compatible with the description of the Ranch application.</p></div>
-<div class="paragraph"><p>Note that for everything related to efficiency and performance,
-you should perform the benchmarks yourself to get the numbers that
-matter to you. Generic benchmarks found on the web may or may not
-be of use to you, you can never know until you benchmark your own
-system.</p></div>
-<div class="sect1">
-<h2 id="_architecture">Architecture</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch is an OTP application.</p></div>
-<div class="paragraph"><p>Like all OTP applications, Ranch has a top supervisor. It is responsible
-for supervising the <code>ranch_server</code> process and all the listeners that
-will be started.</p></div>
-<div class="paragraph"><p>The <code>ranch_server</code> gen_server is a central process keeping track of the
-listeners and their acceptors. It does so through the use of a public ets
-table called <code>ranch_server</code>. The table is owned by the top supervisor
-to improve fault tolerance. This way if the <code>ranch_server</code> gen_server
-fails, it doesn’t lose any information and the restarted process can
-continue as if nothing happened.</p></div>
-<div class="paragraph"><p>Ranch uses a custom supervisor for managing connections. This supervisor
-keeps track of the number of connections and handles connection limits
-directly. While it is heavily optimized to perform the task of creating
-connection processes for accepted connections, it is still following the
-OTP principles and the usual <code>sys</code> and <code>supervisor</code> calls will work on
-it as expected.</p></div>
-<div class="paragraph"><p>Listeners are grouped into the <code>ranch_listener_sup</code> supervisor and
-consist of three kinds of processes: the listener gen_server, the
-acceptor processes and the connection processes, both grouped under
-their own supervisor. All of these processes are registered to the
-<code>ranch_server</code> gen_server with varying amount of information.</p></div>
-<div class="paragraph"><p>All socket operations, including listening for connections, go through
-transport handlers. Accepted connections are given to the protocol handler.
-Transport handlers are simple callback modules for performing operations on
-sockets. Protocol handlers start a new process, which receives socket
-ownership, with no requirements on how the code should be written inside
-that new process.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_number_of_acceptors">Number of acceptors</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The second argument to <code>ranch:start_listener/6</code> is the number of
-processes that will be accepting connections. Care should be taken
-when choosing this number.</p></div>
-<div class="paragraph"><p>First of all, it should not be confused with the maximum number
-of connections. Acceptor processes are only used for accepting and
-have nothing else in common with connection processes. Therefore
-there is nothing to be gained from setting this number too high,
-in fact it can slow everything else down.</p></div>
-<div class="paragraph"><p>Second, this number should be high enough to allow Ranch to accept
-connections concurrently. But the number of cores available doesn’t
-seem to be the only factor for choosing this number, as we can
-observe faster accepts if we have more acceptors than cores. It
-might be entirely dependent on the protocol, however.</p></div>
-<div class="paragraph"><p>Our observations suggest that using 100 acceptors on modern hardware
-is a good solution, as it’s big enough to always have acceptors ready
-and it’s low enough that it doesn’t have a negative impact on the
-system’s performances.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_platform_specific_tcp_features">Platform-specific TCP features</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Some socket options are platform-specific and not supported by <code>inet</code>.
-They can be of interest because they generally are related to
-optimizations provided by the underlying OS. They can still be enabled
-thanks to the <code>raw</code> option, for which we will see an example.</p></div>
-<div class="paragraph"><p>One of these features is <code>TCP_DEFER_ACCEPT</code> on Linux. It is a simplified
-accept mechanism which will wait for application data to come in before
-handing out the connection to the Erlang process.</p></div>
-<div class="paragraph"><p>This is especially useful if you expect many connections to be mostly
-idle, perhaps part of a connection pool. They can be handled by the
-kernel directly until they send any real data, instead of allocating
-resources to idle connections.</p></div>
-<div class="paragraph"><p>To enable this mechanism, the following option can be used.</p></div>
-<div class="listingblock">
-<div class="title">Using raw transport options</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: #FF6600">raw</span>, <span style="color: #993399">6</span>, <span style="color: #993399">9</span>, <span style="color: #990000"><<</span> <span style="font-weight: bold"><span style="color: #000000">30:32</span></span><span style="color: #990000">/</span><span style="color: #FF6600">native</span> <span style="color: #990000">>></span>}</tt></pre></div></div>
-<div class="paragraph"><p>It means go on layer 6, turn on option 9 with the given integer parameter.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter may not apply to embedded Ranch as embedding allows you +to use an architecture specific to your application, which may or may +not be compatible with the description of the Ranch application.</p></div> +<div class="paragraph"><p>Note that for everything related to efficiency and performance, +you should perform the benchmarks yourself to get the numbers that +matter to you. Generic benchmarks found on the web may or may not +be of use to you, you can never know until you benchmark your own +system.</p></div> +<div class="sect1"> +<h2 id="_architecture">Architecture</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch is an OTP application.</p></div> +<div class="paragraph"><p>Like all OTP applications, Ranch has a top supervisor. It is responsible +for supervising the <code>ranch_server</code> process and all the listeners that +will be started.</p></div> +<div class="paragraph"><p>The <code>ranch_server</code> gen_server is a central process keeping track of the +listeners and their acceptors. It does so through the use of a public ets +table called <code>ranch_server</code>. The table is owned by the top supervisor +to improve fault tolerance. This way if the <code>ranch_server</code> gen_server +fails, it doesn’t lose any information and the restarted process can +continue as if nothing happened.</p></div> +<div class="paragraph"><p>Ranch uses a custom supervisor for managing connections. This supervisor +keeps track of the number of connections and handles connection limits +directly. While it is heavily optimized to perform the task of creating +connection processes for accepted connections, it is still following the +OTP principles and the usual <code>sys</code> and <code>supervisor</code> calls will work on +it as expected.</p></div> +<div class="paragraph"><p>Listeners are grouped into the <code>ranch_listener_sup</code> supervisor and +consist of three kinds of processes: the listener gen_server, the +acceptor processes and the connection processes, both grouped under +their own supervisor. All of these processes are registered to the +<code>ranch_server</code> gen_server with varying amount of information.</p></div> +<div class="paragraph"><p>All socket operations, including listening for connections, go through +transport handlers. Accepted connections are given to the protocol handler. +Transport handlers are simple callback modules for performing operations on +sockets. Protocol handlers start a new process, which receives socket +ownership, with no requirements on how the code should be written inside +that new process.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_number_of_acceptors">Number of acceptors</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The second argument to <code>ranch:start_listener/6</code> is the number of +processes that will be accepting connections. Care should be taken +when choosing this number.</p></div> +<div class="paragraph"><p>First of all, it should not be confused with the maximum number +of connections. Acceptor processes are only used for accepting and +have nothing else in common with connection processes. Therefore +there is nothing to be gained from setting this number too high, +in fact it can slow everything else down.</p></div> +<div class="paragraph"><p>Second, this number should be high enough to allow Ranch to accept +connections concurrently. But the number of cores available doesn’t +seem to be the only factor for choosing this number, as we can +observe faster accepts if we have more acceptors than cores. It +might be entirely dependent on the protocol, however.</p></div> +<div class="paragraph"><p>Our observations suggest that using 100 acceptors on modern hardware +is a good solution, as it’s big enough to always have acceptors ready +and it’s low enough that it doesn’t have a negative impact on the +system’s performances.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_platform_specific_tcp_features">Platform-specific TCP features</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Some socket options are platform-specific and not supported by <code>inet</code>. +They can be of interest because they generally are related to +optimizations provided by the underlying OS. They can still be enabled +thanks to the <code>raw</code> option, for which we will see an example.</p></div> +<div class="paragraph"><p>One of these features is <code>TCP_DEFER_ACCEPT</code> on Linux. It is a simplified +accept mechanism which will wait for application data to come in before +handing out the connection to the Erlang process.</p></div> +<div class="paragraph"><p>This is especially useful if you expect many connections to be mostly +idle, perhaps part of a connection pool. They can be handled by the +kernel directly until they send any real data, instead of allocating +resources to idle connections.</p></div> +<div class="paragraph"><p>To enable this mechanism, the following option can be used.</p></div> +<div class="listingblock"> +<div class="title">Using raw transport options</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: #FF6600">raw</span>, <span style="color: #993399">6</span>, <span style="color: #993399">9</span>, <span style="color: #990000"><<</span> <span style="font-weight: bold"><span style="color: #000000">30:32</span></span><span style="color: #990000">/</span><span style="color: #FF6600">native</span> <span style="color: #990000">>></span>}</tt></pre></div></div> +<div class="paragraph"><p>It means go on layer 6, turn on option 9 with the given integer parameter.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.2/guide/introduction/index.html b/docs/en/ranch/1.2/guide/introduction/index.html index 8d2e565c..130721a0 100644 --- a/docs/en/ranch/1.2/guide/introduction/index.html +++ b/docs/en/ranch/1.2/guide/introduction/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Introduction</title> @@ -67,38 +67,41 @@ <h1 class="lined-header"><span>Introduction</span></h1> -<div class="paragraph"><p>Ranch is a socket acceptor pool for TCP protocols.</p></div>
-<div class="paragraph"><p>Ranch aims to provide everything you need to accept TCP connections
-with a small code base and low latency while being easy to use directly
-as an application or to embed into your own.</p></div>
-<div class="sect1">
-<h2 id="_prerequisites">Prerequisites</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>It is assumed the developer already knows Erlang and has some experience
-with socket programming and TCP protocols.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_supported_platforms">Supported platforms</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch is tested and supported on Linux.</p></div>
-<div class="paragraph"><p>Ranch is developed for Erlang R15B01+.</p></div>
-<div class="paragraph"><p>Ranch may be compiled on earlier Erlang versions with small source code
-modifications but there is no guarantee that it will work as expected.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_versioning">Versioning</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch uses <a href="http://semver.org/">Semantic Versioning 2.0.0</a></p></div>
-</div>
-</div>
+<div class="paragraph"><p>Ranch is a socket acceptor pool for TCP protocols.</p></div> +<div class="paragraph"><p>Ranch aims to provide everything you need to accept TCP connections +with a small code base and low latency while being easy to use directly +as an application or to embed into your own.</p></div> +<div class="sect1"> +<h2 id="_prerequisites">Prerequisites</h2> +<div class="sectionbody"> +<div class="paragraph"><p>It is assumed the developer already knows Erlang and has some experience +with socket programming and TCP protocols.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_supported_platforms">Supported platforms</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch is tested and supported on Linux.</p></div> +<div class="paragraph"><p>Ranch is developed for Erlang R15B01+.</p></div> +<div class="paragraph"><p>Ranch may be compiled on earlier Erlang versions with small source code +modifications but there is no guarantee that it will work as expected.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_versioning">Versioning</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch uses <a href="http://semver.org/">Semantic Versioning 2.0.0</a></p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.2/guide/listeners/index.html b/docs/en/ranch/1.2/guide/listeners/index.html index eff0e0ed..83c092a0 100644 --- a/docs/en/ranch/1.2/guide/listeners/index.html +++ b/docs/en/ranch/1.2/guide/listeners/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Listeners</title> @@ -67,293 +67,296 @@ <h1 class="lined-header"><span>Listeners</span></h1> -<div class="paragraph"><p>A listener is a set of processes whose role is to listen on a port
-for new connections. It manages a pool of acceptor processes, each
-of them indefinitely accepting connections. When it does, it starts
-a new process executing the protocol handler code. All the socket
-programming is abstracted through the user of transport handlers.</p></div>
-<div class="paragraph"><p>The listener takes care of supervising all the acceptor and connection
-processes, allowing developers to focus on building their application.</p></div>
-<div class="sect1">
-<h2 id="_starting_a_listener">Starting a listener</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch does nothing by default. It is up to the application developer
-to request that Ranch listens for connections.</p></div>
-<div class="paragraph"><p>A listener can be started and stopped at will.</p></div>
-<div class="paragraph"><p>When starting a listener, a number of different settings are required:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-A name to identify it locally and be able to interact with it.
-</p>
-</li>
-<li>
-<p>
-The number of acceptors in the pool.
-</p>
-</li>
-<li>
-<p>
-A transport handler and its associated options.
-</p>
-</li>
-<li>
-<p>
-A protocol handler and its associated options.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Ranch includes both TCP and SSL transport handlers, respectively
-<code>ranch_tcp</code> and <code>ranch_ssl</code>.</p></div>
-<div class="paragraph"><p>A listener can be started by calling the <code>ranch:start_listener/6</code>
-function. Before doing so however, you must ensure that the <code>ranch</code>
-application is started.</p></div>
-<div class="listingblock">
-<div class="title">Starting the Ranch application</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: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">application:start</span></span>(<span style="color: #FF6600">ranch</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You are then ready to start a listener. Let’s call it <code>tcp_echo</code>. It will
-have a pool of 100 acceptors, use a TCP transport and forward connections
-to the <code>echo_protocol</code> handler.</p></div>
-<div class="listingblock">
-<div class="title">Starting a listener for TCP connections on port 5555</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: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #993399">100</span>,
- <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}],
- <span style="color: #FF6600">echo_protocol</span>, []
-)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can try this out by compiling and running the <code>tcp_echo</code> example in the
-examples directory. To do so, open a shell in the <em>examples/tcp_echo/</em>
-directory and run the following command:</p></div>
-<div class="listingblock">
-<div class="title">Building and starting a Ranch example</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>$ make run</tt></pre></div></div>
-<div class="paragraph"><p>You can then connect to it using telnet and see the echo server reply
-everything you send to it. Then when you’re done testing, you can use
-the <code>Ctrl+]</code> key to escape to the telnet command line and type
-<code>quit</code> to exit.</p></div>
-<div class="listingblock">
-<div class="title">Connecting to the example listener with telnet</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>$ telnet localhost <span style="color: #993399">5555</span>
-Trying <span style="color: #993399">127.0</span><span style="color: #990000">.</span><span style="color: #993399">0.1</span><span style="color: #990000">...</span>
-Connected to localhost<span style="color: #990000">.</span>
-Escape character is <span style="color: #FF0000">'^]'</span><span style="color: #990000">.</span>
-Hello<span style="color: #990000">!</span>
-Hello<span style="color: #990000">!</span>
-It works<span style="color: #990000">!</span>
-It works<span style="color: #990000">!</span>
-<span style="color: #990000">^]</span>
-
-telnet<span style="color: #990000">></span> quit
-Connection closed<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_stopping_a_listener">Stopping a listener</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>All you need to stop a Ranch listener is to call the
-<code>ranch:stop_listener/1</code> function with the listener’s name
-as argument. In the previous section we started the listener
-named <code>tcp_echo</code>. We can now stop it.</p></div>
-<div class="listingblock">
-<div class="title">Stopping a listener</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="font-weight: bold"><span style="color: #000000">ranch:stop_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_default_transport_options">Default transport options</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>By default the socket will be set to return <code>binary</code> data, with the
-options <code>{active, false}</code>, <code>{packet, raw}</code>, <code>{reuseaddr, true}</code> set.
-These values can’t be overriden when starting the listener, but
-they can be overriden using <code>Transport:setopts/2</code> in the protocol.</p></div>
-<div class="paragraph"><p>It will also set <code>{backlog, 1024}</code> and <code>{nodelay, true}</code>, which
-can be overriden at listener startup.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_listening_on_a_random_port">Listening on a random port</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You do not have to specify a specific port to listen on. If you give
-the port number 0, or if you omit the port number entirely, Ranch will
-start listening on a random port.</p></div>
-<div class="paragraph"><p>You can retrieve this port number by calling <code>ranch:get_port/1</code>. The
-argument is the name of the listener you gave in <code>ranch:start_listener/6</code>.</p></div>
-<div class="listingblock">
-<div class="title">Starting a listener for TCP connections on a random port</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: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #993399">100</span>,
- <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">0</span>}],
- <span style="color: #FF6600">echo_protocol</span>, []
-)<span style="color: #990000">.</span>
-<span style="color: #009900">Port</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_port</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_listening_on_privileged_ports">Listening on privileged ports</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Some systems limit access to ports below 1024 for security reasons.
-This can easily be identified by an <code>{error, eacces}</code> error when trying
-to open a listening socket on such a port.</p></div>
-<div class="paragraph"><p>The methods for listening on privileged ports vary between systems,
-please refer to your system’s documentation for more information.</p></div>
-<div class="paragraph"><p>We recommend the use of port rewriting for systems with a single server,
-and load balancing for systems with multiple servers. Documenting these
-solutions is however out of the scope of this guide.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_accepting_connections_on_an_existing_socket">Accepting connections on an existing socket</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>If you want to accept connections on an existing socket, you can use the
-<code>socket</code> transport option, which should just be the relevant data returned
-from the connect function for the transport or the underlying socket library
-(<code>gen_tcp:connect</code>, <code>ssl:connect</code>). The accept function will then be
-called on the passed in socket. You should connect the socket in
-<code>{active, false}</code> mode, as well.</p></div>
-<div class="paragraph"><p>Note, however, that because of a bug in SSL, you cannot change ownership of an
-SSL listen socket prior to R16. Ranch will catch the error thrown, but the
-owner of the SSL socket will remain as whatever process created the socket.
-However, this will not affect accept behaviour unless the owner process dies,
-in which case the socket is closed. Therefore, to use this feature with SSL
-with an erlang release prior to R16, ensure that the SSL socket is opened in a
-persistant process.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_limiting_the_number_of_concurrent_connections">Limiting the number of concurrent connections</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>max_connections</code> transport option allows you to limit the number
-of concurrent connections. It defaults to 1024. Its purpose is to
-prevent your system from being overloaded and ensuring all the
-connections are handled optimally.</p></div>
-<div class="listingblock">
-<div class="title">Customizing the maximum number of concurrent connections</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: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #993399">100</span>,
- <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">max_connections</span>, <span style="color: #993399">100</span>}],
- <span style="color: #FF6600">echo_protocol</span>, []
-)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can disable this limit by setting its value to the atom <code>infinity</code>.</p></div>
-<div class="listingblock">
-<div class="title">Disabling the limit for the number of connections</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: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #993399">100</span>,
- <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">max_connections</span>, <span style="color: #FF6600">infinity</span>}],
- <span style="color: #FF6600">echo_protocol</span>, []
-)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You may not always want connections to be counted when checking for
-<code>max_connections</code>. For example you might have a protocol where both
-short-lived and long-lived connections are possible. If the long-lived
-connections are mostly waiting for messages, then they don’t consume
-much resources and can safely be removed from the count.</p></div>
-<div class="paragraph"><p>To remove the connection from the count, you must call the
-<code>ranch:remove_connection/1</code> from within the connection process,
-with the name of the listener as the only argument.</p></div>
-<div class="listingblock">
-<div class="title">Removing a connection from the count of connections</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="font-weight: bold"><span style="color: #000000">ranch:remove_connection</span></span>(<span style="color: #009900">Ref</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>As seen in the chapter covering protocols, this pid is received as the
-first argument of the protocol’s <code>start_link/4</code> callback.</p></div>
-<div class="paragraph"><p>You can modify the <code>max_connections</code> value on a running listener by
-using the <code>ranch:set_max_connections/2</code> function, with the name of the
-listener as first argument and the new value as the second.</p></div>
-<div class="listingblock">
-<div class="title">Upgrading the maximum number of connections</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="font-weight: bold"><span style="color: #000000">ranch:set_max_connections</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #009900">MaxConns</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The change will occur immediately.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_using_a_supervisor_for_connection_processes">Using a supervisor for connection processes</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch allows you to define the type of process that will be used
-for the connection processes. By default it expects a <code>worker</code>.
-When the <code>connection_type</code> configuration value is set to <code>supervisor</code>,
-Ranch will consider that the connection process it manages is a
-supervisor and will reflect that in its supervision tree.</p></div>
-<div class="paragraph"><p>Connection processes of type <code>supervisor</code> can either handle the
-socket directly or through one of their children. In the latter
-case the start function for the connection process must return
-two pids: the pid of the supervisor you created (that will be
-supervised) and the pid of the protocol handling process (that
-will receive the socket).</p></div>
-<div class="paragraph"><p>Instead of returning <code>{ok, ConnPid}</code>, simply return
-<code>{ok, SupPid, ConnPid}</code>.</p></div>
-<div class="paragraph"><p>It is very important that the connection process be created
-under the supervisor process so that everything works as intended.
-If not, you will most likely experience issues when the supervised
-process is stopped.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_upgrading">Upgrading</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch allows you to upgrade the protocol options. This takes effect
-immediately and for all subsequent connections.</p></div>
-<div class="paragraph"><p>To upgrade the protocol options, call <code>ranch:set_protocol_options/2</code>
-with the name of the listener as first argument and the new options
-as the second.</p></div>
-<div class="listingblock">
-<div class="title">Upgrading the protocol options</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="font-weight: bold"><span style="color: #000000">ranch:set_protocol_options</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #009900">NewOpts</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>All future connections will use the new options.</p></div>
-<div class="paragraph"><p>You can also retrieve the current options similarly by
-calling <code>ranch:get_protocol_options/1</code>.</p></div>
-<div class="listingblock">
-<div class="title">Retrieving the current protocol options</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">Opts</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_protocol_options</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
+<div class="paragraph"><p>A listener is a set of processes whose role is to listen on a port +for new connections. It manages a pool of acceptor processes, each +of them indefinitely accepting connections. When it does, it starts +a new process executing the protocol handler code. All the socket +programming is abstracted through the user of transport handlers.</p></div> +<div class="paragraph"><p>The listener takes care of supervising all the acceptor and connection +processes, allowing developers to focus on building their application.</p></div> +<div class="sect1"> +<h2 id="_starting_a_listener">Starting a listener</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch does nothing by default. It is up to the application developer +to request that Ranch listens for connections.</p></div> +<div class="paragraph"><p>A listener can be started and stopped at will.</p></div> +<div class="paragraph"><p>When starting a listener, a number of different settings are required:</p></div> +<div class="ulist"><ul> +<li> +<p> +A name to identify it locally and be able to interact with it. +</p> +</li> +<li> +<p> +The number of acceptors in the pool. +</p> +</li> +<li> +<p> +A transport handler and its associated options. +</p> +</li> +<li> +<p> +A protocol handler and its associated options. +</p> +</li> +</ul></div> +<div class="paragraph"><p>Ranch includes both TCP and SSL transport handlers, respectively +<code>ranch_tcp</code> and <code>ranch_ssl</code>.</p></div> +<div class="paragraph"><p>A listener can be started by calling the <code>ranch:start_listener/6</code> +function. Before doing so however, you must ensure that the <code>ranch</code> +application is started.</p></div> +<div class="listingblock"> +<div class="title">Starting the Ranch application</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: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">application:start</span></span>(<span style="color: #FF6600">ranch</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You are then ready to start a listener. Let’s call it <code>tcp_echo</code>. It will +have a pool of 100 acceptors, use a TCP transport and forward connections +to the <code>echo_protocol</code> handler.</p></div> +<div class="listingblock"> +<div class="title">Starting a listener for TCP connections on port 5555</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: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #993399">100</span>, + <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}], + <span style="color: #FF6600">echo_protocol</span>, [] +)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You can try this out by compiling and running the <code>tcp_echo</code> example in the +examples directory. To do so, open a shell in the <em>examples/tcp_echo/</em> +directory and run the following command:</p></div> +<div class="listingblock"> +<div class="title">Building and starting a Ranch example</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>$ make run</tt></pre></div></div> +<div class="paragraph"><p>You can then connect to it using telnet and see the echo server reply +everything you send to it. Then when you’re done testing, you can use +the <code>Ctrl+]</code> key to escape to the telnet command line and type +<code>quit</code> to exit.</p></div> +<div class="listingblock"> +<div class="title">Connecting to the example listener with telnet</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>$ telnet localhost <span style="color: #993399">5555</span> +Trying <span style="color: #993399">127.0</span><span style="color: #990000">.</span><span style="color: #993399">0.1</span><span style="color: #990000">...</span> +Connected to localhost<span style="color: #990000">.</span> +Escape character is <span style="color: #FF0000">'^]'</span><span style="color: #990000">.</span> +Hello<span style="color: #990000">!</span> +Hello<span style="color: #990000">!</span> +It works<span style="color: #990000">!</span> +It works<span style="color: #990000">!</span> +<span style="color: #990000">^]</span> + +telnet<span style="color: #990000">></span> quit +Connection closed<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_stopping_a_listener">Stopping a listener</h2> +<div class="sectionbody"> +<div class="paragraph"><p>All you need to stop a Ranch listener is to call the +<code>ranch:stop_listener/1</code> function with the listener’s name +as argument. In the previous section we started the listener +named <code>tcp_echo</code>. We can now stop it.</p></div> +<div class="listingblock"> +<div class="title">Stopping a listener</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="font-weight: bold"><span style="color: #000000">ranch:stop_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_default_transport_options">Default transport options</h2> +<div class="sectionbody"> +<div class="paragraph"><p>By default the socket will be set to return <code>binary</code> data, with the +options <code>{active, false}</code>, <code>{packet, raw}</code>, <code>{reuseaddr, true}</code> set. +These values can’t be overriden when starting the listener, but +they can be overriden using <code>Transport:setopts/2</code> in the protocol.</p></div> +<div class="paragraph"><p>It will also set <code>{backlog, 1024}</code> and <code>{nodelay, true}</code>, which +can be overriden at listener startup.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_listening_on_a_random_port">Listening on a random port</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You do not have to specify a specific port to listen on. If you give +the port number 0, or if you omit the port number entirely, Ranch will +start listening on a random port.</p></div> +<div class="paragraph"><p>You can retrieve this port number by calling <code>ranch:get_port/1</code>. The +argument is the name of the listener you gave in <code>ranch:start_listener/6</code>.</p></div> +<div class="listingblock"> +<div class="title">Starting a listener for TCP connections on a random port</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: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #993399">100</span>, + <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">0</span>}], + <span style="color: #FF6600">echo_protocol</span>, [] +)<span style="color: #990000">.</span> +<span style="color: #009900">Port</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_port</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_listening_on_privileged_ports">Listening on privileged ports</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Some systems limit access to ports below 1024 for security reasons. +This can easily be identified by an <code>{error, eacces}</code> error when trying +to open a listening socket on such a port.</p></div> +<div class="paragraph"><p>The methods for listening on privileged ports vary between systems, +please refer to your system’s documentation for more information.</p></div> +<div class="paragraph"><p>We recommend the use of port rewriting for systems with a single server, +and load balancing for systems with multiple servers. Documenting these +solutions is however out of the scope of this guide.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_accepting_connections_on_an_existing_socket">Accepting connections on an existing socket</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you want to accept connections on an existing socket, you can use the +<code>socket</code> transport option, which should just be the relevant data returned +from the connect function for the transport or the underlying socket library +(<code>gen_tcp:connect</code>, <code>ssl:connect</code>). The accept function will then be +called on the passed in socket. You should connect the socket in +<code>{active, false}</code> mode, as well.</p></div> +<div class="paragraph"><p>Note, however, that because of a bug in SSL, you cannot change ownership of an +SSL listen socket prior to R16. Ranch will catch the error thrown, but the +owner of the SSL socket will remain as whatever process created the socket. +However, this will not affect accept behaviour unless the owner process dies, +in which case the socket is closed. Therefore, to use this feature with SSL +with an erlang release prior to R16, ensure that the SSL socket is opened in a +persistant process.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_limiting_the_number_of_concurrent_connections">Limiting the number of concurrent connections</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>max_connections</code> transport option allows you to limit the number +of concurrent connections. It defaults to 1024. Its purpose is to +prevent your system from being overloaded and ensuring all the +connections are handled optimally.</p></div> +<div class="listingblock"> +<div class="title">Customizing the maximum number of concurrent connections</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: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #993399">100</span>, + <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">max_connections</span>, <span style="color: #993399">100</span>}], + <span style="color: #FF6600">echo_protocol</span>, [] +)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You can disable this limit by setting its value to the atom <code>infinity</code>.</p></div> +<div class="listingblock"> +<div class="title">Disabling the limit for the number of connections</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: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #993399">100</span>, + <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">max_connections</span>, <span style="color: #FF6600">infinity</span>}], + <span style="color: #FF6600">echo_protocol</span>, [] +)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You may not always want connections to be counted when checking for +<code>max_connections</code>. For example you might have a protocol where both +short-lived and long-lived connections are possible. If the long-lived +connections are mostly waiting for messages, then they don’t consume +much resources and can safely be removed from the count.</p></div> +<div class="paragraph"><p>To remove the connection from the count, you must call the +<code>ranch:remove_connection/1</code> from within the connection process, +with the name of the listener as the only argument.</p></div> +<div class="listingblock"> +<div class="title">Removing a connection from the count of connections</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="font-weight: bold"><span style="color: #000000">ranch:remove_connection</span></span>(<span style="color: #009900">Ref</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>As seen in the chapter covering protocols, this pid is received as the +first argument of the protocol’s <code>start_link/4</code> callback.</p></div> +<div class="paragraph"><p>You can modify the <code>max_connections</code> value on a running listener by +using the <code>ranch:set_max_connections/2</code> function, with the name of the +listener as first argument and the new value as the second.</p></div> +<div class="listingblock"> +<div class="title">Upgrading the maximum number of connections</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="font-weight: bold"><span style="color: #000000">ranch:set_max_connections</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #009900">MaxConns</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The change will occur immediately.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_using_a_supervisor_for_connection_processes">Using a supervisor for connection processes</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch allows you to define the type of process that will be used +for the connection processes. By default it expects a <code>worker</code>. +When the <code>connection_type</code> configuration value is set to <code>supervisor</code>, +Ranch will consider that the connection process it manages is a +supervisor and will reflect that in its supervision tree.</p></div> +<div class="paragraph"><p>Connection processes of type <code>supervisor</code> can either handle the +socket directly or through one of their children. In the latter +case the start function for the connection process must return +two pids: the pid of the supervisor you created (that will be +supervised) and the pid of the protocol handling process (that +will receive the socket).</p></div> +<div class="paragraph"><p>Instead of returning <code>{ok, ConnPid}</code>, simply return +<code>{ok, SupPid, ConnPid}</code>.</p></div> +<div class="paragraph"><p>It is very important that the connection process be created +under the supervisor process so that everything works as intended. +If not, you will most likely experience issues when the supervised +process is stopped.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_upgrading">Upgrading</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch allows you to upgrade the protocol options. This takes effect +immediately and for all subsequent connections.</p></div> +<div class="paragraph"><p>To upgrade the protocol options, call <code>ranch:set_protocol_options/2</code> +with the name of the listener as first argument and the new options +as the second.</p></div> +<div class="listingblock"> +<div class="title">Upgrading the protocol options</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="font-weight: bold"><span style="color: #000000">ranch:set_protocol_options</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #009900">NewOpts</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>All future connections will use the new options.</p></div> +<div class="paragraph"><p>You can also retrieve the current options similarly by +calling <code>ranch:get_protocol_options/1</code>.</p></div> +<div class="listingblock"> +<div class="title">Retrieving the current protocol options</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">Opts</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_protocol_options</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.2/guide/parsers/index.html b/docs/en/ranch/1.2/guide/parsers/index.html index a0b4e5d1..a5d18388 100644 --- a/docs/en/ranch/1.2/guide/parsers/index.html +++ b/docs/en/ranch/1.2/guide/parsers/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Writing parsers</title> @@ -67,115 +67,118 @@ <h1 class="lined-header"><span>Writing parsers</span></h1> -<div class="paragraph"><p>There are three kinds of protocols:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Text protocols
-</p>
-</li>
-<li>
-<p>
-Schema-less binary protocols
-</p>
-</li>
-<li>
-<p>
-Schema-based binary protocols
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>This chapter introduces the first two kinds. It will not cover
-more advanced topics such as continuations or parser generators.</p></div>
-<div class="paragraph"><p>This chapter isn’t specifically about Ranch, we assume here that
-you know how to read data from the socket. The data you read and
-the data that hasn’t been parsed is saved in a buffer. Every
-time you read from the socket, the data read is appended to the
-buffer. What happens next depends on the kind of protocol. We
-will only cover the first two.</p></div>
-<div class="sect1">
-<h2 id="_parsing_text">Parsing text</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Text protocols are generally line based. This means that we can’t
-do anything with them until we receive the full line.</p></div>
-<div class="paragraph"><p>A simple way to get a full line is to use <code>binary:split/{2,3}</code>.</p></div>
-<div class="listingblock">
-<div class="title">Using binary:split/2 to get a line of input</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="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">binary:split</span></span>(<span style="color: #009900">Buffer</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"\n"</span><span style="color: #990000">>></span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- [<span style="color: #990000">_</span>] <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">get_more_data</span></span>(<span style="color: #009900">Buffer</span>);
- [<span style="color: #009900">Line</span>, <span style="color: #009900">Rest</span>] <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">handle_line</span></span>(<span style="color: #009900">Line</span>, <span style="color: #009900">Rest</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>In the above example, we can have two results. Either there was
-a line break in the buffer and we get it split into two parts,
-the line and the rest of the buffer; or there was no line break
-in the buffer and we need to get more data from the socket.</p></div>
-<div class="paragraph"><p>Next, we need to parse the line. The simplest way is to again
-split, here on space. The difference is that we want to split
-on all spaces character, as we want to tokenize the whole string.</p></div>
-<div class="listingblock">
-<div class="title">Using binary:split/3 to split text</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="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">binary:split</span></span>(<span style="color: #009900">Line</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">" "</span><span style="color: #990000">>></span>, [<span style="color: #FF6600">global</span>]) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- [<span style="color: #990000"><<</span><span style="color: #FF0000">"HELLO"</span><span style="color: #990000">>></span>] <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">be_polite</span></span>();
- [<span style="color: #990000"><<</span><span style="color: #FF0000">"AUTH"</span><span style="color: #990000">>></span>, <span style="color: #009900">User</span>, <span style="color: #009900">Password</span>] <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">authenticate_user</span></span>(<span style="color: #009900">User</span>, <span style="color: #009900">Password</span>);
- [<span style="color: #990000"><<</span><span style="color: #FF0000">"QUIT"</span><span style="color: #990000">>></span>, <span style="color: #009900">Reason</span>] <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">quit</span></span>(<span style="color: #009900">Reason</span>)
- <span style="font-style: italic"><span style="color: #9A1900">%% ...</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>Pretty simple, right? Match on the command name, get the rest
-of the tokens in variables and call the respective functions.</p></div>
-<div class="paragraph"><p>After doing this, you will want to check if there is another
-line in the buffer, and handle it immediately if any.
-Otherwise wait for more data.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_parsing_binary">Parsing binary</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Binary protocols can be more varied, although most of them are
-pretty similar. The first four bytes of a frame tend to be
-the size of the frame, which is followed by a certain number
-of bytes for the type of frame and then various parameters.</p></div>
-<div class="paragraph"><p>Sometimes the size of the frame includes the first four bytes,
-sometimes not. Other times this size is encoded over two bytes.
-And even other times little-endian is used instead of big-endian.</p></div>
-<div class="paragraph"><p>The general idea stays the same though.</p></div>
-<div class="listingblock">
-<div class="title">Using binary pattern matching to split frames</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: #990000"><<</span> <span style="color: #009900">Size</span><span style="color: #990000">:</span><span style="color: #993399">32</span>, <span style="color: #990000">_/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span> <span style="color: #990000">=</span> <span style="color: #009900">Buffer</span>,
-<span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="color: #009900">Buffer</span> <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- <span style="color: #990000"><<</span> <span style="color: #009900">Frame</span><span style="color: #990000">:</span><span style="color: #009900">Size</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span> <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">handle_frame</span></span>(<span style="color: #009900">Frame</span>, <span style="color: #009900">Rest</span>);
- <span style="color: #990000">_</span> <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">get_more_data</span></span>(<span style="color: #009900">Buffer</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 will then need to parse this frame using binary pattern
-matching, and handle it. Then you will want to check if there
-is another frame fully received in the buffer, and handle it
-immediately if any. Otherwise wait for more data.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>There are three kinds of protocols:</p></div> +<div class="ulist"><ul> +<li> +<p> +Text protocols +</p> +</li> +<li> +<p> +Schema-less binary protocols +</p> +</li> +<li> +<p> +Schema-based binary protocols +</p> +</li> +</ul></div> +<div class="paragraph"><p>This chapter introduces the first two kinds. It will not cover +more advanced topics such as continuations or parser generators.</p></div> +<div class="paragraph"><p>This chapter isn’t specifically about Ranch, we assume here that +you know how to read data from the socket. The data you read and +the data that hasn’t been parsed is saved in a buffer. Every +time you read from the socket, the data read is appended to the +buffer. What happens next depends on the kind of protocol. We +will only cover the first two.</p></div> +<div class="sect1"> +<h2 id="_parsing_text">Parsing text</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Text protocols are generally line based. This means that we can’t +do anything with them until we receive the full line.</p></div> +<div class="paragraph"><p>A simple way to get a full line is to use <code>binary:split/{2,3}</code>.</p></div> +<div class="listingblock"> +<div class="title">Using binary:split/2 to get a line of input</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="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">binary:split</span></span>(<span style="color: #009900">Buffer</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"\n"</span><span style="color: #990000">>></span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + [<span style="color: #990000">_</span>] <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">get_more_data</span></span>(<span style="color: #009900">Buffer</span>); + [<span style="color: #009900">Line</span>, <span style="color: #009900">Rest</span>] <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">handle_line</span></span>(<span style="color: #009900">Line</span>, <span style="color: #009900">Rest</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>In the above example, we can have two results. Either there was +a line break in the buffer and we get it split into two parts, +the line and the rest of the buffer; or there was no line break +in the buffer and we need to get more data from the socket.</p></div> +<div class="paragraph"><p>Next, we need to parse the line. The simplest way is to again +split, here on space. The difference is that we want to split +on all spaces character, as we want to tokenize the whole string.</p></div> +<div class="listingblock"> +<div class="title">Using binary:split/3 to split text</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="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">binary:split</span></span>(<span style="color: #009900">Line</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">" "</span><span style="color: #990000">>></span>, [<span style="color: #FF6600">global</span>]) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + [<span style="color: #990000"><<</span><span style="color: #FF0000">"HELLO"</span><span style="color: #990000">>></span>] <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">be_polite</span></span>(); + [<span style="color: #990000"><<</span><span style="color: #FF0000">"AUTH"</span><span style="color: #990000">>></span>, <span style="color: #009900">User</span>, <span style="color: #009900">Password</span>] <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">authenticate_user</span></span>(<span style="color: #009900">User</span>, <span style="color: #009900">Password</span>); + [<span style="color: #990000"><<</span><span style="color: #FF0000">"QUIT"</span><span style="color: #990000">>></span>, <span style="color: #009900">Reason</span>] <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">quit</span></span>(<span style="color: #009900">Reason</span>) + <span style="font-style: italic"><span style="color: #9A1900">%% ...</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>Pretty simple, right? Match on the command name, get the rest +of the tokens in variables and call the respective functions.</p></div> +<div class="paragraph"><p>After doing this, you will want to check if there is another +line in the buffer, and handle it immediately if any. +Otherwise wait for more data.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_parsing_binary">Parsing binary</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Binary protocols can be more varied, although most of them are +pretty similar. The first four bytes of a frame tend to be +the size of the frame, which is followed by a certain number +of bytes for the type of frame and then various parameters.</p></div> +<div class="paragraph"><p>Sometimes the size of the frame includes the first four bytes, +sometimes not. Other times this size is encoded over two bytes. +And even other times little-endian is used instead of big-endian.</p></div> +<div class="paragraph"><p>The general idea stays the same though.</p></div> +<div class="listingblock"> +<div class="title">Using binary pattern matching to split frames</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: #990000"><<</span> <span style="color: #009900">Size</span><span style="color: #990000">:</span><span style="color: #993399">32</span>, <span style="color: #990000">_/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span> <span style="color: #990000">=</span> <span style="color: #009900">Buffer</span>, +<span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="color: #009900">Buffer</span> <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + <span style="color: #990000"><<</span> <span style="color: #009900">Frame</span><span style="color: #990000">:</span><span style="color: #009900">Size</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span> <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">handle_frame</span></span>(<span style="color: #009900">Frame</span>, <span style="color: #009900">Rest</span>); + <span style="color: #990000">_</span> <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">get_more_data</span></span>(<span style="color: #009900">Buffer</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 will then need to parse this frame using binary pattern +matching, and handle it. Then you will want to check if there +is another frame fully received in the buffer, and handle it +immediately if any. Otherwise wait for more data.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.2/guide/protocols/index.html b/docs/en/ranch/1.2/guide/protocols/index.html index b7918b8c..dffca064 100644 --- a/docs/en/ranch/1.2/guide/protocols/index.html +++ b/docs/en/ranch/1.2/guide/protocols/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Protocols</title> @@ -67,135 +67,138 @@ <h1 class="lined-header"><span>Protocols</span></h1> -<div class="paragraph"><p>A protocol handler starts a connection process and defines the
-protocol logic executed in this process.</p></div>
-<div class="sect1">
-<h2 id="_writing_a_protocol_handler">Writing a protocol handler</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>All protocol handlers must implement the <code>ranch_protocol</code> behavior
-which defines a single callback, <code>start_link/4</code>. This callback is
-responsible for spawning a new process for handling the connection.
-It receives four arguments: the name of the listener, the socket, the
-transport handler being used and the protocol options defined in
-the call to <code>ranch:start_listener/6</code>. This callback must
-return <code>{ok, Pid}</code>, with <code>Pid</code> the pid of the new process.</p></div>
-<div class="paragraph"><p>The newly started process can then freely initialize itself. However,
-it must call <code>ranch:accept_ack/1</code> before doing any socket operation.
-This will ensure the connection process is the owner of the socket.
-It expects the listener’s name as argument.</p></div>
-<div class="listingblock">
-<div class="title">Acknowledge accepting the socket</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: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>If your protocol code requires specific socket options, you should
-set them while initializing your connection process, after
-calling <code>ranch:accept_ack/1</code>. You can use <code>Transport:setopts/2</code>
-for that purpose.</p></div>
-<div class="paragraph"><p>Following is the complete protocol code for the example found
-in <code>examples/tcp_echo/</code>.</p></div>
-<div class="listingblock">
-<div class="title">Protocol module that echoes everything it receives</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="font-weight: bold"><span style="color: #000080">-module</span></span>(<span style="color: #FF6600">echo_protocol</span>)<span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">ranch_protocol</span>)<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">start_link</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">init</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">start_link</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span>
- <span style="color: #009900">Pid</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000080">spawn_link</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, <span style="color: #FF6600">init</span>, [<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>]),
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Pid</span>}<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">_Opts</span> <span style="color: #990000">=</span> []) <span style="color: #990000">-></span>
- <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>),
- <span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>)<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">recv</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #993399">0</span>, <span style="color: #993399">5000</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: #990000">-></span>
- <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Data</span>),
- <span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>);
- <span style="color: #990000">_</span> <span style="color: #990000">-></span>
- <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">close</span></span>(<span style="color: #009900">Socket</span>)
- <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_using_gen_server">Using gen_server</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Special processes like the ones that use the <code>gen_server</code> or <code>gen_fsm</code>
-behaviours have the particularity of having their <code>start_link</code> call not
-return until the <code>init</code> function returns. This is problematic, because
-you won’t be able to call <code>ranch:accept_ack/1</code> from the <code>init</code> callback
-as this would cause a deadlock to happen.</p></div>
-<div class="paragraph"><p>There are two ways of solving this problem.</p></div>
-<div class="paragraph"><p>The first, and probably the most elegant one, is to make use of the
-<code>gen_server:enter_loop/3</code> function. It allows you to start your process
-normally (although it must be started with <code>proc_lib</code> like all special
-processes), then perform any needed operations before falling back into
-the normal <code>gen_server</code> execution loop.</p></div>
-<div class="listingblock">
-<div class="title">Use a gen_server for protocol handling</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="font-weight: bold"><span style="color: #000080">-module</span></span>(<span style="color: #FF6600">my_protocol</span>)<span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">gen_server</span>)<span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">ranch_protocol</span>)<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">start_link</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">init</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span>
-<span style="font-style: italic"><span style="color: #9A1900">%% Exports of other gen_server callbacks here.</span></span>
-
-<span style="font-weight: bold"><span style="color: #000000">start_link</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">proc_lib:start_link</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, <span style="color: #FF6600">init</span>, [<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>])<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">_Opts</span> <span style="color: #990000">=</span> []) <span style="color: #990000">-></span>
- <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">proc_lib:init_ack</span></span>({<span style="color: #FF6600">ok</span>, <span style="font-weight: bold"><span style="color: #000080">self</span></span>()}),
- <span style="font-style: italic"><span style="color: #9A1900">%% Perform any required state initialization here.</span></span>
- <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>),
- <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">setopts</span></span>(<span style="color: #009900">Socket</span>, [{<span style="color: #FF6600">active</span>, <span style="color: #FF6600">once</span>}]),
- <span style="font-weight: bold"><span style="color: #000000">gen_server:enter_loop</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, [], {<span style="color: #FF6600">state</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>})<span style="color: #990000">.</span>
-
-<span style="font-style: italic"><span style="color: #9A1900">%% Other gen_server callbacks here.</span></span></tt></pre></div></div>
-<div class="paragraph"><p>The second method involves triggering a timeout just after <code>gen_server:init</code>
-ends. If you return a timeout value of <code>0</code> then the <code>gen_server</code> will call
-<code>handle_info(timeout, _, _)</code> right away.</p></div>
-<div class="listingblock">
-<div class="title">Use a gen_server for protocol handling, method 2</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="font-weight: bold"><span style="color: #000080">-module</span></span>(<span style="color: #FF6600">my_protocol</span>)<span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">gen_server</span>)<span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">ranch_protocol</span>)<span style="color: #990000">.</span>
-
-<span style="font-style: italic"><span style="color: #9A1900">%% Exports go here.</span></span>
-
-<span style="font-weight: bold"><span style="color: #000000">init</span></span>([<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>]) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, {<span style="color: #FF6600">state</span>, <span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>}, <span style="color: #993399">0</span>}<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">handle_info</span></span>(<span style="color: #FF6600">timeout</span>, <span style="color: #009900">State</span><span style="color: #990000">=</span>{<span style="color: #FF6600">state</span>, <span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>}) <span style="color: #990000">-></span>
- <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>),
- <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">setopts</span></span>(<span style="color: #009900">Socket</span>, [{<span style="color: #FF6600">active</span>, <span style="color: #FF6600">once</span>}]),
- {<span style="color: #FF6600">noreply</span>, <span style="color: #009900">State</span>};
-<span style="font-style: italic"><span style="color: #9A1900">%% ...</span></span></tt></pre></div></div>
-</div>
-</div>
+<div class="paragraph"><p>A protocol handler starts a connection process and defines the +protocol logic executed in this process.</p></div> +<div class="sect1"> +<h2 id="_writing_a_protocol_handler">Writing a protocol handler</h2> +<div class="sectionbody"> +<div class="paragraph"><p>All protocol handlers must implement the <code>ranch_protocol</code> behavior +which defines a single callback, <code>start_link/4</code>. This callback is +responsible for spawning a new process for handling the connection. +It receives four arguments: the name of the listener, the socket, the +transport handler being used and the protocol options defined in +the call to <code>ranch:start_listener/6</code>. This callback must +return <code>{ok, Pid}</code>, with <code>Pid</code> the pid of the new process.</p></div> +<div class="paragraph"><p>The newly started process can then freely initialize itself. However, +it must call <code>ranch:accept_ack/1</code> before doing any socket operation. +This will ensure the connection process is the owner of the socket. +It expects the listener’s name as argument.</p></div> +<div class="listingblock"> +<div class="title">Acknowledge accepting the socket</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: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>If your protocol code requires specific socket options, you should +set them while initializing your connection process, after +calling <code>ranch:accept_ack/1</code>. You can use <code>Transport:setopts/2</code> +for that purpose.</p></div> +<div class="paragraph"><p>Following is the complete protocol code for the example found +in <code>examples/tcp_echo/</code>.</p></div> +<div class="listingblock"> +<div class="title">Protocol module that echoes everything it receives</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="font-weight: bold"><span style="color: #000080">-module</span></span>(<span style="color: #FF6600">echo_protocol</span>)<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">ranch_protocol</span>)<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">start_link</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">init</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">start_link</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span> + <span style="color: #009900">Pid</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000080">spawn_link</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, <span style="color: #FF6600">init</span>, [<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>]), + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Pid</span>}<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">_Opts</span> <span style="color: #990000">=</span> []) <span style="color: #990000">-></span> + <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>), + <span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>)<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">recv</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #993399">0</span>, <span style="color: #993399">5000</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: #990000">-></span> + <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Data</span>), + <span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>); + <span style="color: #990000">_</span> <span style="color: #990000">-></span> + <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">close</span></span>(<span style="color: #009900">Socket</span>) + <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_using_gen_server">Using gen_server</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Special processes like the ones that use the <code>gen_server</code> or <code>gen_fsm</code> +behaviours have the particularity of having their <code>start_link</code> call not +return until the <code>init</code> function returns. This is problematic, because +you won’t be able to call <code>ranch:accept_ack/1</code> from the <code>init</code> callback +as this would cause a deadlock to happen.</p></div> +<div class="paragraph"><p>There are two ways of solving this problem.</p></div> +<div class="paragraph"><p>The first, and probably the most elegant one, is to make use of the +<code>gen_server:enter_loop/3</code> function. It allows you to start your process +normally (although it must be started with <code>proc_lib</code> like all special +processes), then perform any needed operations before falling back into +the normal <code>gen_server</code> execution loop.</p></div> +<div class="listingblock"> +<div class="title">Use a gen_server for protocol handling</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="font-weight: bold"><span style="color: #000080">-module</span></span>(<span style="color: #FF6600">my_protocol</span>)<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">gen_server</span>)<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">ranch_protocol</span>)<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">start_link</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">init</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span> +<span style="font-style: italic"><span style="color: #9A1900">%% Exports of other gen_server callbacks here.</span></span> + +<span style="font-weight: bold"><span style="color: #000000">start_link</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">proc_lib:start_link</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, <span style="color: #FF6600">init</span>, [<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>])<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">_Opts</span> <span style="color: #990000">=</span> []) <span style="color: #990000">-></span> + <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">proc_lib:init_ack</span></span>({<span style="color: #FF6600">ok</span>, <span style="font-weight: bold"><span style="color: #000080">self</span></span>()}), + <span style="font-style: italic"><span style="color: #9A1900">%% Perform any required state initialization here.</span></span> + <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>), + <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">setopts</span></span>(<span style="color: #009900">Socket</span>, [{<span style="color: #FF6600">active</span>, <span style="color: #FF6600">once</span>}]), + <span style="font-weight: bold"><span style="color: #000000">gen_server:enter_loop</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, [], {<span style="color: #FF6600">state</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>})<span style="color: #990000">.</span> + +<span style="font-style: italic"><span style="color: #9A1900">%% Other gen_server callbacks here.</span></span></tt></pre></div></div> +<div class="paragraph"><p>The second method involves triggering a timeout just after <code>gen_server:init</code> +ends. If you return a timeout value of <code>0</code> then the <code>gen_server</code> will call +<code>handle_info(timeout, _, _)</code> right away.</p></div> +<div class="listingblock"> +<div class="title">Use a gen_server for protocol handling, method 2</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="font-weight: bold"><span style="color: #000080">-module</span></span>(<span style="color: #FF6600">my_protocol</span>)<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">gen_server</span>)<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">ranch_protocol</span>)<span style="color: #990000">.</span> + +<span style="font-style: italic"><span style="color: #9A1900">%% Exports go here.</span></span> + +<span style="font-weight: bold"><span style="color: #000000">init</span></span>([<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>]) <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, {<span style="color: #FF6600">state</span>, <span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>}, <span style="color: #993399">0</span>}<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">handle_info</span></span>(<span style="color: #FF6600">timeout</span>, <span style="color: #009900">State</span><span style="color: #990000">=</span>{<span style="color: #FF6600">state</span>, <span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>}) <span style="color: #990000">-></span> + <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>), + <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">setopts</span></span>(<span style="color: #009900">Socket</span>, [{<span style="color: #FF6600">active</span>, <span style="color: #FF6600">once</span>}]), + {<span style="color: #FF6600">noreply</span>, <span style="color: #009900">State</span>}; +<span style="font-style: italic"><span style="color: #9A1900">%% ...</span></span></tt></pre></div></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.2/guide/ssl_auth/index.html b/docs/en/ranch/1.2/guide/ssl_auth/index.html index 18e94d36..3261ddc4 100644 --- a/docs/en/ranch/1.2/guide/ssl_auth/index.html +++ b/docs/en/ranch/1.2/guide/ssl_auth/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: SSL client authentication</title> @@ -67,164 +67,167 @@ <h1 class="lined-header"><span>SSL client authentication</span></h1> -<div class="sect1">
-<h2 id="_purpose">Purpose</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>SSL client authentication is a mechanism allowing applications to
-identify certificates. This allows your application to make sure that
-the client is an authorized certificate, but makes no claim about
-whether the user can be trusted. This can be combined with a password
-based authentication to attain greater security.</p></div>
-<div class="paragraph"><p>The server only needs to retain the certificate serial number and
-the certificate issuer to authenticate the certificate. Together,
-they can be used to uniquely identify a certicate.</p></div>
-<div class="paragraph"><p>As Ranch allows the same protocol code to be used for both SSL and
-non-SSL transports, you need to make sure you are in an SSL context
-before attempting to perform an SSL client authentication. This
-can be done by checking the return value of <code>Transport:name/0</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_obtaining_client_certificates">Obtaining client certificates</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can obtain client certificates from various sources. You can
-generate them yourself, or you can use a service like CAcert.org
-which allows you to generate client and server certificates for
-free.</p></div>
-<div class="paragraph"><p>Following are the steps you need to take to create a CAcert.org
-account, generate a certificate and install it in your favorite
-browser.</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Open [CAcert.org](<a href="http://cacert.org">http://cacert.org</a>) in your favorite browser
-</p>
-</li>
-<li>
-<p>
-Root Certificate link: install both certificates
-</p>
-</li>
-<li>
-<p>
-Join (Register an account)
-</p>
-</li>
-<li>
-<p>
-Verify your account (check your email inbox!)
-</p>
-</li>
-<li>
-<p>
-Log in
-</p>
-</li>
-<li>
-<p>
-Client Certificates: New
-</p>
-</li>
-<li>
-<p>
-Follow instructions to create the certificate
-</p>
-</li>
-<li>
-<p>
-Install the certificate in your browser
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>You can optionally save the certificate for later use, for example
-to extract the <code>IssuerID</code> information as will be detailed later on.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_transport_configuration">Transport configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The SSL transport does not request a client certificate by default.
-You need to specify the <code>{verify, verify_peer}</code> option when starting
-the listener to enable this behavior.</p></div>
-<div class="listingblock">
-<div class="title">Configure a listener for SSL authentication</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: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">my_ssl</span>, <span style="color: #993399">100</span>,
- <span style="color: #FF6600">ranch_ssl</span>, [
- {<span style="color: #FF6600">port</span>, <span style="color: #009900">SSLPort</span>},
- {<span style="color: #FF6600">certfile</span>, <span style="color: #009900">PathToCertfile</span>},
- {<span style="color: #FF6600">cacertfile</span>, <span style="color: #009900">PathToCACertfile</span>},
- {<span style="color: #FF6600">verify</span>, <span style="color: #FF6600">verify_peer</span>}
- ],
- <span style="color: #FF6600">my_protocol</span>, []
-)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>In this example we set the required <code>port</code> and <code>certfile</code>, but also
-the <code>cacertfile</code> containing the CACert.org root certificate, and
-the option to request the client certificate.</p></div>
-<div class="paragraph"><p>If you enable the <code>{verify, verify_peer}</code> option and the client does
-not have a client certificate configured for your domain, then no
-certificate will be sent. This allows you to use SSL for more than
-just authenticated clients.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_authentication">Authentication</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To authenticate users, you must first save the certificate information
-required. If you have your users' certificate files, you can simply
-load the certificate and retrieve the information directly.</p></div>
-<div class="listingblock">
-<div class="title">Retrieve the issuer ID from a certificate</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="font-weight: bold"><span style="color: #000000">certfile_to_issuer_id</span></span>(<span style="color: #009900">Filename</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:read_file</span></span>(<span style="color: #009900">Filename</span>),
- [{<span style="color: #FF6600">'Certificate'</span>, <span style="color: #009900">Cert</span>, <span style="color: #FF6600">not_encrypted</span>}] <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pem_decode</span></span>(<span style="color: #009900">Data</span>),
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">IssuerID</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pkix_issuer_id</span></span>(<span style="color: #009900">Cert</span>, <span style="font-weight: bold"><span style="color: #000080">self</span></span>),
- <span style="color: #009900">IssuerID</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The <code>IssuerID</code> variable contains both the certificate serial number
-and the certificate issuer stored in a tuple, so this value alone can
-be used to uniquely identify the user certificate. You can save this
-value in a database, a configuration file or any other place where an
-Erlang term can be stored and retrieved.</p></div>
-<div class="paragraph"><p>To retrieve the <code>IssuerID</code> from a running connection, you need to first
-retrieve the client certificate and then extract this information from
-it. Ranch does not provide a function to retrieve the client certificate.
-Instead you can use the <code>ssl:peercert/1</code> function. Once you have the
-certificate, you can again use the <code>public_key:pkix_issuer_id/2</code> to
-extract the <code>IssuerID</code> value.</p></div>
-<div class="paragraph"><p>The following function returns the <code>IssuerID</code> or <code>false</code> if no client
-certificate was found. This snippet is intended to be used from your
-protocol code.</p></div>
-<div class="listingblock">
-<div class="title">Retrieve the issuer ID from the certificate for the current connection</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="font-weight: bold"><span style="color: #000000">socket_to_issuer_id</span></span>(<span style="color: #009900">Socket</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">ssl:peercert</span></span>(<span style="color: #009900">Socket</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">no_peercert</span>} <span style="color: #990000">-></span>
- <span style="color: #000080">false</span>;
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Cert</span>} <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">IssuerID</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pkix_issuer_id</span></span>(<span style="color: #009900">Cert</span>, <span style="font-weight: bold"><span style="color: #000080">self</span></span>),
- <span style="color: #009900">IssuerID</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 then only need to match the <code>IssuerID</code> value to authenticate the
-user.</p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_purpose">Purpose</h2> +<div class="sectionbody"> +<div class="paragraph"><p>SSL client authentication is a mechanism allowing applications to +identify certificates. This allows your application to make sure that +the client is an authorized certificate, but makes no claim about +whether the user can be trusted. This can be combined with a password +based authentication to attain greater security.</p></div> +<div class="paragraph"><p>The server only needs to retain the certificate serial number and +the certificate issuer to authenticate the certificate. Together, +they can be used to uniquely identify a certicate.</p></div> +<div class="paragraph"><p>As Ranch allows the same protocol code to be used for both SSL and +non-SSL transports, you need to make sure you are in an SSL context +before attempting to perform an SSL client authentication. This +can be done by checking the return value of <code>Transport:name/0</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_obtaining_client_certificates">Obtaining client certificates</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You can obtain client certificates from various sources. You can +generate them yourself, or you can use a service like CAcert.org +which allows you to generate client and server certificates for +free.</p></div> +<div class="paragraph"><p>Following are the steps you need to take to create a CAcert.org +account, generate a certificate and install it in your favorite +browser.</p></div> +<div class="ulist"><ul> +<li> +<p> +Open [CAcert.org](<a href="http://cacert.org">http://cacert.org</a>) in your favorite browser +</p> +</li> +<li> +<p> +Root Certificate link: install both certificates +</p> +</li> +<li> +<p> +Join (Register an account) +</p> +</li> +<li> +<p> +Verify your account (check your email inbox!) +</p> +</li> +<li> +<p> +Log in +</p> +</li> +<li> +<p> +Client Certificates: New +</p> +</li> +<li> +<p> +Follow instructions to create the certificate +</p> +</li> +<li> +<p> +Install the certificate in your browser +</p> +</li> +</ul></div> +<div class="paragraph"><p>You can optionally save the certificate for later use, for example +to extract the <code>IssuerID</code> information as will be detailed later on.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_transport_configuration">Transport configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The SSL transport does not request a client certificate by default. +You need to specify the <code>{verify, verify_peer}</code> option when starting +the listener to enable this behavior.</p></div> +<div class="listingblock"> +<div class="title">Configure a listener for SSL authentication</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: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">my_ssl</span>, <span style="color: #993399">100</span>, + <span style="color: #FF6600">ranch_ssl</span>, [ + {<span style="color: #FF6600">port</span>, <span style="color: #009900">SSLPort</span>}, + {<span style="color: #FF6600">certfile</span>, <span style="color: #009900">PathToCertfile</span>}, + {<span style="color: #FF6600">cacertfile</span>, <span style="color: #009900">PathToCACertfile</span>}, + {<span style="color: #FF6600">verify</span>, <span style="color: #FF6600">verify_peer</span>} + ], + <span style="color: #FF6600">my_protocol</span>, [] +)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>In this example we set the required <code>port</code> and <code>certfile</code>, but also +the <code>cacertfile</code> containing the CACert.org root certificate, and +the option to request the client certificate.</p></div> +<div class="paragraph"><p>If you enable the <code>{verify, verify_peer}</code> option and the client does +not have a client certificate configured for your domain, then no +certificate will be sent. This allows you to use SSL for more than +just authenticated clients.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_authentication">Authentication</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To authenticate users, you must first save the certificate information +required. If you have your users' certificate files, you can simply +load the certificate and retrieve the information directly.</p></div> +<div class="listingblock"> +<div class="title">Retrieve the issuer ID from a certificate</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="font-weight: bold"><span style="color: #000000">certfile_to_issuer_id</span></span>(<span style="color: #009900">Filename</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:read_file</span></span>(<span style="color: #009900">Filename</span>), + [{<span style="color: #FF6600">'Certificate'</span>, <span style="color: #009900">Cert</span>, <span style="color: #FF6600">not_encrypted</span>}] <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pem_decode</span></span>(<span style="color: #009900">Data</span>), + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">IssuerID</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pkix_issuer_id</span></span>(<span style="color: #009900">Cert</span>, <span style="font-weight: bold"><span style="color: #000080">self</span></span>), + <span style="color: #009900">IssuerID</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The <code>IssuerID</code> variable contains both the certificate serial number +and the certificate issuer stored in a tuple, so this value alone can +be used to uniquely identify the user certificate. You can save this +value in a database, a configuration file or any other place where an +Erlang term can be stored and retrieved.</p></div> +<div class="paragraph"><p>To retrieve the <code>IssuerID</code> from a running connection, you need to first +retrieve the client certificate and then extract this information from +it. Ranch does not provide a function to retrieve the client certificate. +Instead you can use the <code>ssl:peercert/1</code> function. Once you have the +certificate, you can again use the <code>public_key:pkix_issuer_id/2</code> to +extract the <code>IssuerID</code> value.</p></div> +<div class="paragraph"><p>The following function returns the <code>IssuerID</code> or <code>false</code> if no client +certificate was found. This snippet is intended to be used from your +protocol code.</p></div> +<div class="listingblock"> +<div class="title">Retrieve the issuer ID from the certificate for the current connection</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="font-weight: bold"><span style="color: #000000">socket_to_issuer_id</span></span>(<span style="color: #009900">Socket</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">ssl:peercert</span></span>(<span style="color: #009900">Socket</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">no_peercert</span>} <span style="color: #990000">-></span> + <span style="color: #000080">false</span>; + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Cert</span>} <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">IssuerID</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pkix_issuer_id</span></span>(<span style="color: #009900">Cert</span>, <span style="font-weight: bold"><span style="color: #000080">self</span></span>), + <span style="color: #009900">IssuerID</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 then only need to match the <code>IssuerID</code> value to authenticate the +user.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.2/guide/transports/index.html b/docs/en/ranch/1.2/guide/transports/index.html index e45b0d90..b60d99e6 100644 --- a/docs/en/ranch/1.2/guide/transports/index.html +++ b/docs/en/ranch/1.2/guide/transports/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Transports</title> @@ -67,195 +67,198 @@ <h1 class="lined-header"><span>Transports</span></h1> -<div class="paragraph"><p>A transport defines the interface to interact with a socket.</p></div>
-<div class="paragraph"><p>Transports can be used for connecting, listening and accepting
-connections, but also for receiving and sending data. Both
-passive and active mode are supported, although all sockets
-are initialized as passive.</p></div>
-<div class="sect1">
-<h2 id="_tcp_transport">TCP transport</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The TCP transport is a thin wrapper around <code>gen_tcp</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_ssl_transport">SSL transport</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The SSL transport is a thin wrapper around <code>ssl</code>. It requires
-the <code>crypto</code>, <code>asn1</code>, <code>public_key</code> and <code>ssl</code> applications
-to be started. When starting an SSL listener, Ranch will attempt
-to automatically start them. It will not try to stop them when
-the listener is removed, however.</p></div>
-<div class="listingblock">
-<div class="title">Starting the SSL application</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="font-weight: bold"><span style="color: #000000">ssl:start</span></span>()<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>In a proper OTP setting, you will need to make your application
-depend on the <code>crypto</code>, <code>public_key</code> and <code>ssl</code> applications.
-They will be started automatically when starting your release.</p></div>
-<div class="paragraph"><p>The SSL transport <code>accept/2</code> function performs both transport
-and SSL accepts. Errors occurring during the SSL accept phase
-are returned as <code>{error, {ssl_accept, atom()}}</code> to differentiate
-on which socket the problem occurred.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_sending_and_receiving_data">Sending and receiving data</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This section assumes that <code>Transport</code> is a valid transport handler
-(like <code>ranch_tcp</code> or <code>ranch_ssl</code>) and <code>Socket</code> is a connected
-socket obtained through the listener.</p></div>
-<div class="paragraph"><p>You can send data to a socket by calling the <code>Transport:send/2</code>
-function. The data can be given as <code>iodata()</code>, which is defined as
-<code>binary() | iolist()</code>. All the following calls will work:</p></div>
-<div class="listingblock">
-<div class="title">Sending data to the socket</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">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"Ranch is cool!"</span><span style="color: #990000">>></span>)<span style="color: #990000">.</span>
-<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #FF0000">"Ranch is cool!"</span>)<span style="color: #990000">.</span>
-<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, [<span style="color: #FF0000">"Ranch"</span>, [<span style="color: #FF0000">"is"</span>, <span style="color: #FF0000">"cool!"</span>]])<span style="color: #990000">.</span>
-<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, [<span style="color: #FF0000">"Ranch"</span>, [<span style="color: #990000"><<</span><span style="color: #FF0000">"is"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"cool!"</span>]])<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can receive data either in passive or in active mode. Passive mode
-means that you will perform a blocking <code>Transport:recv/3</code> call, while
-active mode means that you will receive the data as a message.</p></div>
-<div class="paragraph"><p>By default, all data will be received as binary. It is possible to
-receive data as strings, although this is not recommended as binaries
-are a more efficient construct, especially for binary protocols.</p></div>
-<div class="paragraph"><p>Receiving data using passive mode requires a single function call. The
-first argument is the socket, and the third argument is a timeout duration
-before the call returns with <code>{error, timeout}</code>.</p></div>
-<div class="paragraph"><p>The second argument is the amount of data in bytes that we want to receive.
-The function will wait for data until it has received exactly this amount.
-If you are not expecting a precise size, you can specify 0 which will make
-this call return as soon as data was read, regardless of its size.</p></div>
-<div class="listingblock">
-<div class="title">Receiving data from the socket in passive mode</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: #FF6600">ok</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">recv</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #993399">0</span>, <span style="color: #993399">5000</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Active mode requires you to inform the socket that you want to receive
-data as a message and to write the code to actually receive it.</p></div>
-<div class="paragraph"><p>There are two kinds of active modes: <code>{active, once}</code> and
-<code>{active, true}</code>. The first will send a single message before going
-back to passive mode; the second will send messages indefinitely.
-We recommend not using the <code>{active, true}</code> mode as it could quickly
-flood your process mailbox. It’s better to keep the data in the socket
-and read it only when required.</p></div>
-<div class="paragraph"><p>Three different messages can be received:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<code>{OK, Socket, Data}</code>
-</p>
-</li>
-<li>
-<p>
-<code>{Closed, Socket}</code>
-</p>
-</li>
-<li>
-<p>
-<code>{Error, Socket, Reason}</code>
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>The value of <code>OK</code>, <code>Closed</code> and <code>Error</code> can be different
-depending on the transport being used. To be able to properly match
-on them you must first call the <code>Transport:messages/0</code> function.</p></div>
-<div class="listingblock">
-<div class="title">Retrieving the transport’s active message identifiers</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">OK</span>, <span style="color: #009900">Closed</span>, <span style="color: #009900">Error</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">messages</span></span>()<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>To start receiving messages you will need to call the <code>Transport:setopts/2</code>
-function, and do so every time you want to receive data.</p></div>
-<div class="listingblock">
-<div class="title">Receiving messages from the socket in active mode</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">OK</span>, <span style="color: #009900">Closed</span>, <span style="color: #009900">Error</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">messages</span></span>(),
-<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">setopts</span></span>(<span style="color: #009900">Socket</span>, [{<span style="color: #FF6600">active</span>, <span style="color: #FF6600">once</span>}]),
-<span style="font-weight: bold"><span style="color: #0000FF">receive</span></span>
- {<span style="color: #009900">OK</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"data received: ~p~n"</span>, [<span style="color: #009900">Data</span>]);
- {<span style="color: #009900">Closed</span>, <span style="color: #009900">Socket</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"socket got closed!~n"</span>);
- {<span style="color: #009900">Error</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"error happened: ~p~n"</span>, [<span style="color: #009900">Reason</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 easily integrate active sockets with existing Erlang code as all
-you really need is just a few more clauses when receiving messages.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_sending_files">Sending files</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>As in the previous section it is assumed <code>Transport</code> is a valid transport
-handler and <code>Socket</code> is a connected socket obtained through the listener.</p></div>
-<div class="paragraph"><p>To send a whole file, with name <code>Filename</code>, over a socket:</p></div>
-<div class="listingblock">
-<div class="title">Sending a file by filename</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: #FF6600">ok</span>, <span style="color: #009900">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Filename</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Or part of a file, with <code>Offset</code> greater than or equal to 0, <code>Bytes</code> number of
-bytes and chunks of size <code>ChunkSize</code>:</p></div>
-<div class="listingblock">
-<div class="title">Sending part of a file by filename in chunks</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">Opts</span> <span style="color: #990000">=</span> [{<span style="color: #FF6600">chunk_size</span>, <span style="color: #009900">ChunkSize</span>}],
-{<span style="color: #FF6600">ok</span>, <span style="color: #009900">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Filename</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Bytes</span>, <span style="color: #009900">Opts</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>To improve efficiency when sending multiple parts of the same file it is also
-possible to use a file descriptor opened in raw mode:</p></div>
-<div class="listingblock">
-<div class="title">Sending a file opened in raw mode</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: #FF6600">ok</span>, <span style="color: #009900">RawFile</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:open</span></span>(<span style="color: #009900">Filename</span>, [<span style="color: #FF6600">raw</span>, <span style="color: #FF6600">read</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>]),
-{<span style="color: #FF6600">ok</span>, <span style="color: #009900">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">RawFile</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Bytes</span>, <span style="color: #009900">Opts</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_writing_a_transport_handler">Writing a transport handler</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A transport handler is a module implementing the <code>ranch_transport</code> behavior.
-It defines a certain number of callbacks that must be written in order to
-allow transparent usage of the transport handler.</p></div>
-<div class="paragraph"><p>The behavior doesn’t define the socket options available when opening a
-socket. These do not need to be common to all transports as it’s easy enough
-to write different initialization functions for the different transports that
-will be used. With one exception though. The <code>setopts/2</code> function <strong>must</strong>
-implement the <code>{active, once}</code> and the <code>{active, true}</code> options.</p></div>
-<div class="paragraph"><p>If the transport handler doesn’t have a native implementation of <code>sendfile/5</code> a
-fallback is available, <code>ranch_transport:sendfile/6</code>. The extra first argument
-is the transport’s module. See <code>ranch_ssl</code> for an example.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>A transport defines the interface to interact with a socket.</p></div> +<div class="paragraph"><p>Transports can be used for connecting, listening and accepting +connections, but also for receiving and sending data. Both +passive and active mode are supported, although all sockets +are initialized as passive.</p></div> +<div class="sect1"> +<h2 id="_tcp_transport">TCP transport</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The TCP transport is a thin wrapper around <code>gen_tcp</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_ssl_transport">SSL transport</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The SSL transport is a thin wrapper around <code>ssl</code>. It requires +the <code>crypto</code>, <code>asn1</code>, <code>public_key</code> and <code>ssl</code> applications +to be started. When starting an SSL listener, Ranch will attempt +to automatically start them. It will not try to stop them when +the listener is removed, however.</p></div> +<div class="listingblock"> +<div class="title">Starting the SSL application</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="font-weight: bold"><span style="color: #000000">ssl:start</span></span>()<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>In a proper OTP setting, you will need to make your application +depend on the <code>crypto</code>, <code>public_key</code> and <code>ssl</code> applications. +They will be started automatically when starting your release.</p></div> +<div class="paragraph"><p>The SSL transport <code>accept/2</code> function performs both transport +and SSL accepts. Errors occurring during the SSL accept phase +are returned as <code>{error, {ssl_accept, atom()}}</code> to differentiate +on which socket the problem occurred.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_sending_and_receiving_data">Sending and receiving data</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This section assumes that <code>Transport</code> is a valid transport handler +(like <code>ranch_tcp</code> or <code>ranch_ssl</code>) and <code>Socket</code> is a connected +socket obtained through the listener.</p></div> +<div class="paragraph"><p>You can send data to a socket by calling the <code>Transport:send/2</code> +function. The data can be given as <code>iodata()</code>, which is defined as +<code>binary() | iolist()</code>. All the following calls will work:</p></div> +<div class="listingblock"> +<div class="title">Sending data to the socket</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">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"Ranch is cool!"</span><span style="color: #990000">>></span>)<span style="color: #990000">.</span> +<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #FF0000">"Ranch is cool!"</span>)<span style="color: #990000">.</span> +<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, [<span style="color: #FF0000">"Ranch"</span>, [<span style="color: #FF0000">"is"</span>, <span style="color: #FF0000">"cool!"</span>]])<span style="color: #990000">.</span> +<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, [<span style="color: #FF0000">"Ranch"</span>, [<span style="color: #990000"><<</span><span style="color: #FF0000">"is"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"cool!"</span>]])<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You can receive data either in passive or in active mode. Passive mode +means that you will perform a blocking <code>Transport:recv/3</code> call, while +active mode means that you will receive the data as a message.</p></div> +<div class="paragraph"><p>By default, all data will be received as binary. It is possible to +receive data as strings, although this is not recommended as binaries +are a more efficient construct, especially for binary protocols.</p></div> +<div class="paragraph"><p>Receiving data using passive mode requires a single function call. The +first argument is the socket, and the third argument is a timeout duration +before the call returns with <code>{error, timeout}</code>.</p></div> +<div class="paragraph"><p>The second argument is the amount of data in bytes that we want to receive. +The function will wait for data until it has received exactly this amount. +If you are not expecting a precise size, you can specify 0 which will make +this call return as soon as data was read, regardless of its size.</p></div> +<div class="listingblock"> +<div class="title">Receiving data from the socket in passive mode</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: #FF6600">ok</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">recv</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #993399">0</span>, <span style="color: #993399">5000</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Active mode requires you to inform the socket that you want to receive +data as a message and to write the code to actually receive it.</p></div> +<div class="paragraph"><p>There are two kinds of active modes: <code>{active, once}</code> and +<code>{active, true}</code>. The first will send a single message before going +back to passive mode; the second will send messages indefinitely. +We recommend not using the <code>{active, true}</code> mode as it could quickly +flood your process mailbox. It’s better to keep the data in the socket +and read it only when required.</p></div> +<div class="paragraph"><p>Three different messages can be received:</p></div> +<div class="ulist"><ul> +<li> +<p> +<code>{OK, Socket, Data}</code> +</p> +</li> +<li> +<p> +<code>{Closed, Socket}</code> +</p> +</li> +<li> +<p> +<code>{Error, Socket, Reason}</code> +</p> +</li> +</ul></div> +<div class="paragraph"><p>The value of <code>OK</code>, <code>Closed</code> and <code>Error</code> can be different +depending on the transport being used. To be able to properly match +on them you must first call the <code>Transport:messages/0</code> function.</p></div> +<div class="listingblock"> +<div class="title">Retrieving the transport’s active message identifiers</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">OK</span>, <span style="color: #009900">Closed</span>, <span style="color: #009900">Error</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">messages</span></span>()<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>To start receiving messages you will need to call the <code>Transport:setopts/2</code> +function, and do so every time you want to receive data.</p></div> +<div class="listingblock"> +<div class="title">Receiving messages from the socket in active mode</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">OK</span>, <span style="color: #009900">Closed</span>, <span style="color: #009900">Error</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">messages</span></span>(), +<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">setopts</span></span>(<span style="color: #009900">Socket</span>, [{<span style="color: #FF6600">active</span>, <span style="color: #FF6600">once</span>}]), +<span style="font-weight: bold"><span style="color: #0000FF">receive</span></span> + {<span style="color: #009900">OK</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"data received: ~p~n"</span>, [<span style="color: #009900">Data</span>]); + {<span style="color: #009900">Closed</span>, <span style="color: #009900">Socket</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"socket got closed!~n"</span>); + {<span style="color: #009900">Error</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"error happened: ~p~n"</span>, [<span style="color: #009900">Reason</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 easily integrate active sockets with existing Erlang code as all +you really need is just a few more clauses when receiving messages.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_sending_files">Sending files</h2> +<div class="sectionbody"> +<div class="paragraph"><p>As in the previous section it is assumed <code>Transport</code> is a valid transport +handler and <code>Socket</code> is a connected socket obtained through the listener.</p></div> +<div class="paragraph"><p>To send a whole file, with name <code>Filename</code>, over a socket:</p></div> +<div class="listingblock"> +<div class="title">Sending a file by filename</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: #FF6600">ok</span>, <span style="color: #009900">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Filename</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Or part of a file, with <code>Offset</code> greater than or equal to 0, <code>Bytes</code> number of +bytes and chunks of size <code>ChunkSize</code>:</p></div> +<div class="listingblock"> +<div class="title">Sending part of a file by filename in chunks</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">Opts</span> <span style="color: #990000">=</span> [{<span style="color: #FF6600">chunk_size</span>, <span style="color: #009900">ChunkSize</span>}], +{<span style="color: #FF6600">ok</span>, <span style="color: #009900">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Filename</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Bytes</span>, <span style="color: #009900">Opts</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>To improve efficiency when sending multiple parts of the same file it is also +possible to use a file descriptor opened in raw mode:</p></div> +<div class="listingblock"> +<div class="title">Sending a file opened in raw mode</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: #FF6600">ok</span>, <span style="color: #009900">RawFile</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:open</span></span>(<span style="color: #009900">Filename</span>, [<span style="color: #FF6600">raw</span>, <span style="color: #FF6600">read</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>]), +{<span style="color: #FF6600">ok</span>, <span style="color: #009900">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">RawFile</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Bytes</span>, <span style="color: #009900">Opts</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_writing_a_transport_handler">Writing a transport handler</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A transport handler is a module implementing the <code>ranch_transport</code> behavior. +It defines a certain number of callbacks that must be written in order to +allow transparent usage of the transport handler.</p></div> +<div class="paragraph"><p>The behavior doesn’t define the socket options available when opening a +socket. These do not need to be common to all transports as it’s easy enough +to write different initialization functions for the different transports that +will be used. With one exception though. The <code>setopts/2</code> function <strong>must</strong> +implement the <code>{active, once}</code> and the <code>{active, true}</code> options.</p></div> +<div class="paragraph"><p>If the transport handler doesn’t have a native implementation of <code>sendfile/5</code> a +fallback is available, <code>ranch_transport:sendfile/6</code>. The extra first argument +is the transport’s module. See <code>ranch_ssl</code> for an example.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.2/index.html b/docs/en/ranch/1.2/index.html index d87c4243..0194031a 100644 --- a/docs/en/ranch/1.2/index.html +++ b/docs/en/ranch/1.2/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file diff --git a/docs/en/ranch/1.2/manual/index.html b/docs/en/ranch/1.2/manual/index.html index 08dcf0ce..eecb6cbe 100644 --- a/docs/en/ranch/1.2/manual/index.html +++ b/docs/en/ranch/1.2/manual/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Ranch Function Reference</title> @@ -67,38 +67,38 @@ <h1 class="lined-header"><span>Ranch Function Reference</span></h1> -<div class="ulist"><ul>
-<li>
-<p>
-<a href="ranch_app">ranch(7)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch">ranch(3)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch_protocol">ranch_protocol(3)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch_ssl">ranch_ssl(3)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch_tcp">ranch_tcp(3)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch_transport">ranch_transport(3)</a>
-</p>
-</li>
-</ul></div>
+<div class="ulist"><ul> +<li> +<p> +<a href="ranch_app">ranch(7)</a> +</p> +</li> +<li> +<p> +<a href="ranch">ranch(3)</a> +</p> +</li> +<li> +<p> +<a href="ranch_protocol">ranch_protocol(3)</a> +</p> +</li> +<li> +<p> +<a href="ranch_ssl">ranch_ssl(3)</a> +</p> +</li> +<li> +<p> +<a href="ranch_tcp">ranch_tcp(3)</a> +</p> +</li> +<li> +<p> +<a href="ranch_transport">ranch_transport(3)</a> +</p> +</li> +</ul></div> diff --git a/docs/en/ranch/1.2/manual/ranch/index.html b/docs/en/ranch/1.2/manual/ranch/index.html index 2c72b236..2cbc5dec 100644 --- a/docs/en/ranch/1.2/manual/ranch/index.html +++ b/docs/en/ranch/1.2/manual/ranch/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch(3)</title> @@ -67,423 +67,423 @@ <h1 class="lined-header"><span>ranch(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>ranch - socket acceptor pool</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>ranch</code> module provides functions for starting and
-manipulating Ranch listeners.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_max_conns_non_neg_integer_infinity">max_conns() = non_neg_integer() | infinity</h3>
-<div class="paragraph"><p>Maximum number of connections allowed on this listener.</p></div>
-<div class="paragraph"><p>This is a soft limit. The actual number of connections
-might be slightly above the limit due to concurrency
-when accepting new connections. Some connections may
-also be removed from this count explicitly by the user
-code.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_opt">opt()</h3>
-<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">opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">ack_timeout</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()}
- | {<span style="color: #FF6600">connection_type</span>, <span style="color: #FF6600">worker</span> | <span style="color: #FF6600">supervisor</span>}
- | {<span style="color: #FF6600">max_connections</span>, <span style="font-weight: bold"><span style="color: #000000">max_conns</span></span>()}
- | {<span style="color: #000080">shutdown</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>() | <span style="color: #FF6600">brutal_kill</span>}
- | {<span style="color: #FF6600">socket</span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>Ranch-specific transport options.</p></div>
-<div class="paragraph"><p>These options are not passed on to the transports.
-They are used by Ranch while setting up the listeners.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_ref_any">ref() = any()</h3>
-<div class="paragraph"><p>Unique name used to refer to a listener.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_option_descriptions">Option descriptions</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>None of the options are required.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ack_timeout (5000)
-</dt>
-<dd>
-<p>
- Maximum allowed time for the <code>ranch:accept_ack/1</code> call to finish.
-</p>
-</dd>
-<dt class="hdlist1">
-connection_type (worker)
-</dt>
-<dd>
-<p>
- Type of process that will handle the connection.
-</p>
-</dd>
-<dt class="hdlist1">
-max_connections (1024)
-</dt>
-<dd>
-<p>
- Maximum number of active connections. Soft limit. Using <code>infinity</code> will disable the limit entirely.
-</p>
-</dd>
-<dt class="hdlist1">
-shutdown (5000)
-</dt>
-<dd>
-<p>
- Maximum allowed time for children to stop on listener shutdown.
-</p>
-</dd>
-<dt class="hdlist1">
-socket
-</dt>
-<dd>
-<p>
- Listening socket opened externally to be used instead of calling <code>Transport:listen/1</code>.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exports">Exports</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_accept_ack_ref_8594_ok">accept_ack(Ref) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Acknowledge that the connection is accepted.</p></div>
-<div class="paragraph"><p>This function MUST be used by a connection process to inform
-Ranch that it initialized properly and let it perform any
-additional operations before the socket can be safely used.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_child_spec_ref_nbacceptors_transport_transopts_protocol_protoopts_8594_supervisor_child_spec">child_spec(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) → supervisor:child_spec()</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-NbAcceptors = non_neg_integer()
-</dt>
-<dd>
-<p>
-Number of acceptor processes.
-</p>
-</dd>
-<dt class="hdlist1">
-Transport = module()
-</dt>
-<dd>
-<p>
-Transport module.
-</p>
-</dd>
-<dt class="hdlist1">
-TransOpts = any()
-</dt>
-<dd>
-<p>
-Transport options.
-</p>
-</dd>
-<dt class="hdlist1">
-Protocol = module()
-</dt>
-<dd>
-<p>
-Protocol module.
-</p>
-</dd>
-<dt class="hdlist1">
-ProtoOpts = any()
-</dt>
-<dd>
-<p>
-Protocol options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return child specifications for a new listener.</p></div>
-<div class="paragraph"><p>This function can be used to embed a listener directly
-in an application instead of letting Ranch handle it.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_get_addr_ref_8594_ip_port">get_addr(Ref) → {IP, Port}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-IP = inet:ip_address()
-</dt>
-<dd>
-<p>
-IP of the interface used by this listener.
-</p>
-</dd>
-<dt class="hdlist1">
-Port = inet:port_number()
-</dt>
-<dd>
-<p>
-Port number used by this listener.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the IP address and port for the given listener.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_get_max_connections_ref_8594_maxconns">get_max_connections(Ref) → MaxConns</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-MaxConns = max_conns()
-</dt>
-<dd>
-<p>
-Current maximum number of connections.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the max number of connections allowed for the given listener.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_get_port_ref_8594_port">get_port(Ref) → Port</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-Port = inet:port_number()
-</dt>
-<dd>
-<p>
-Port number used by this listener.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the port for the given listener.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_get_protocol_options_ref_8594_protoopts">get_protocol_options(Ref) → ProtoOpts</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-ProtoOpts = any()
-</dt>
-<dd>
-<p>
-Current protocol options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the protocol options set for the given listener.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_remove_connection_ref_8594_ok">remove_connection(Ref) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Do not count this connection when limiting the number of connections.</p></div>
-<div class="paragraph"><p>You can use this function for long-running connection processes
-which spend most of their time idling rather than consuming
-resources. This allows Ranch to accept a lot more connections
-without sacrificing the latency of the system.</p></div>
-<div class="paragraph"><p>This function may only be called from a connection process.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_set_max_connections_ref_maxconns_8594_ok">set_max_connections(Ref, MaxConns) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-MaxConns = max_conns()
-</dt>
-<dd>
-<p>
-New maximum number of connections.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Set the max number of connections for the given listener.</p></div>
-<div class="paragraph"><p>The change will be applied immediately. If the new value is
-smaller than the previous one, Ranch will not kill the extra
-connections, but will wait for them to terminate properly.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_set_protocol_options_ref_protoopts_8594_ok">set_protocol_options(Ref, ProtoOpts) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-ProtoOpts = any()
-</dt>
-<dd>
-<p>
-New protocol options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Set the protocol options for the given listener.</p></div>
-<div class="paragraph"><p>The change will be applied immediately for all new connections.
-Old connections will not receive the new options.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_start_listener_ref_nbacceptors_transport_transopts_protocol_protoopts_8594_ok_pid_error_badarg">start_listener(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) → {ok, pid()} | {error, badarg}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-NbAcceptors = non_neg_integer()
-</dt>
-<dd>
-<p>
-Number of acceptor processes.
-</p>
-</dd>
-<dt class="hdlist1">
-Transport = module()
-</dt>
-<dd>
-<p>
-Transport module.
-</p>
-</dd>
-<dt class="hdlist1">
-TransOpts = any()
-</dt>
-<dd>
-<p>
-Transport options.
-</p>
-</dd>
-<dt class="hdlist1">
-Protocol = module()
-</dt>
-<dd>
-<p>
-Protocol module.
-</p>
-</dd>
-<dt class="hdlist1">
-ProtoOpts = any()
-</dt>
-<dd>
-<p>
-Protocol options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Start listening for connections using the given transport
-and protocol. Returns the pid for this listener’s supervisor.</p></div>
-<div class="paragraph"><p>There are additional transport options that apply
-regardless of transport. They allow configuring how the
-connections are supervised, rate limited and more. Please
-consult the previous section for more details.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_stop_listener_ref_8594_ok_error_not_found">stop_listener(Ref) → ok | {error, not_found}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Stop the given listener.</p></div>
-<div class="paragraph"><p>The listener is stopped gracefully, first by closing the
-listening port, then by stopping the connection processes.
-These processes are stopped according to the <code>shutdown</code>
-transport option, which may be set to brutally kill all
-connection processes or give them some time to stop properly.</p></div>
-<div class="paragraph"><p>This function does not return until the listener is
-completely stopped.</p></div>
-</div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch - socket acceptor pool</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch</code> module provides functions for starting and +manipulating Ranch listeners.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_max_conns_non_neg_integer_infinity">max_conns() = non_neg_integer() | infinity</h3> +<div class="paragraph"><p>Maximum number of connections allowed on this listener.</p></div> +<div class="paragraph"><p>This is a soft limit. The actual number of connections +might be slightly above the limit due to concurrency +when accepting new connections. Some connections may +also be removed from this count explicitly by the user +code.</p></div> +</div> +<div class="sect2"> +<h3 id="_opt">opt()</h3> +<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">opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">ack_timeout</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()} + | {<span style="color: #FF6600">connection_type</span>, <span style="color: #FF6600">worker</span> | <span style="color: #FF6600">supervisor</span>} + | {<span style="color: #FF6600">max_connections</span>, <span style="font-weight: bold"><span style="color: #000000">max_conns</span></span>()} + | {<span style="color: #000080">shutdown</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>() | <span style="color: #FF6600">brutal_kill</span>} + | {<span style="color: #FF6600">socket</span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Ranch-specific transport options.</p></div> +<div class="paragraph"><p>These options are not passed on to the transports. +They are used by Ranch while setting up the listeners.</p></div> +</div> +<div class="sect2"> +<h3 id="_ref_any">ref() = any()</h3> +<div class="paragraph"><p>Unique name used to refer to a listener.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_option_descriptions">Option descriptions</h2> +<div class="sectionbody"> +<div class="paragraph"><p>None of the options are required.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +ack_timeout (5000) +</dt> +<dd> +<p> + Maximum allowed time for the <code>ranch:accept_ack/1</code> call to finish. +</p> +</dd> +<dt class="hdlist1"> +connection_type (worker) +</dt> +<dd> +<p> + Type of process that will handle the connection. +</p> +</dd> +<dt class="hdlist1"> +max_connections (1024) +</dt> +<dd> +<p> + Maximum number of active connections. Soft limit. Using <code>infinity</code> will disable the limit entirely. +</p> +</dd> +<dt class="hdlist1"> +shutdown (5000) +</dt> +<dd> +<p> + Maximum allowed time for children to stop on listener shutdown. +</p> +</dd> +<dt class="hdlist1"> +socket +</dt> +<dd> +<p> + Listening socket opened externally to be used instead of calling <code>Transport:listen/1</code>. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_accept_ack_ref_8594_ok">accept_ack(Ref) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Acknowledge that the connection is accepted.</p></div> +<div class="paragraph"><p>This function MUST be used by a connection process to inform +Ranch that it initialized properly and let it perform any +additional operations before the socket can be safely used.</p></div> +</div> +<div class="sect2"> +<h3 id="_child_spec_ref_nbacceptors_transport_transopts_protocol_protoopts_8594_supervisor_child_spec">child_spec(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) → supervisor:child_spec()</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +NbAcceptors = non_neg_integer() +</dt> +<dd> +<p> +Number of acceptor processes. +</p> +</dd> +<dt class="hdlist1"> +Transport = module() +</dt> +<dd> +<p> +Transport module. +</p> +</dd> +<dt class="hdlist1"> +TransOpts = any() +</dt> +<dd> +<p> +Transport options. +</p> +</dd> +<dt class="hdlist1"> +Protocol = module() +</dt> +<dd> +<p> +Protocol module. +</p> +</dd> +<dt class="hdlist1"> +ProtoOpts = any() +</dt> +<dd> +<p> +Protocol options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return child specifications for a new listener.</p></div> +<div class="paragraph"><p>This function can be used to embed a listener directly +in an application instead of letting Ranch handle it.</p></div> +</div> +<div class="sect2"> +<h3 id="_get_addr_ref_8594_ip_port">get_addr(Ref) → {IP, Port}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +IP = inet:ip_address() +</dt> +<dd> +<p> +IP of the interface used by this listener. +</p> +</dd> +<dt class="hdlist1"> +Port = inet:port_number() +</dt> +<dd> +<p> +Port number used by this listener. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the IP address and port for the given listener.</p></div> +</div> +<div class="sect2"> +<h3 id="_get_max_connections_ref_8594_maxconns">get_max_connections(Ref) → MaxConns</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +MaxConns = max_conns() +</dt> +<dd> +<p> +Current maximum number of connections. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the max number of connections allowed for the given listener.</p></div> +</div> +<div class="sect2"> +<h3 id="_get_port_ref_8594_port">get_port(Ref) → Port</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +Port = inet:port_number() +</dt> +<dd> +<p> +Port number used by this listener. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the port for the given listener.</p></div> +</div> +<div class="sect2"> +<h3 id="_get_protocol_options_ref_8594_protoopts">get_protocol_options(Ref) → ProtoOpts</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +ProtoOpts = any() +</dt> +<dd> +<p> +Current protocol options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the protocol options set for the given listener.</p></div> +</div> +<div class="sect2"> +<h3 id="_remove_connection_ref_8594_ok">remove_connection(Ref) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Do not count this connection when limiting the number of connections.</p></div> +<div class="paragraph"><p>You can use this function for long-running connection processes +which spend most of their time idling rather than consuming +resources. This allows Ranch to accept a lot more connections +without sacrificing the latency of the system.</p></div> +<div class="paragraph"><p>This function may only be called from a connection process.</p></div> +</div> +<div class="sect2"> +<h3 id="_set_max_connections_ref_maxconns_8594_ok">set_max_connections(Ref, MaxConns) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +MaxConns = max_conns() +</dt> +<dd> +<p> +New maximum number of connections. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Set the max number of connections for the given listener.</p></div> +<div class="paragraph"><p>The change will be applied immediately. If the new value is +smaller than the previous one, Ranch will not kill the extra +connections, but will wait for them to terminate properly.</p></div> +</div> +<div class="sect2"> +<h3 id="_set_protocol_options_ref_protoopts_8594_ok">set_protocol_options(Ref, ProtoOpts) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +ProtoOpts = any() +</dt> +<dd> +<p> +New protocol options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Set the protocol options for the given listener.</p></div> +<div class="paragraph"><p>The change will be applied immediately for all new connections. +Old connections will not receive the new options.</p></div> +</div> +<div class="sect2"> +<h3 id="_start_listener_ref_nbacceptors_transport_transopts_protocol_protoopts_8594_ok_pid_error_badarg">start_listener(Ref, NbAcceptors, Transport, TransOpts, Protocol, ProtoOpts) → {ok, pid()} | {error, badarg}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +NbAcceptors = non_neg_integer() +</dt> +<dd> +<p> +Number of acceptor processes. +</p> +</dd> +<dt class="hdlist1"> +Transport = module() +</dt> +<dd> +<p> +Transport module. +</p> +</dd> +<dt class="hdlist1"> +TransOpts = any() +</dt> +<dd> +<p> +Transport options. +</p> +</dd> +<dt class="hdlist1"> +Protocol = module() +</dt> +<dd> +<p> +Protocol module. +</p> +</dd> +<dt class="hdlist1"> +ProtoOpts = any() +</dt> +<dd> +<p> +Protocol options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Start listening for connections using the given transport +and protocol. Returns the pid for this listener’s supervisor.</p></div> +<div class="paragraph"><p>There are additional transport options that apply +regardless of transport. They allow configuring how the +connections are supervised, rate limited and more. Please +consult the previous section for more details.</p></div> +</div> +<div class="sect2"> +<h3 id="_stop_listener_ref_8594_ok_error_not_found">stop_listener(Ref) → ok | {error, not_found}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Stop the given listener.</p></div> +<div class="paragraph"><p>The listener is stopped gracefully, first by closing the +listening port, then by stopping the connection processes. +These processes are stopped according to the <code>shutdown</code> +transport option, which may be set to brutally kill all +connection processes or give them some time to stop properly.</p></div> +<div class="paragraph"><p>This function does not return until the listener is +completely stopped.</p></div> +</div> +</div> +</div> diff --git a/docs/en/ranch/1.2/manual/ranch_app/index.html b/docs/en/ranch/1.2/manual/ranch_app/index.html index fd930bf4..a3f2b89c 100644 --- a/docs/en/ranch/1.2/manual/ranch_app/index.html +++ b/docs/en/ranch/1.2/manual/ranch_app/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch(7)</title> @@ -67,43 +67,43 @@ <h1 class="lined-header"><span>ranch(7)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>ranch - Socket acceptor pool for TCP protocols.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_dependencies">Dependencies</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>ranch</code> application has no particular dependency required
-to start.</p></div>
-<div class="paragraph"><p>It has optional dependencies that are only required when
-listening for SSL connections. The dependencies are <code>crypto</code>,
-<code>asn1</code>, <code>public_key</code> and <code>ssl</code>. They are started automatically
-if they weren’t before.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_environment">Environment</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>ranch</code> application defines one application environment
-configuration parameter.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-profile (false)
-</dt>
-<dd>
-<p>
- When enabled, Ranch will start <code>eprof</code> profiling automatically.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>You can use the <code>ranch_app:profile_output/0</code> function to stop
-profiling and output the results to the files <em>procs.profile</em>
-and <em>total.profile</em>. Do not use in production.</p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch - Socket acceptor pool for TCP protocols.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_dependencies">Dependencies</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch</code> application has no particular dependency required +to start.</p></div> +<div class="paragraph"><p>It has optional dependencies that are only required when +listening for SSL connections. The dependencies are <code>crypto</code>, +<code>asn1</code>, <code>public_key</code> and <code>ssl</code>. They are started automatically +if they weren’t before.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_environment">Environment</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch</code> application defines one application environment +configuration parameter.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +profile (false) +</dt> +<dd> +<p> + When enabled, Ranch will start <code>eprof</code> profiling automatically. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>You can use the <code>ranch_app:profile_output/0</code> function to stop +profiling and output the results to the files <em>procs.profile</em> +and <em>total.profile</em>. Do not use in production.</p></div> +</div> +</div> diff --git a/docs/en/ranch/1.2/manual/ranch_protocol/index.html b/docs/en/ranch/1.2/manual/ranch_protocol/index.html index e8411a2c..f88fad6c 100644 --- a/docs/en/ranch/1.2/manual/ranch_protocol/index.html +++ b/docs/en/ranch/1.2/manual/ranch_protocol/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch_protocol(3)</title> @@ -67,83 +67,83 @@ <h1 class="lined-header"><span>ranch_protocol(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>ranch_protocol - behaviour for protocol modules</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>ranch_protocol</code> behaviour defines the interface used
-by Ranch protocols.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>None.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_callbacks">Callbacks</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_start_link_ref_socket_transport_protoopts_8594_ok_pid_ok_pid_pid">start_link(Ref, Socket, Transport, ProtoOpts) → {ok, pid()} | {ok, pid(), pid()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ranch:ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-Socket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-Transport = module()
-</dt>
-<dd>
-<p>
-Transport module for this socket.
-</p>
-</dd>
-<dt class="hdlist1">
-ProtoOpts = any()
-</dt>
-<dd>
-<p>
-Protocol options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Start a new connection process for the given socket.</p></div>
-<div class="paragraph"><p>The only purpose of this callback is to start a process that
-will handle the socket. It must spawn the process, link and
-then return the new pid. This function will always be called
-from inside a supervisor.</p></div>
-<div class="paragraph"><p>This callback can also return two pids. The first pid is the
-pid of the process that will be supervised. The second pid is
-the pid of the process that will receive ownership of the
-socket. This second process must be a child of the first. This
-form is only available when <code>connection_type</code> is set to
-<code>supervisor</code>.</p></div>
-<div class="paragraph"><p>If any other value is returned, the supervisor will close the
-socket and assume no process has been started.</p></div>
-<div class="paragraph"><p>Do not perform any operations in this callback, as this would
-block the supervisor responsible for starting connection
-processes and degrade performance severely.</p></div>
-</div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch_protocol - behaviour for protocol modules</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch_protocol</code> behaviour defines the interface used +by Ranch protocols.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="paragraph"><p>None.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_callbacks">Callbacks</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_start_link_ref_socket_transport_protoopts_8594_ok_pid_ok_pid_pid">start_link(Ref, Socket, Transport, ProtoOpts) → {ok, pid()} | {ok, pid(), pid()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ranch:ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +Socket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +Transport = module() +</dt> +<dd> +<p> +Transport module for this socket. +</p> +</dd> +<dt class="hdlist1"> +ProtoOpts = any() +</dt> +<dd> +<p> +Protocol options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Start a new connection process for the given socket.</p></div> +<div class="paragraph"><p>The only purpose of this callback is to start a process that +will handle the socket. It must spawn the process, link and +then return the new pid. This function will always be called +from inside a supervisor.</p></div> +<div class="paragraph"><p>This callback can also return two pids. The first pid is the +pid of the process that will be supervised. The second pid is +the pid of the process that will receive ownership of the +socket. This second process must be a child of the first. This +form is only available when <code>connection_type</code> is set to +<code>supervisor</code>.</p></div> +<div class="paragraph"><p>If any other value is returned, the supervisor will close the +socket and assume no process has been started.</p></div> +<div class="paragraph"><p>Do not perform any operations in this callback, as this would +block the supervisor responsible for starting connection +processes and degrade performance severely.</p></div> +</div> +</div> +</div> diff --git a/docs/en/ranch/1.2/manual/ranch_ssl/index.html b/docs/en/ranch/1.2/manual/ranch_ssl/index.html index c006d8e6..d1b83d48 100644 --- a/docs/en/ranch/1.2/manual/ranch_ssl/index.html +++ b/docs/en/ranch/1.2/manual/ranch_ssl/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch_ssl(3)</title> @@ -67,349 +67,349 @@ <h1 class="lined-header"><span>ranch_ssl(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>ranch_ssl - SSL transport module</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>ranch_ssl</code> module implements an SSL Ranch transport.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_ssl_opt">ssl_opt()</h3>
-<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">ssl_opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">alpn_preferred_protocols</span>, [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()]}
- | {<span style="color: #FF6600">cacertfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
- | {<span style="color: #FF6600">cacerts</span>, [<span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()]}
- | {<span style="color: #FF6600">cert</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()}
- | {<span style="color: #FF6600">certfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
- | {<span style="color: #FF6600">ciphers</span>, [<span style="font-weight: bold"><span style="color: #000000">ssl:erl_cipher_suite</span></span>()] | <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
- | {<span style="color: #FF6600">client_renegotiation</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">crl_cache</span>, {<span style="font-weight: bold"><span style="color: #000000">module</span></span>(), {<span style="color: #FF6600">internal</span> | <span style="font-weight: bold"><span style="color: #000000">any</span></span>(), <span style="font-weight: bold"><span style="color: #000080">list</span></span>()}}}
- | {<span style="color: #FF6600">crl_check</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() | <span style="color: #FF6600">peer</span> | <span style="color: #FF6600">best_effort</span>}
- | {<span style="color: #FF6600">depth</span>, <span style="color: #993399">0</span><span style="color: #990000">..</span><span style="color: #993399">255</span>}
- | {<span style="color: #FF6600">dh</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()}
- | {<span style="color: #FF6600">dhfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
- | {<span style="color: #FF6600">fail_if_no_peer_cert</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">hibernate_after</span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>() | <span style="color: #000080">undefined</span>}
- | {<span style="color: #FF6600">honor_cipher_order</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">key</span>, {<span style="color: #FF6600">'RSAPrivateKey'</span> | <span style="color: #FF6600">'DSAPrivateKey'</span> | <span style="color: #FF6600">'PrivateKeyInfo'</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()}}
- | {<span style="color: #FF6600">keyfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
- | {<span style="color: #FF6600">log_alert</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">next_protocols_advertised</span>, [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()]}
- | {<span style="color: #FF6600">partial_chain</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(([<span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()]) <span style="color: #990000">-></span> {<span style="color: #FF6600">trusted_ca</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()} | <span style="color: #FF6600">unknown_ca</span>)}
- | {<span style="color: #FF6600">password</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
- | {<span style="color: #FF6600">psk_identity</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
- | {<span style="color: #FF6600">reuse_session</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>()}
- | {<span style="color: #FF6600">reuse_sessions</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">secure_renegotiate</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">sni_fun</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>()}
- | {<span style="color: #FF6600">sni_hosts</span>, [{<span style="font-weight: bold"><span style="color: #000000">string</span></span>(), <span style="font-weight: bold"><span style="color: #000000">ssl_opt</span></span>()}]}
- | {<span style="color: #FF6600">user_lookup_fun</span>, {<span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(), <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}}
- | {<span style="color: #FF6600">verify</span>, <span style="font-weight: bold"><span style="color: #000000">ssl:verify_type</span></span>()}
- | {<span style="color: #FF6600">verify_fun</span>, {<span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(), <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}}
- | {<span style="color: #FF6600">versions</span>, [<span style="font-weight: bold"><span style="color: #000080">atom</span></span>()]}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>SSL-specific listen options.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_opt_ranch_tcp_opt_ssl_opt">opt() = ranch_tcp:opt() | ssl_opt()</h3>
-<div class="paragraph"><p>Listen options.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_opts_opt">opts() = [opt()]</h3>
-<div class="paragraph"><p>List of listen options.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_option_descriptions">Option descriptions</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Specifying a certificate is mandatory, either through the <code>cert</code>
-or the <code>certfile</code> option. None of the other options are required.</p></div>
-<div class="paragraph"><p>The default value is given next to the option name.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-alpn_preferred_protocols
-</dt>
-<dd>
-<p>
- Perform Application-Layer Protocol Negotiation with the given list of preferred protocols.
-</p>
-</dd>
-<dt class="hdlist1">
-cacertfile
-</dt>
-<dd>
-<p>
- Path to PEM encoded trusted certificates file used to verify peer certificates.
-</p>
-</dd>
-<dt class="hdlist1">
-cacerts
-</dt>
-<dd>
-<p>
- List of DER encoded trusted certificates.
-</p>
-</dd>
-<dt class="hdlist1">
-cert
-</dt>
-<dd>
-<p>
- DER encoded user certificate.
-</p>
-</dd>
-<dt class="hdlist1">
-certfile
-</dt>
-<dd>
-<p>
- Path to the PEM encoded user certificate file. May also contain the private key.
-</p>
-</dd>
-<dt class="hdlist1">
-ciphers
-</dt>
-<dd>
-<p>
- List of ciphers that clients are allowed to use.
-</p>
-</dd>
-<dt class="hdlist1">
-client_renegotiation (true)
-</dt>
-<dd>
-<p>
- Whether to allow client-initiated renegotiation.
-</p>
-</dd>
-<dt class="hdlist1">
-crl_cache ({ssl_crl_cache, {internal, []}})
-</dt>
-<dd>
-<p>
- Customize the module used to cache Certificate Revocation Lists.
-</p>
-</dd>
-<dt class="hdlist1">
-crl_check (false)
-</dt>
-<dd>
-<p>
- Whether to perform CRL check on all certificates in the chain during validation.
-</p>
-</dd>
-<dt class="hdlist1">
-depth (1)
-</dt>
-<dd>
-<p>
- Maximum of intermediate certificates allowed in the certification path.
-</p>
-</dd>
-<dt class="hdlist1">
-dh
-</dt>
-<dd>
-<p>
- DER encoded Diffie-Hellman parameters.
-</p>
-</dd>
-<dt class="hdlist1">
-dhfile
-</dt>
-<dd>
-<p>
- Path to the PEM encoded Diffie-Hellman parameters file.
-</p>
-</dd>
-<dt class="hdlist1">
-fail_if_no_peer_cert (false)
-</dt>
-<dd>
-<p>
- Whether to refuse the connection if the client sends an empty certificate.
-</p>
-</dd>
-<dt class="hdlist1">
-hibernate_after (undefined)
-</dt>
-<dd>
-<p>
- Time in ms after which SSL socket processes go into hibernation to reduce memory usage.
-</p>
-</dd>
-<dt class="hdlist1">
-honor_cipher_order (false)
-</dt>
-<dd>
-<p>
- If true, use the server’s preference for cipher selection. If false, use the client’s preference.
-</p>
-</dd>
-<dt class="hdlist1">
-key
-</dt>
-<dd>
-<p>
- DER encoded user private key.
-</p>
-</dd>
-<dt class="hdlist1">
-keyfile
-</dt>
-<dd>
-<p>
- Path to the PEM encoded private key file, if different than the certfile.
-</p>
-</dd>
-<dt class="hdlist1">
-log_alert (true)
-</dt>
-<dd>
-<p>
- If false, error reports will not be displayed.
-</p>
-</dd>
-<dt class="hdlist1">
-next_protocols_advertised
-</dt>
-<dd>
-<p>
- List of protocols to send to the client if it supports the Next Protocol extension.
-</p>
-</dd>
-<dt class="hdlist1">
-nodelay (true)
-</dt>
-<dd>
-<p>
- Whether to enable TCP_NODELAY.
-</p>
-</dd>
-<dt class="hdlist1">
-partial_chain
-</dt>
-<dd>
-<p>
- Claim an intermediate CA in the chain as trusted.
-</p>
-</dd>
-<dt class="hdlist1">
-password
-</dt>
-<dd>
-<p>
- Password to the private key file, if password protected.
-</p>
-</dd>
-<dt class="hdlist1">
-psk_identity
-</dt>
-<dd>
-<p>
- Provide the given PSK identity hint to the client during the handshake.
-</p>
-</dd>
-<dt class="hdlist1">
-reuse_session
-</dt>
-<dd>
-<p>
- Custom policy to decide whether a session should be reused.
-</p>
-</dd>
-<dt class="hdlist1">
-reuse_sessions (false)
-</dt>
-<dd>
-<p>
- Whether to allow session reuse.
-</p>
-</dd>
-<dt class="hdlist1">
-secure_renegotiate (false)
-</dt>
-<dd>
-<p>
- Whether to reject renegotiation attempts that do not conform to RFC5746.
-</p>
-</dd>
-<dt class="hdlist1">
-sni_fun
-</dt>
-<dd>
-<p>
- Function called when the client requests a host using Server Name Indication. Returns options to apply.
-</p>
-</dd>
-<dt class="hdlist1">
-sni_hosts
-</dt>
-<dd>
-<p>
- Options to apply for the host that matches what the client requested with Server Name Indication.
-</p>
-</dd>
-<dt class="hdlist1">
-user_lookup_fun
-</dt>
-<dd>
-<p>
- Function called to determine the shared secret when using PSK, or provide parameters when using SRP.
-</p>
-</dd>
-<dt class="hdlist1">
-verify (verify_none)
-</dt>
-<dd>
-<p>
- Use <code>verify_peer</code> to request a certificate from the client.
-</p>
-</dd>
-<dt class="hdlist1">
-verify_fun
-</dt>
-<dd>
-<p>
- Custom policy to decide whether a client certificate is valid.
-</p>
-</dd>
-<dt class="hdlist1">
-versions
-</dt>
-<dd>
-<p>
- TLS protocol versions that will be supported.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Note that the client will not send a certificate unless the
-value for the <code>verify</code> option is set to <code>verify_peer</code>. This
-means that the <code>fail_if_no_peer_cert</code> only apply when combined
-with the <code>verify</code> option. The <code>verify_fun</code> option allows
-greater control over the client certificate validation.</p></div>
-<div class="paragraph"><p>The options <code>sni_fun</code> and <code>sni_hosts</code> are mutually exclusive.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exports">Exports</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>None.</p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch_ssl - SSL transport module</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch_ssl</code> module implements an SSL Ranch transport.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_ssl_opt">ssl_opt()</h3> +<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">ssl_opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">alpn_preferred_protocols</span>, [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()]} + | {<span style="color: #FF6600">cacertfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">cacerts</span>, [<span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()]} + | {<span style="color: #FF6600">cert</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()} + | {<span style="color: #FF6600">certfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">ciphers</span>, [<span style="font-weight: bold"><span style="color: #000000">ssl:erl_cipher_suite</span></span>()] | <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">client_renegotiation</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">crl_cache</span>, {<span style="font-weight: bold"><span style="color: #000000">module</span></span>(), {<span style="color: #FF6600">internal</span> | <span style="font-weight: bold"><span style="color: #000000">any</span></span>(), <span style="font-weight: bold"><span style="color: #000080">list</span></span>()}}} + | {<span style="color: #FF6600">crl_check</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() | <span style="color: #FF6600">peer</span> | <span style="color: #FF6600">best_effort</span>} + | {<span style="color: #FF6600">depth</span>, <span style="color: #993399">0</span><span style="color: #990000">..</span><span style="color: #993399">255</span>} + | {<span style="color: #FF6600">dh</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()} + | {<span style="color: #FF6600">dhfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">fail_if_no_peer_cert</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">hibernate_after</span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>() | <span style="color: #000080">undefined</span>} + | {<span style="color: #FF6600">honor_cipher_order</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">key</span>, {<span style="color: #FF6600">'RSAPrivateKey'</span> | <span style="color: #FF6600">'DSAPrivateKey'</span> | <span style="color: #FF6600">'PrivateKeyInfo'</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()}} + | {<span style="color: #FF6600">keyfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">log_alert</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">next_protocols_advertised</span>, [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()]} + | {<span style="color: #FF6600">partial_chain</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(([<span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()]) <span style="color: #990000">-></span> {<span style="color: #FF6600">trusted_ca</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()} | <span style="color: #FF6600">unknown_ca</span>)} + | {<span style="color: #FF6600">password</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">psk_identity</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">reuse_session</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>()} + | {<span style="color: #FF6600">reuse_sessions</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">secure_renegotiate</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">sni_fun</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>()} + | {<span style="color: #FF6600">sni_hosts</span>, [{<span style="font-weight: bold"><span style="color: #000000">string</span></span>(), <span style="font-weight: bold"><span style="color: #000000">ssl_opt</span></span>()}]} + | {<span style="color: #FF6600">user_lookup_fun</span>, {<span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(), <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}} + | {<span style="color: #FF6600">verify</span>, <span style="font-weight: bold"><span style="color: #000000">ssl:verify_type</span></span>()} + | {<span style="color: #FF6600">verify_fun</span>, {<span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(), <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}} + | {<span style="color: #FF6600">versions</span>, [<span style="font-weight: bold"><span style="color: #000080">atom</span></span>()]}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>SSL-specific listen options.</p></div> +</div> +<div class="sect2"> +<h3 id="_opt_ranch_tcp_opt_ssl_opt">opt() = ranch_tcp:opt() | ssl_opt()</h3> +<div class="paragraph"><p>Listen options.</p></div> +</div> +<div class="sect2"> +<h3 id="_opts_opt">opts() = [opt()]</h3> +<div class="paragraph"><p>List of listen options.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_option_descriptions">Option descriptions</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Specifying a certificate is mandatory, either through the <code>cert</code> +or the <code>certfile</code> option. None of the other options are required.</p></div> +<div class="paragraph"><p>The default value is given next to the option name.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +alpn_preferred_protocols +</dt> +<dd> +<p> + Perform Application-Layer Protocol Negotiation with the given list of preferred protocols. +</p> +</dd> +<dt class="hdlist1"> +cacertfile +</dt> +<dd> +<p> + Path to PEM encoded trusted certificates file used to verify peer certificates. +</p> +</dd> +<dt class="hdlist1"> +cacerts +</dt> +<dd> +<p> + List of DER encoded trusted certificates. +</p> +</dd> +<dt class="hdlist1"> +cert +</dt> +<dd> +<p> + DER encoded user certificate. +</p> +</dd> +<dt class="hdlist1"> +certfile +</dt> +<dd> +<p> + Path to the PEM encoded user certificate file. May also contain the private key. +</p> +</dd> +<dt class="hdlist1"> +ciphers +</dt> +<dd> +<p> + List of ciphers that clients are allowed to use. +</p> +</dd> +<dt class="hdlist1"> +client_renegotiation (true) +</dt> +<dd> +<p> + Whether to allow client-initiated renegotiation. +</p> +</dd> +<dt class="hdlist1"> +crl_cache ({ssl_crl_cache, {internal, []}}) +</dt> +<dd> +<p> + Customize the module used to cache Certificate Revocation Lists. +</p> +</dd> +<dt class="hdlist1"> +crl_check (false) +</dt> +<dd> +<p> + Whether to perform CRL check on all certificates in the chain during validation. +</p> +</dd> +<dt class="hdlist1"> +depth (1) +</dt> +<dd> +<p> + Maximum of intermediate certificates allowed in the certification path. +</p> +</dd> +<dt class="hdlist1"> +dh +</dt> +<dd> +<p> + DER encoded Diffie-Hellman parameters. +</p> +</dd> +<dt class="hdlist1"> +dhfile +</dt> +<dd> +<p> + Path to the PEM encoded Diffie-Hellman parameters file. +</p> +</dd> +<dt class="hdlist1"> +fail_if_no_peer_cert (false) +</dt> +<dd> +<p> + Whether to refuse the connection if the client sends an empty certificate. +</p> +</dd> +<dt class="hdlist1"> +hibernate_after (undefined) +</dt> +<dd> +<p> + Time in ms after which SSL socket processes go into hibernation to reduce memory usage. +</p> +</dd> +<dt class="hdlist1"> +honor_cipher_order (false) +</dt> +<dd> +<p> + If true, use the server’s preference for cipher selection. If false, use the client’s preference. +</p> +</dd> +<dt class="hdlist1"> +key +</dt> +<dd> +<p> + DER encoded user private key. +</p> +</dd> +<dt class="hdlist1"> +keyfile +</dt> +<dd> +<p> + Path to the PEM encoded private key file, if different than the certfile. +</p> +</dd> +<dt class="hdlist1"> +log_alert (true) +</dt> +<dd> +<p> + If false, error reports will not be displayed. +</p> +</dd> +<dt class="hdlist1"> +next_protocols_advertised +</dt> +<dd> +<p> + List of protocols to send to the client if it supports the Next Protocol extension. +</p> +</dd> +<dt class="hdlist1"> +nodelay (true) +</dt> +<dd> +<p> + Whether to enable TCP_NODELAY. +</p> +</dd> +<dt class="hdlist1"> +partial_chain +</dt> +<dd> +<p> + Claim an intermediate CA in the chain as trusted. +</p> +</dd> +<dt class="hdlist1"> +password +</dt> +<dd> +<p> + Password to the private key file, if password protected. +</p> +</dd> +<dt class="hdlist1"> +psk_identity +</dt> +<dd> +<p> + Provide the given PSK identity hint to the client during the handshake. +</p> +</dd> +<dt class="hdlist1"> +reuse_session +</dt> +<dd> +<p> + Custom policy to decide whether a session should be reused. +</p> +</dd> +<dt class="hdlist1"> +reuse_sessions (false) +</dt> +<dd> +<p> + Whether to allow session reuse. +</p> +</dd> +<dt class="hdlist1"> +secure_renegotiate (false) +</dt> +<dd> +<p> + Whether to reject renegotiation attempts that do not conform to RFC5746. +</p> +</dd> +<dt class="hdlist1"> +sni_fun +</dt> +<dd> +<p> + Function called when the client requests a host using Server Name Indication. Returns options to apply. +</p> +</dd> +<dt class="hdlist1"> +sni_hosts +</dt> +<dd> +<p> + Options to apply for the host that matches what the client requested with Server Name Indication. +</p> +</dd> +<dt class="hdlist1"> +user_lookup_fun +</dt> +<dd> +<p> + Function called to determine the shared secret when using PSK, or provide parameters when using SRP. +</p> +</dd> +<dt class="hdlist1"> +verify (verify_none) +</dt> +<dd> +<p> + Use <code>verify_peer</code> to request a certificate from the client. +</p> +</dd> +<dt class="hdlist1"> +verify_fun +</dt> +<dd> +<p> + Custom policy to decide whether a client certificate is valid. +</p> +</dd> +<dt class="hdlist1"> +versions +</dt> +<dd> +<p> + TLS protocol versions that will be supported. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Note that the client will not send a certificate unless the +value for the <code>verify</code> option is set to <code>verify_peer</code>. This +means that the <code>fail_if_no_peer_cert</code> only apply when combined +with the <code>verify</code> option. The <code>verify_fun</code> option allows +greater control over the client certificate validation.</p></div> +<div class="paragraph"><p>The options <code>sni_fun</code> and <code>sni_hosts</code> are mutually exclusive.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="paragraph"><p>None.</p></div> +</div> +</div> diff --git a/docs/en/ranch/1.2/manual/ranch_tcp/index.html b/docs/en/ranch/1.2/manual/ranch_tcp/index.html index 120010a5..989da87d 100644 --- a/docs/en/ranch/1.2/manual/ranch_tcp/index.html +++ b/docs/en/ranch/1.2/manual/ranch_tcp/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch_tcp(3)</title> @@ -67,274 +67,274 @@ <h1 class="lined-header"><span>ranch_tcp(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>ranch_tcp - TCP transport module</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>ranch_tcp</code> module implements a TCP Ranch transport.</p></div>
-<div class="paragraph"><p>Note that due to bugs in OTP up to at least R16B02, it is
-recommended to disable async threads when using the
-<code>sendfile</code> function of this transport, as it can make
-the threads stuck indefinitely.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_opt">opt()</h3>
-<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">opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">backlog</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">buffer</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">delay_send</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">dontroute</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">exit_on_close</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">fd</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">high_msgq_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">high_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | <span style="color: #FF6600">inet</span>
- | <span style="color: #FF6600">inet6</span>
- | {<span style="color: #FF6600">ip</span>, <span style="font-weight: bold"><span style="color: #000000">inet:ip_address</span></span>()}
- | {<span style="color: #FF6600">keepalive</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">linger</span>, {<span style="font-weight: bold"><span style="color: #000000">boolean</span></span>(), <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}}
- | {<span style="color: #FF6600">low_msgq_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">low_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">nodelay</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">port</span>, <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>()}
- | {<span style="font-weight: bold"><span style="color: #000080">priority</span></span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>()}
- | {<span style="color: #FF6600">raw</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}
- | {<span style="color: #FF6600">recbuf</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">send_timeout</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()}
- | {<span style="color: #FF6600">send_timeout_close</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">sndbuf</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">tos</span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>Listen options.</p></div>
-<div class="paragraph"><p>This does not represent the entirety of the options that can
-be set on the socket, but only the options that may be
-set independently of protocol implementation.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_opts_opt">opts() = [opt()]</h3>
-<div class="paragraph"><p>List of listen options.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_option_descriptions">Option descriptions</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>None of the options are required.</p></div>
-<div class="paragraph"><p>Please consult the <code>gen_tcp</code> and <code>inet</code> manuals for a more
-thorough description of these options. This manual only aims
-to provide a short description along with what the defaults
-are. Defaults may be different in Ranch compared to <code>gen_tcp</code>.
-Defaults are given next to the option name.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-backlog (1024)
-</dt>
-<dd>
-<p>
- Max length of the queue of pending connections.
-</p>
-</dd>
-<dt class="hdlist1">
-buffer
-</dt>
-<dd>
-<p>
- Size of the buffer used by the Erlang driver. Default is system-dependent.
-</p>
-</dd>
-<dt class="hdlist1">
-delay_send (false)
-</dt>
-<dd>
-<p>
- Always queue packets before sending, to send fewer, larger packets over the network.
-</p>
-</dd>
-<dt class="hdlist1">
-dontroute (false)
-</dt>
-<dd>
-<p>
- Don’t send via a gateway, only send to directly connected hosts.
-</p>
-</dd>
-<dt class="hdlist1">
-exit_on_close (true)
-</dt>
-<dd>
-<p>
- Disable to allow sending data after a close has been detected.
-</p>
-</dd>
-<dt class="hdlist1">
-fd
-</dt>
-<dd>
-<p>
- File descriptor of the socket, if it was opened externally.
-</p>
-</dd>
-<dt class="hdlist1">
-high_msgq_watermark (8192)
-</dt>
-<dd>
-<p>
- Limit in the amount of data in the socket message queue before the socket queue becomes busy.
-</p>
-</dd>
-<dt class="hdlist1">
-high_watermark (8192)
-</dt>
-<dd>
-<p>
- Limit in the amount of data in the ERTS socket implementation’s queue before the socket becomes busy.
-</p>
-</dd>
-<dt class="hdlist1">
-inet
-</dt>
-<dd>
-<p>
- Set up the socket for IPv4.
-</p>
-</dd>
-<dt class="hdlist1">
-inet6
-</dt>
-<dd>
-<p>
- Set up the socket for IPv6.
-</p>
-</dd>
-<dt class="hdlist1">
-ip
-</dt>
-<dd>
-<p>
- Interface to listen on. Listen on all interfaces by default.
-</p>
-</dd>
-<dt class="hdlist1">
-keepalive (false)
-</dt>
-<dd>
-<p>
- Enable sending of keep-alive messages.
-</p>
-</dd>
-<dt class="hdlist1">
-linger ({false, 0})
-</dt>
-<dd>
-<p>
- Whether to wait and how long to flush data sent before closing the socket.
-</p>
-</dd>
-<dt class="hdlist1">
-low_msgq_watermark (4096)
-</dt>
-<dd>
-<p>
- Amount of data in the socket message queue before the socket queue leaves busy state.
-</p>
-</dd>
-<dt class="hdlist1">
-low_watermark (4096)
-</dt>
-<dd>
-<p>
- Amount of data in the ERTS socket implementation’s queue before the socket leaves busy state.
-</p>
-</dd>
-<dt class="hdlist1">
-nodelay (true)
-</dt>
-<dd>
-<p>
- Whether to enable TCP_NODELAY.
-</p>
-</dd>
-<dt class="hdlist1">
-port (0)
-</dt>
-<dd>
-<p>
- TCP port number to listen on. 0 means a random port will be used.
-</p>
-</dd>
-<dt class="hdlist1">
-priority (0)
-</dt>
-<dd>
-<p>
- Priority value for all packets to be sent by this socket.
-</p>
-</dd>
-<dt class="hdlist1">
-recbuf
-</dt>
-<dd>
-<p>
- Minimum size of the socket’s receive buffer. Default is system-dependent.
-</p>
-</dd>
-<dt class="hdlist1">
-send_timeout (30000)
-</dt>
-<dd>
-<p>
- How long the send call may wait for confirmation before returning.
-</p>
-</dd>
-<dt class="hdlist1">
-send_timeout_close (true)
-</dt>
-<dd>
-<p>
- Whether to close the socket when the confirmation wasn’t received.
-</p>
-</dd>
-<dt class="hdlist1">
-sndbuf
-</dt>
-<dd>
-<p>
- Minimum size of the socket’s send buffer. Default is system-dependent.
-</p>
-</dd>
-<dt class="hdlist1">
-tos
-</dt>
-<dd>
-<p>
- Value for the IP_TOS IP level option. Use with caution.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>In addition, the <code>raw</code> option can be used to set system-specific
-options by specifying the protocol level, the option number and
-the actual option value specified as a binary. This option is not
-portable. Use with caution.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exports">Exports</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>None.</p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch_tcp - TCP transport module</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch_tcp</code> module implements a TCP Ranch transport.</p></div> +<div class="paragraph"><p>Note that due to bugs in OTP up to at least R16B02, it is +recommended to disable async threads when using the +<code>sendfile</code> function of this transport, as it can make +the threads stuck indefinitely.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_opt">opt()</h3> +<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">opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">backlog</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">buffer</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">delay_send</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">dontroute</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">exit_on_close</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">fd</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">high_msgq_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">high_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | <span style="color: #FF6600">inet</span> + | <span style="color: #FF6600">inet6</span> + | {<span style="color: #FF6600">ip</span>, <span style="font-weight: bold"><span style="color: #000000">inet:ip_address</span></span>()} + | {<span style="color: #FF6600">keepalive</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">linger</span>, {<span style="font-weight: bold"><span style="color: #000000">boolean</span></span>(), <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}} + | {<span style="color: #FF6600">low_msgq_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">low_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">nodelay</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">port</span>, <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>()} + | {<span style="font-weight: bold"><span style="color: #000080">priority</span></span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>()} + | {<span style="color: #FF6600">raw</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()} + | {<span style="color: #FF6600">recbuf</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">send_timeout</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()} + | {<span style="color: #FF6600">send_timeout_close</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">sndbuf</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">tos</span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Listen options.</p></div> +<div class="paragraph"><p>This does not represent the entirety of the options that can +be set on the socket, but only the options that may be +set independently of protocol implementation.</p></div> +</div> +<div class="sect2"> +<h3 id="_opts_opt">opts() = [opt()]</h3> +<div class="paragraph"><p>List of listen options.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_option_descriptions">Option descriptions</h2> +<div class="sectionbody"> +<div class="paragraph"><p>None of the options are required.</p></div> +<div class="paragraph"><p>Please consult the <code>gen_tcp</code> and <code>inet</code> manuals for a more +thorough description of these options. This manual only aims +to provide a short description along with what the defaults +are. Defaults may be different in Ranch compared to <code>gen_tcp</code>. +Defaults are given next to the option name.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +backlog (1024) +</dt> +<dd> +<p> + Max length of the queue of pending connections. +</p> +</dd> +<dt class="hdlist1"> +buffer +</dt> +<dd> +<p> + Size of the buffer used by the Erlang driver. Default is system-dependent. +</p> +</dd> +<dt class="hdlist1"> +delay_send (false) +</dt> +<dd> +<p> + Always queue packets before sending, to send fewer, larger packets over the network. +</p> +</dd> +<dt class="hdlist1"> +dontroute (false) +</dt> +<dd> +<p> + Don’t send via a gateway, only send to directly connected hosts. +</p> +</dd> +<dt class="hdlist1"> +exit_on_close (true) +</dt> +<dd> +<p> + Disable to allow sending data after a close has been detected. +</p> +</dd> +<dt class="hdlist1"> +fd +</dt> +<dd> +<p> + File descriptor of the socket, if it was opened externally. +</p> +</dd> +<dt class="hdlist1"> +high_msgq_watermark (8192) +</dt> +<dd> +<p> + Limit in the amount of data in the socket message queue before the socket queue becomes busy. +</p> +</dd> +<dt class="hdlist1"> +high_watermark (8192) +</dt> +<dd> +<p> + Limit in the amount of data in the ERTS socket implementation’s queue before the socket becomes busy. +</p> +</dd> +<dt class="hdlist1"> +inet +</dt> +<dd> +<p> + Set up the socket for IPv4. +</p> +</dd> +<dt class="hdlist1"> +inet6 +</dt> +<dd> +<p> + Set up the socket for IPv6. +</p> +</dd> +<dt class="hdlist1"> +ip +</dt> +<dd> +<p> + Interface to listen on. Listen on all interfaces by default. +</p> +</dd> +<dt class="hdlist1"> +keepalive (false) +</dt> +<dd> +<p> + Enable sending of keep-alive messages. +</p> +</dd> +<dt class="hdlist1"> +linger ({false, 0}) +</dt> +<dd> +<p> + Whether to wait and how long to flush data sent before closing the socket. +</p> +</dd> +<dt class="hdlist1"> +low_msgq_watermark (4096) +</dt> +<dd> +<p> + Amount of data in the socket message queue before the socket queue leaves busy state. +</p> +</dd> +<dt class="hdlist1"> +low_watermark (4096) +</dt> +<dd> +<p> + Amount of data in the ERTS socket implementation’s queue before the socket leaves busy state. +</p> +</dd> +<dt class="hdlist1"> +nodelay (true) +</dt> +<dd> +<p> + Whether to enable TCP_NODELAY. +</p> +</dd> +<dt class="hdlist1"> +port (0) +</dt> +<dd> +<p> + TCP port number to listen on. 0 means a random port will be used. +</p> +</dd> +<dt class="hdlist1"> +priority (0) +</dt> +<dd> +<p> + Priority value for all packets to be sent by this socket. +</p> +</dd> +<dt class="hdlist1"> +recbuf +</dt> +<dd> +<p> + Minimum size of the socket’s receive buffer. Default is system-dependent. +</p> +</dd> +<dt class="hdlist1"> +send_timeout (30000) +</dt> +<dd> +<p> + How long the send call may wait for confirmation before returning. +</p> +</dd> +<dt class="hdlist1"> +send_timeout_close (true) +</dt> +<dd> +<p> + Whether to close the socket when the confirmation wasn’t received. +</p> +</dd> +<dt class="hdlist1"> +sndbuf +</dt> +<dd> +<p> + Minimum size of the socket’s send buffer. Default is system-dependent. +</p> +</dd> +<dt class="hdlist1"> +tos +</dt> +<dd> +<p> + Value for the IP_TOS IP level option. Use with caution. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>In addition, the <code>raw</code> option can be used to set system-specific +options by specifying the protocol level, the option number and +the actual option value specified as a binary. This option is not +portable. Use with caution.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="paragraph"><p>None.</p></div> +</div> +</div> diff --git a/docs/en/ranch/1.2/manual/ranch_transport/index.html b/docs/en/ranch/1.2/manual/ranch_transport/index.html index a9e1ac4f..fcd30741 100644 --- a/docs/en/ranch/1.2/manual/ranch_transport/index.html +++ b/docs/en/ranch/1.2/manual/ranch_transport/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch_transport(3)</title> @@ -67,494 +67,494 @@ <h1 class="lined-header"><span>ranch_transport(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>ranch_transport - behaviour for transport modules</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>ranch_transport</code> behaviour defines the interface used
-by Ranch transports.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_sendfile_opts_chunk_size_non_neg_integer">sendfile_opts() = [{chunk_size, non_neg_integer()}]</h3>
-<div class="paragraph"><p>Options used by the sendfile function and callbacks.</p></div>
-<div class="paragraph"><p>Allows configuring the chunk size, in bytes. Defaults to 8191 bytes.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_callbacks">Callbacks</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_accept_lsocket_timeout_8594_ok_csocket_error_closed_timeout_atom">accept(LSocket, Timeout) → {ok, CSocket} | {error, closed | timeout | atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-LSocket = CSocket = any()
-</dt>
-<dd>
-<p>
-Listening socket.
-</p>
-</dd>
-<dt class="hdlist1">
-Timeout = timeout()
-</dt>
-<dd>
-<p>
-Accept timeout.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Accept a connection on the given listening socket.</p></div>
-<div class="paragraph"><p>The <code>accept_ack</code> callback will be used to initialize the socket
-after accepting the connection. This is most useful when the
-transport is not raw TCP, like with SSL for example.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_accept_ack_csocket_timeout_8594_ok">accept_ack(CSocket, Timeout) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-Timeout = timeout()
-</dt>
-<dd>
-<p>
-Ack timeout.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Perform post-accept initialization of the connection.</p></div>
-<div class="paragraph"><p>This function will be called by connection processes
-before performing any socket operation. It allows
-transports that require extra initialization to perform
-their task and make the socket ready to use.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_close_socket_8594_ok">close(Socket) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Socket = any()
-</dt>
-<dd>
-<p>
-Socket opened with listen/1 or accept/2.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Close the given socket.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_controlling_process_socket_pid_8594_ok_error_closed_not_owner_atom">controlling_process(Socket, Pid) → ok | {error, closed | not_owner | atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Socket = any()
-</dt>
-<dd>
-<p>
-Socket opened with listen/1 or accept/2.
-</p>
-</dd>
-<dt class="hdlist1">
-Pid = pid()
-</dt>
-<dd>
-<p>
-Pid of the new owner of the socket.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Change the controlling process for the given socket.</p></div>
-<div class="paragraph"><p>The controlling process is the process that is allowed to
-perform operations on the socket, and that will receive
-messages from the socket when active mode is used. When
-the controlling process dies, the socket is closed.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_listen_transopts_8594_ok_lsocket_error_atom">listen(TransOpts) → {ok, LSocket} | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-TransOpts = any()
-</dt>
-<dd>
-<p>
-Transport options.
-</p>
-</dd>
-<dt class="hdlist1">
-LSocket = any()
-</dt>
-<dd>
-<p>
-Listening socket.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Listen for connections on the given port.</p></div>
-<div class="paragraph"><p>The port is given as part of the transport options under
-the key <code>port</code>. Any other option is transport dependent.</p></div>
-<div class="paragraph"><p>The socket returned by this call can then be used to
-accept connections. It is not possible to send or receive
-data from the listening socket.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_messages_8594_ok_closed_error">messages() → {OK, Closed, Error}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-OK = Closed = Error = atom()
-</dt>
-<dd>
-<p>
-Tuple names.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the atoms used to identify messages sent in active mode.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_name_8594_name">name() → Name</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name = atom()
-</dt>
-<dd>
-<p>
-Transport module name.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the name of the transport.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_peername_csocket_8594_ok_ip_port_error_atom">peername(CSocket) → {ok, {IP, Port}} | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-IP = inet:ip_address()
-</dt>
-<dd>
-<p>
-IP of the remote endpoint.
-</p>
-</dd>
-<dt class="hdlist1">
-Port = inet:port_number()
-</dt>
-<dd>
-<p>
-Port of the remote endpoint.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the IP and port of the remote endpoint.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_recv_csocket_length_timeout_8594_ok_packet_error_closed_timeout_atom">recv(CSocket, Length, Timeout) → {ok, Packet} | {error, closed | timeout | atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-Length = non_neg_integer()
-</dt>
-<dd>
-<p>
-Requested length.
-</p>
-</dd>
-<dt class="hdlist1">
-Timeout = timeout()
-</dt>
-<dd>
-<p>
-Receive timeout.
-</p>
-</dd>
-<dt class="hdlist1">
-Packet = iodata() | any()
-</dt>
-<dd>
-<p>
-Data received.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Receive data from the given socket when in passive mode.</p></div>
-<div class="paragraph"><p>Trying to receive data from a socket that is in active mode
-will return an error.</p></div>
-<div class="paragraph"><p>A length of 0 will return any data available on the socket.</p></div>
-<div class="paragraph"><p>While it is possible to use the timeout value <code>infinity</code>,
-this is highly discouraged as this could cause your process
-to get stuck waiting for data that will never come. This may
-happen when a socket becomes half-open due to a crash of the
-remote endpoint. Wi-Fi going down is another common culprit
-of this issue.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_send_csocket_packet_8594_ok_error_atom">send(CSocket, Packet) → ok | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-Packet = iodata()
-</dt>
-<dd>
-<p>
-Data to be sent.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Send data to the given socket.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_sendfile_csocket_file_8594_sendfile_csocket_file_0_0">sendfile(CSocket, File) → sendfile(CSocket, File, 0, 0, [])</h3>
-<div class="paragraph"><p>Alias of <code>ranch_transport:sendfile/5</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_sendfile_csocket_file_offset_bytes_8594_sendfile_csocket_file_offset_bytes">sendfile(CSocket, File, Offset, Bytes) → sendfile(CSocket, File, Offset, Bytes, [])</h3>
-<div class="paragraph"><p>Alias of <code>ranch_transport:sendfile/5</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_sendfile_csocket_file_offset_bytes_sfopts_8594_ok_sentbytes_error_atom">sendfile(CSocket, File, Offset, Bytes, SfOpts) → {ok, SentBytes} | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-File = file:filename_all() | file:fd()
-</dt>
-<dd>
-<p>
-Filename or file descriptor for the file to be sent.
-</p>
-</dd>
-<dt class="hdlist1">
-Offset = non_neg_integer()
-</dt>
-<dd>
-<p>
-Begin sending at this position in the file.
-</p>
-</dd>
-<dt class="hdlist1">
-Bytes = non_neg_integer()
-</dt>
-<dd>
-<p>
-Send this many bytes.
-</p>
-</dd>
-<dt class="hdlist1">
-SentBytes = non_neg_integer()
-</dt>
-<dd>
-<p>
-This many bytes were sent.
-</p>
-</dd>
-<dt class="hdlist1">
-SfOpts = sendfile_opts()
-</dt>
-<dd>
-<p>
-Sendfile options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Send data from a file to the given socket.</p></div>
-<div class="paragraph"><p>The file may be sent full or in parts, and may be specified
-by its filename or by an already open file descriptor.</p></div>
-<div class="paragraph"><p>Transports that manipulate TCP directly may use the
-<code>file:sendfile/{2,4,5}</code> function, which calls the sendfile
-syscall where applicable (on Linux, for example). Other
-transports can use the <code>sendfile/6</code> function exported from
-this module.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_setopts_csocket_sockopts_8594_ok_error_atom">setopts(CSocket, SockOpts) → ok | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-SockOpts = any()
-</dt>
-<dd>
-<p>
-Socket options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Change options for the given socket.</p></div>
-<div class="paragraph"><p>This is mainly useful for switching to active or passive mode
-or to set protocol-specific options.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_shutdown_csocket_how_8594_ok_error_atom">shutdown(CSocket, How) → ok | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-How = read | write | read_write
-</dt>
-<dd>
-<p>
-Which side(s) of the socket to close.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Immediately close the socket in one or two directions.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_sockname_socket_8594_ok_ip_port_error_atom">sockname(Socket) → {ok, {IP, Port}} | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Socket = any()
-</dt>
-<dd>
-<p>
-Socket opened with listen/1 or accept/2.
-</p>
-</dd>
-<dt class="hdlist1">
-IP = inet:ip_address()
-</dt>
-<dd>
-<p>
-IP of the local endpoint.
-</p>
-</dd>
-<dt class="hdlist1">
-Port = inet:port_number()
-</dt>
-<dd>
-<p>
-Port of the local endpoint.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the IP and port of the local endpoint.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exports">Exports</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_sendfile_transport_csocket_file_offset_bytes_sfopts_8594_ok_sentbytes_error_atom">sendfile(Transport, CSocket, File, Offset, Bytes, SfOpts) → {ok, SentBytes} | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Transport = module()
-</dt>
-<dd>
-<p>
-Transport module for this socket.
-</p>
-</dd>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-File = file:filename_all() | file:fd()
-</dt>
-<dd>
-<p>
-Filename or file descriptor for the file to be sent.
-</p>
-</dd>
-<dt class="hdlist1">
-Offset = non_neg_integer()
-</dt>
-<dd>
-<p>
-Begin sending at this position in the file.
-</p>
-</dd>
-<dt class="hdlist1">
-Bytes = non_neg_integer()
-</dt>
-<dd>
-<p>
-Send this many bytes.
-</p>
-</dd>
-<dt class="hdlist1">
-SentBytes = non_neg_integer()
-</dt>
-<dd>
-<p>
-This many bytes were sent.
-</p>
-</dd>
-<dt class="hdlist1">
-SfOpts = sendfile_opts()
-</dt>
-<dd>
-<p>
-Sendfile options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Send data from a file to the given socket.</p></div>
-<div class="paragraph"><p>This function emulates the function <code>file:sendfile/{2,4,5}</code>
-and may be used when transports are not manipulating TCP
-directly.</p></div>
-</div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch_transport - behaviour for transport modules</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch_transport</code> behaviour defines the interface used +by Ranch transports.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_sendfile_opts_chunk_size_non_neg_integer">sendfile_opts() = [{chunk_size, non_neg_integer()}]</h3> +<div class="paragraph"><p>Options used by the sendfile function and callbacks.</p></div> +<div class="paragraph"><p>Allows configuring the chunk size, in bytes. Defaults to 8191 bytes.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_callbacks">Callbacks</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_accept_lsocket_timeout_8594_ok_csocket_error_closed_timeout_atom">accept(LSocket, Timeout) → {ok, CSocket} | {error, closed | timeout | atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +LSocket = CSocket = any() +</dt> +<dd> +<p> +Listening socket. +</p> +</dd> +<dt class="hdlist1"> +Timeout = timeout() +</dt> +<dd> +<p> +Accept timeout. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Accept a connection on the given listening socket.</p></div> +<div class="paragraph"><p>The <code>accept_ack</code> callback will be used to initialize the socket +after accepting the connection. This is most useful when the +transport is not raw TCP, like with SSL for example.</p></div> +</div> +<div class="sect2"> +<h3 id="_accept_ack_csocket_timeout_8594_ok">accept_ack(CSocket, Timeout) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +Timeout = timeout() +</dt> +<dd> +<p> +Ack timeout. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Perform post-accept initialization of the connection.</p></div> +<div class="paragraph"><p>This function will be called by connection processes +before performing any socket operation. It allows +transports that require extra initialization to perform +their task and make the socket ready to use.</p></div> +</div> +<div class="sect2"> +<h3 id="_close_socket_8594_ok">close(Socket) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Socket = any() +</dt> +<dd> +<p> +Socket opened with listen/1 or accept/2. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Close the given socket.</p></div> +</div> +<div class="sect2"> +<h3 id="_controlling_process_socket_pid_8594_ok_error_closed_not_owner_atom">controlling_process(Socket, Pid) → ok | {error, closed | not_owner | atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Socket = any() +</dt> +<dd> +<p> +Socket opened with listen/1 or accept/2. +</p> +</dd> +<dt class="hdlist1"> +Pid = pid() +</dt> +<dd> +<p> +Pid of the new owner of the socket. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Change the controlling process for the given socket.</p></div> +<div class="paragraph"><p>The controlling process is the process that is allowed to +perform operations on the socket, and that will receive +messages from the socket when active mode is used. When +the controlling process dies, the socket is closed.</p></div> +</div> +<div class="sect2"> +<h3 id="_listen_transopts_8594_ok_lsocket_error_atom">listen(TransOpts) → {ok, LSocket} | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +TransOpts = any() +</dt> +<dd> +<p> +Transport options. +</p> +</dd> +<dt class="hdlist1"> +LSocket = any() +</dt> +<dd> +<p> +Listening socket. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Listen for connections on the given port.</p></div> +<div class="paragraph"><p>The port is given as part of the transport options under +the key <code>port</code>. Any other option is transport dependent.</p></div> +<div class="paragraph"><p>The socket returned by this call can then be used to +accept connections. It is not possible to send or receive +data from the listening socket.</p></div> +</div> +<div class="sect2"> +<h3 id="_messages_8594_ok_closed_error">messages() → {OK, Closed, Error}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +OK = Closed = Error = atom() +</dt> +<dd> +<p> +Tuple names. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the atoms used to identify messages sent in active mode.</p></div> +</div> +<div class="sect2"> +<h3 id="_name_8594_name">name() → Name</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name = atom() +</dt> +<dd> +<p> +Transport module name. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the name of the transport.</p></div> +</div> +<div class="sect2"> +<h3 id="_peername_csocket_8594_ok_ip_port_error_atom">peername(CSocket) → {ok, {IP, Port}} | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +IP = inet:ip_address() +</dt> +<dd> +<p> +IP of the remote endpoint. +</p> +</dd> +<dt class="hdlist1"> +Port = inet:port_number() +</dt> +<dd> +<p> +Port of the remote endpoint. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the IP and port of the remote endpoint.</p></div> +</div> +<div class="sect2"> +<h3 id="_recv_csocket_length_timeout_8594_ok_packet_error_closed_timeout_atom">recv(CSocket, Length, Timeout) → {ok, Packet} | {error, closed | timeout | atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +Length = non_neg_integer() +</dt> +<dd> +<p> +Requested length. +</p> +</dd> +<dt class="hdlist1"> +Timeout = timeout() +</dt> +<dd> +<p> +Receive timeout. +</p> +</dd> +<dt class="hdlist1"> +Packet = iodata() | any() +</dt> +<dd> +<p> +Data received. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Receive data from the given socket when in passive mode.</p></div> +<div class="paragraph"><p>Trying to receive data from a socket that is in active mode +will return an error.</p></div> +<div class="paragraph"><p>A length of 0 will return any data available on the socket.</p></div> +<div class="paragraph"><p>While it is possible to use the timeout value <code>infinity</code>, +this is highly discouraged as this could cause your process +to get stuck waiting for data that will never come. This may +happen when a socket becomes half-open due to a crash of the +remote endpoint. Wi-Fi going down is another common culprit +of this issue.</p></div> +</div> +<div class="sect2"> +<h3 id="_send_csocket_packet_8594_ok_error_atom">send(CSocket, Packet) → ok | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +Packet = iodata() +</dt> +<dd> +<p> +Data to be sent. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Send data to the given socket.</p></div> +</div> +<div class="sect2"> +<h3 id="_sendfile_csocket_file_8594_sendfile_csocket_file_0_0">sendfile(CSocket, File) → sendfile(CSocket, File, 0, 0, [])</h3> +<div class="paragraph"><p>Alias of <code>ranch_transport:sendfile/5</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_sendfile_csocket_file_offset_bytes_8594_sendfile_csocket_file_offset_bytes">sendfile(CSocket, File, Offset, Bytes) → sendfile(CSocket, File, Offset, Bytes, [])</h3> +<div class="paragraph"><p>Alias of <code>ranch_transport:sendfile/5</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_sendfile_csocket_file_offset_bytes_sfopts_8594_ok_sentbytes_error_atom">sendfile(CSocket, File, Offset, Bytes, SfOpts) → {ok, SentBytes} | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +File = file:filename_all() | file:fd() +</dt> +<dd> +<p> +Filename or file descriptor for the file to be sent. +</p> +</dd> +<dt class="hdlist1"> +Offset = non_neg_integer() +</dt> +<dd> +<p> +Begin sending at this position in the file. +</p> +</dd> +<dt class="hdlist1"> +Bytes = non_neg_integer() +</dt> +<dd> +<p> +Send this many bytes. +</p> +</dd> +<dt class="hdlist1"> +SentBytes = non_neg_integer() +</dt> +<dd> +<p> +This many bytes were sent. +</p> +</dd> +<dt class="hdlist1"> +SfOpts = sendfile_opts() +</dt> +<dd> +<p> +Sendfile options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Send data from a file to the given socket.</p></div> +<div class="paragraph"><p>The file may be sent full or in parts, and may be specified +by its filename or by an already open file descriptor.</p></div> +<div class="paragraph"><p>Transports that manipulate TCP directly may use the +<code>file:sendfile/{2,4,5}</code> function, which calls the sendfile +syscall where applicable (on Linux, for example). Other +transports can use the <code>sendfile/6</code> function exported from +this module.</p></div> +</div> +<div class="sect2"> +<h3 id="_setopts_csocket_sockopts_8594_ok_error_atom">setopts(CSocket, SockOpts) → ok | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +SockOpts = any() +</dt> +<dd> +<p> +Socket options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Change options for the given socket.</p></div> +<div class="paragraph"><p>This is mainly useful for switching to active or passive mode +or to set protocol-specific options.</p></div> +</div> +<div class="sect2"> +<h3 id="_shutdown_csocket_how_8594_ok_error_atom">shutdown(CSocket, How) → ok | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +How = read | write | read_write +</dt> +<dd> +<p> +Which side(s) of the socket to close. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Immediately close the socket in one or two directions.</p></div> +</div> +<div class="sect2"> +<h3 id="_sockname_socket_8594_ok_ip_port_error_atom">sockname(Socket) → {ok, {IP, Port}} | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Socket = any() +</dt> +<dd> +<p> +Socket opened with listen/1 or accept/2. +</p> +</dd> +<dt class="hdlist1"> +IP = inet:ip_address() +</dt> +<dd> +<p> +IP of the local endpoint. +</p> +</dd> +<dt class="hdlist1"> +Port = inet:port_number() +</dt> +<dd> +<p> +Port of the local endpoint. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the IP and port of the local endpoint.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_sendfile_transport_csocket_file_offset_bytes_sfopts_8594_ok_sentbytes_error_atom">sendfile(Transport, CSocket, File, Offset, Bytes, SfOpts) → {ok, SentBytes} | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Transport = module() +</dt> +<dd> +<p> +Transport module for this socket. +</p> +</dd> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +File = file:filename_all() | file:fd() +</dt> +<dd> +<p> +Filename or file descriptor for the file to be sent. +</p> +</dd> +<dt class="hdlist1"> +Offset = non_neg_integer() +</dt> +<dd> +<p> +Begin sending at this position in the file. +</p> +</dd> +<dt class="hdlist1"> +Bytes = non_neg_integer() +</dt> +<dd> +<p> +Send this many bytes. +</p> +</dd> +<dt class="hdlist1"> +SentBytes = non_neg_integer() +</dt> +<dd> +<p> +This many bytes were sent. +</p> +</dd> +<dt class="hdlist1"> +SfOpts = sendfile_opts() +</dt> +<dd> +<p> +Sendfile options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Send data from a file to the given socket.</p></div> +<div class="paragraph"><p>This function emulates the function <code>file:sendfile/{2,4,5}</code> +and may be used when transports are not manipulating TCP +directly.</p></div> +</div> +</div> +</div> diff --git a/docs/en/ranch/1.3/guide/embedded/index.html b/docs/en/ranch/1.3/guide/embedded/index.html index eea4e32b..a1d552af 100644 --- a/docs/en/ranch/1.3/guide/embedded/index.html +++ b/docs/en/ranch/1.3/guide/embedded/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Embedded mode</title> @@ -67,54 +67,57 @@ <h1 class="lined-header"><span>Embedded mode</span></h1> -<div class="paragraph"><p>Embedded mode allows you to insert Ranch listeners directly
-in your supervision tree. This allows for greater fault tolerance
-control by permitting the shutdown of a listener due to the
-failure of another part of the application and vice versa.</p></div>
-<div class="sect1">
-<h2 id="_embedding">Embedding</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To embed Ranch in your application you can simply add the child specs
-to your supervision tree. This can all be done in the <code>init/1</code> function
-of one of your application supervisors.</p></div>
-<div class="paragraph"><p>Ranch requires at the minimum two kinds of child specs for embedding.
-First, you need to add <code>ranch_sup</code> to your supervision tree, only once,
-regardless of the number of listeners you will use. Then you need to
-add the child specs for each listener.</p></div>
-<div class="paragraph"><p>Ranch has a convenience function for getting the listeners child specs
-called <code>ranch:child_spec/5</code>, that works like <code>ranch:start_listener/5</code>,
-except that it doesn’t start anything, it only returns child specs.</p></div>
-<div class="paragraph"><p>As for <code>ranch_sup</code>, the child spec is simple enough to not require a
-convenience function.</p></div>
-<div class="paragraph"><p>The following example adds both <code>ranch_sup</code> and one listener to another
-application’s supervision tree.</p></div>
-<div class="listingblock">
-<div class="title">Embed Ranch directly in your supervision tree</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="font-weight: bold"><span style="color: #000000">init</span></span>([]) <span style="color: #990000">-></span>
- <span style="color: #009900">RanchSupSpec</span> <span style="color: #990000">=</span> {<span style="color: #FF6600">ranch_sup</span>, {<span style="color: #FF6600">ranch_sup</span>, <span style="color: #FF6600">start_link</span>, []},
- <span style="color: #FF6600">permanent</span>, <span style="color: #993399">5000</span>, <span style="color: #FF6600">supervisor</span>, [<span style="color: #FF6600">ranch_sup</span>]},
- <span style="color: #009900">ListenerSpec</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:child_spec</span></span>(<span style="color: #FF6600">echo</span>, <span style="color: #993399">100</span>,
- <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}],
- <span style="color: #FF6600">echo_protocol</span>, []
- ),
- {<span style="color: #FF6600">ok</span>, {{<span style="color: #FF6600">one_for_one</span>, <span style="color: #993399">10</span>, <span style="color: #993399">10</span>}, [<span style="color: #009900">RanchSupSpec</span>, <span style="color: #009900">ListenerSpec</span>]}}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Remember, you can add as many listener child specs as needed, but only
-one <code>ranch_sup</code> spec!</p></div>
-<div class="paragraph"><p>It is recommended that your architecture makes sure that all listeners
-are restarted if <code>ranch_sup</code> fails. See the Ranch internals chapter for
-more details on how Ranch does it.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>Embedded mode allows you to insert Ranch listeners directly +in your supervision tree. This allows for greater fault tolerance +control by permitting the shutdown of a listener due to the +failure of another part of the application and vice versa.</p></div> +<div class="sect1"> +<h2 id="_embedding">Embedding</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To embed Ranch in your application you can simply add the child specs +to your supervision tree. This can all be done in the <code>init/1</code> function +of one of your application supervisors.</p></div> +<div class="paragraph"><p>Ranch requires at the minimum two kinds of child specs for embedding. +First, you need to add <code>ranch_sup</code> to your supervision tree, only once, +regardless of the number of listeners you will use. Then you need to +add the child specs for each listener.</p></div> +<div class="paragraph"><p>Ranch has a convenience function for getting the listeners child specs +called <code>ranch:child_spec/5</code>, that works like <code>ranch:start_listener/5</code>, +except that it doesn’t start anything, it only returns child specs.</p></div> +<div class="paragraph"><p>As for <code>ranch_sup</code>, the child spec is simple enough to not require a +convenience function.</p></div> +<div class="paragraph"><p>The following example adds both <code>ranch_sup</code> and one listener to another +application’s supervision tree.</p></div> +<div class="listingblock"> +<div class="title">Embed Ranch directly in your supervision tree</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="font-weight: bold"><span style="color: #000000">init</span></span>([]) <span style="color: #990000">-></span> + <span style="color: #009900">RanchSupSpec</span> <span style="color: #990000">=</span> {<span style="color: #FF6600">ranch_sup</span>, {<span style="color: #FF6600">ranch_sup</span>, <span style="color: #FF6600">start_link</span>, []}, + <span style="color: #FF6600">permanent</span>, <span style="color: #993399">5000</span>, <span style="color: #FF6600">supervisor</span>, [<span style="color: #FF6600">ranch_sup</span>]}, + <span style="color: #009900">ListenerSpec</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:child_spec</span></span>(<span style="color: #FF6600">echo</span>, <span style="color: #993399">100</span>, + <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}], + <span style="color: #FF6600">echo_protocol</span>, [] + ), + {<span style="color: #FF6600">ok</span>, {{<span style="color: #FF6600">one_for_one</span>, <span style="color: #993399">10</span>, <span style="color: #993399">10</span>}, [<span style="color: #009900">RanchSupSpec</span>, <span style="color: #009900">ListenerSpec</span>]}}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Remember, you can add as many listener child specs as needed, but only +one <code>ranch_sup</code> spec!</p></div> +<div class="paragraph"><p>It is recommended that your architecture makes sure that all listeners +are restarted if <code>ranch_sup</code> fails. See the Ranch internals chapter for +more details on how Ranch does it.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.3/guide/index.html b/docs/en/ranch/1.3/guide/index.html index 11fff995..e9986a13 100644 --- a/docs/en/ranch/1.3/guide/index.html +++ b/docs/en/ranch/1.3/guide/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Ranch User Guide</title> @@ -67,48 +67,48 @@ <h1 class="lined-header"><span>Ranch User Guide</span></h1> -<div class="ulist"><ul>
-<li>
-<p>
-<a href="introduction/">Introduction</a>
-</p>
-</li>
-<li>
-<p>
-<a href="listeners/">Listeners</a>
-</p>
-</li>
-<li>
-<p>
-<a href="transports/">Transports</a>
-</p>
-</li>
-<li>
-<p>
-<a href="protocols/">Protocols</a>
-</p>
-</li>
-<li>
-<p>
-<a href="embedded/">Embedded mode</a>
-</p>
-</li>
-<li>
-<p>
-<a href="parsers/">Writing parsers</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ssl_auth/">SSL client authentication</a>
-</p>
-</li>
-<li>
-<p>
-<a href="internals/">Internals</a>
-</p>
-</li>
-</ul></div>
+<div class="ulist"><ul> +<li> +<p> +<a href="introduction/">Introduction</a> +</p> +</li> +<li> +<p> +<a href="listeners/">Listeners</a> +</p> +</li> +<li> +<p> +<a href="transports/">Transports</a> +</p> +</li> +<li> +<p> +<a href="protocols/">Protocols</a> +</p> +</li> +<li> +<p> +<a href="embedded/">Embedded mode</a> +</p> +</li> +<li> +<p> +<a href="parsers/">Writing parsers</a> +</p> +</li> +<li> +<p> +<a href="ssl_auth/">SSL client authentication</a> +</p> +</li> +<li> +<p> +<a href="internals/">Internals</a> +</p> +</li> +</ul></div> diff --git a/docs/en/ranch/1.3/guide/internals/index.html b/docs/en/ranch/1.3/guide/internals/index.html index 7a08d075..f75bc639 100644 --- a/docs/en/ranch/1.3/guide/internals/index.html +++ b/docs/en/ranch/1.3/guide/internals/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Internals</title> @@ -67,99 +67,102 @@ <h1 class="lined-header"><span>Internals</span></h1> -<div class="paragraph"><p>This chapter may not apply to embedded Ranch as embedding allows you
-to use an architecture specific to your application, which may or may
-not be compatible with the description of the Ranch application.</p></div>
-<div class="paragraph"><p>Note that for everything related to efficiency and performance,
-you should perform the benchmarks yourself to get the numbers that
-matter to you. Generic benchmarks found on the web may or may not
-be of use to you, you can never know until you benchmark your own
-system.</p></div>
-<div class="sect1">
-<h2 id="_architecture">Architecture</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch is an OTP application.</p></div>
-<div class="paragraph"><p>Like all OTP applications, Ranch has a top supervisor. It is responsible
-for supervising the <code>ranch_server</code> process and all the listeners that
-will be started.</p></div>
-<div class="paragraph"><p>The <code>ranch_server</code> gen_server is a central process keeping track of the
-listeners and their acceptors. It does so through the use of a public ets
-table called <code>ranch_server</code>. The table is owned by the top supervisor
-to improve fault tolerance. This way if the <code>ranch_server</code> gen_server
-fails, it doesn’t lose any information and the restarted process can
-continue as if nothing happened.</p></div>
-<div class="paragraph"><p>Ranch uses a custom supervisor for managing connections. This supervisor
-keeps track of the number of connections and handles connection limits
-directly. While it is heavily optimized to perform the task of creating
-connection processes for accepted connections, it is still following the
-OTP principles and the usual <code>sys</code> and <code>supervisor</code> calls will work on
-it as expected.</p></div>
-<div class="paragraph"><p>Listeners are grouped into the <code>ranch_listener_sup</code> supervisor and
-consist of three kinds of processes: the listener gen_server, the
-acceptor processes and the connection processes, both grouped under
-their own supervisor. All of these processes are registered to the
-<code>ranch_server</code> gen_server with varying amount of information.</p></div>
-<div class="paragraph"><p>All socket operations, including listening for connections, go through
-transport handlers. Accepted connections are given to the protocol handler.
-Transport handlers are simple callback modules for performing operations on
-sockets. Protocol handlers start a new process, which receives socket
-ownership, with no requirements on how the code should be written inside
-that new process.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_number_of_acceptors">Number of acceptors</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The second argument to <code>ranch:start_listener/5</code> is the number of
-processes that will be accepting connections. Care should be taken
-when choosing this number.</p></div>
-<div class="paragraph"><p>First of all, it should not be confused with the maximum number
-of connections. Acceptor processes are only used for accepting and
-have nothing else in common with connection processes. Therefore
-there is nothing to be gained from setting this number too high,
-in fact it can slow everything else down.</p></div>
-<div class="paragraph"><p>Second, this number should be high enough to allow Ranch to accept
-connections concurrently. But the number of cores available doesn’t
-seem to be the only factor for choosing this number, as we can
-observe faster accepts if we have more acceptors than cores. It
-might be entirely dependent on the protocol, however.</p></div>
-<div class="paragraph"><p>Our observations suggest that using 100 acceptors on modern hardware
-is a good solution, as it’s big enough to always have acceptors ready
-and it’s low enough that it doesn’t have a negative impact on the
-system’s performances.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_platform_specific_tcp_features">Platform-specific TCP features</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Some socket options are platform-specific and not supported by <code>inet</code>.
-They can be of interest because they generally are related to
-optimizations provided by the underlying OS. They can still be enabled
-thanks to the <code>raw</code> option, for which we will see an example.</p></div>
-<div class="paragraph"><p>One of these features is <code>TCP_DEFER_ACCEPT</code> on Linux. It is a simplified
-accept mechanism which will wait for application data to come in before
-handing out the connection to the Erlang process.</p></div>
-<div class="paragraph"><p>This is especially useful if you expect many connections to be mostly
-idle, perhaps part of a connection pool. They can be handled by the
-kernel directly until they send any real data, instead of allocating
-resources to idle connections.</p></div>
-<div class="paragraph"><p>To enable this mechanism, the following option can be used.</p></div>
-<div class="listingblock">
-<div class="title">Using raw transport options</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: #FF6600">raw</span>, <span style="color: #993399">6</span>, <span style="color: #993399">9</span>, <span style="color: #990000"><<</span> <span style="font-weight: bold"><span style="color: #000000">30:32</span></span><span style="color: #990000">/</span><span style="color: #FF6600">native</span> <span style="color: #990000">>></span>}</tt></pre></div></div>
-<div class="paragraph"><p>It means go on layer 6, turn on option 9 with the given integer parameter.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter may not apply to embedded Ranch as embedding allows you +to use an architecture specific to your application, which may or may +not be compatible with the description of the Ranch application.</p></div> +<div class="paragraph"><p>Note that for everything related to efficiency and performance, +you should perform the benchmarks yourself to get the numbers that +matter to you. Generic benchmarks found on the web may or may not +be of use to you, you can never know until you benchmark your own +system.</p></div> +<div class="sect1"> +<h2 id="_architecture">Architecture</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch is an OTP application.</p></div> +<div class="paragraph"><p>Like all OTP applications, Ranch has a top supervisor. It is responsible +for supervising the <code>ranch_server</code> process and all the listeners that +will be started.</p></div> +<div class="paragraph"><p>The <code>ranch_server</code> gen_server is a central process keeping track of the +listeners and their acceptors. It does so through the use of a public ets +table called <code>ranch_server</code>. The table is owned by the top supervisor +to improve fault tolerance. This way if the <code>ranch_server</code> gen_server +fails, it doesn’t lose any information and the restarted process can +continue as if nothing happened.</p></div> +<div class="paragraph"><p>Ranch uses a custom supervisor for managing connections. This supervisor +keeps track of the number of connections and handles connection limits +directly. While it is heavily optimized to perform the task of creating +connection processes for accepted connections, it is still following the +OTP principles and the usual <code>sys</code> and <code>supervisor</code> calls will work on +it as expected.</p></div> +<div class="paragraph"><p>Listeners are grouped into the <code>ranch_listener_sup</code> supervisor and +consist of three kinds of processes: the listener gen_server, the +acceptor processes and the connection processes, both grouped under +their own supervisor. All of these processes are registered to the +<code>ranch_server</code> gen_server with varying amount of information.</p></div> +<div class="paragraph"><p>All socket operations, including listening for connections, go through +transport handlers. Accepted connections are given to the protocol handler. +Transport handlers are simple callback modules for performing operations on +sockets. Protocol handlers start a new process, which receives socket +ownership, with no requirements on how the code should be written inside +that new process.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_number_of_acceptors">Number of acceptors</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The second argument to <code>ranch:start_listener/5</code> is the number of +processes that will be accepting connections. Care should be taken +when choosing this number.</p></div> +<div class="paragraph"><p>First of all, it should not be confused with the maximum number +of connections. Acceptor processes are only used for accepting and +have nothing else in common with connection processes. Therefore +there is nothing to be gained from setting this number too high, +in fact it can slow everything else down.</p></div> +<div class="paragraph"><p>Second, this number should be high enough to allow Ranch to accept +connections concurrently. But the number of cores available doesn’t +seem to be the only factor for choosing this number, as we can +observe faster accepts if we have more acceptors than cores. It +might be entirely dependent on the protocol, however.</p></div> +<div class="paragraph"><p>Our observations suggest that using 100 acceptors on modern hardware +is a good solution, as it’s big enough to always have acceptors ready +and it’s low enough that it doesn’t have a negative impact on the +system’s performances.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_platform_specific_tcp_features">Platform-specific TCP features</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Some socket options are platform-specific and not supported by <code>inet</code>. +They can be of interest because they generally are related to +optimizations provided by the underlying OS. They can still be enabled +thanks to the <code>raw</code> option, for which we will see an example.</p></div> +<div class="paragraph"><p>One of these features is <code>TCP_DEFER_ACCEPT</code> on Linux. It is a simplified +accept mechanism which will wait for application data to come in before +handing out the connection to the Erlang process.</p></div> +<div class="paragraph"><p>This is especially useful if you expect many connections to be mostly +idle, perhaps part of a connection pool. They can be handled by the +kernel directly until they send any real data, instead of allocating +resources to idle connections.</p></div> +<div class="paragraph"><p>To enable this mechanism, the following option can be used.</p></div> +<div class="listingblock"> +<div class="title">Using raw transport options</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: #FF6600">raw</span>, <span style="color: #993399">6</span>, <span style="color: #993399">9</span>, <span style="color: #990000"><<</span> <span style="font-weight: bold"><span style="color: #000000">30:32</span></span><span style="color: #990000">/</span><span style="color: #FF6600">native</span> <span style="color: #990000">>></span>}</tt></pre></div></div> +<div class="paragraph"><p>It means go on layer 6, turn on option 9 with the given integer parameter.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.3/guide/introduction/index.html b/docs/en/ranch/1.3/guide/introduction/index.html index 8997b000..9c795d8b 100644 --- a/docs/en/ranch/1.3/guide/introduction/index.html +++ b/docs/en/ranch/1.3/guide/introduction/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Introduction</title> @@ -67,40 +67,43 @@ <h1 class="lined-header"><span>Introduction</span></h1> -<div class="paragraph"><p>Ranch is a socket acceptor pool for TCP protocols.</p></div>
-<div class="paragraph"><p>Ranch aims to provide everything you need to accept TCP connections
-with a small code base and low latency while being easy to use directly
-as an application or to embed into your own.</p></div>
-<div class="sect1">
-<h2 id="_prerequisites">Prerequisites</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>It is assumed the developer already knows Erlang and has some experience
-with socket programming and TCP protocols.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_supported_platforms">Supported platforms</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch is tested and supported on Linux, FreeBSD, OSX and Windows.</p></div>
-<div class="paragraph"><p>Ranch is developed for Erlang/OTP R16B+.</p></div>
-<div class="paragraph"><p>There are known issues with the SSL application found in Erlang/OTP
-18.3.2 and 18.3.3. These versions are therefore not supported.</p></div>
-<div class="paragraph"><p>Ranch may be compiled on earlier Erlang versions with small source code
-modifications but there is no guarantee that it will work as expected.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_versioning">Versioning</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch uses <a href="http://semver.org/">Semantic Versioning 2.0.0</a></p></div>
-</div>
-</div>
+<div class="paragraph"><p>Ranch is a socket acceptor pool for TCP protocols.</p></div> +<div class="paragraph"><p>Ranch aims to provide everything you need to accept TCP connections +with a small code base and low latency while being easy to use directly +as an application or to embed into your own.</p></div> +<div class="sect1"> +<h2 id="_prerequisites">Prerequisites</h2> +<div class="sectionbody"> +<div class="paragraph"><p>It is assumed the developer already knows Erlang and has some experience +with socket programming and TCP protocols.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_supported_platforms">Supported platforms</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch is tested and supported on Linux, FreeBSD, OSX and Windows.</p></div> +<div class="paragraph"><p>Ranch is developed for Erlang/OTP R16B+.</p></div> +<div class="paragraph"><p>There are known issues with the SSL application found in Erlang/OTP +18.3.2 and 18.3.3. These versions are therefore not supported.</p></div> +<div class="paragraph"><p>Ranch may be compiled on earlier Erlang versions with small source code +modifications but there is no guarantee that it will work as expected.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_versioning">Versioning</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch uses <a href="http://semver.org/">Semantic Versioning 2.0.0</a></p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.3/guide/listeners/index.html b/docs/en/ranch/1.3/guide/listeners/index.html index 6cc4d0a1..bb7f3310 100644 --- a/docs/en/ranch/1.3/guide/listeners/index.html +++ b/docs/en/ranch/1.3/guide/listeners/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Listeners</title> @@ -67,373 +67,376 @@ <h1 class="lined-header"><span>Listeners</span></h1> -<div class="paragraph"><p>A listener is a set of processes whose role is to listen on a port
-for new connections. It manages a pool of acceptor processes, each
-of them indefinitely accepting connections. When it does, it starts
-a new process executing the protocol handler code. All the socket
-programming is abstracted through the use of transport handlers.</p></div>
-<div class="paragraph"><p>The listener takes care of supervising all the acceptor and connection
-processes, allowing developers to focus on building their application.</p></div>
-<div class="sect1">
-<h2 id="_starting_a_listener">Starting a listener</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch does nothing by default. It is up to the application developer
-to request that Ranch listens for connections.</p></div>
-<div class="paragraph"><p>A listener can be started and stopped at will.</p></div>
-<div class="paragraph"><p>When starting a listener, a number of different settings are required:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-A name to identify it locally and be able to interact with it.
-</p>
-</li>
-<li>
-<p>
-The number of acceptors in the pool.
-</p>
-</li>
-<li>
-<p>
-A transport handler and its associated options.
-</p>
-</li>
-<li>
-<p>
-A protocol handler and its associated options.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Ranch includes both TCP and SSL transport handlers, respectively
-<code>ranch_tcp</code> and <code>ranch_ssl</code>.</p></div>
-<div class="paragraph"><p>A listener can be started by calling the <code>ranch:start_listener/5</code>
-function. Before doing so however, you must ensure that the <code>ranch</code>
-application is started.</p></div>
-<div class="listingblock">
-<div class="title">Starting the Ranch application</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: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">application:start</span></span>(<span style="color: #FF6600">ranch</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You are then ready to start a listener. Let’s call it <code>tcp_echo</code>. It will
-have a pool of 100 acceptors, use a TCP transport and forward connections
-to the <code>echo_protocol</code> handler.</p></div>
-<div class="listingblock">
-<div class="title">Starting a listener for TCP connections on port 5555</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: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>,
- <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}],
- <span style="color: #FF6600">echo_protocol</span>, []
-)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can try this out by compiling and running the <code>tcp_echo</code> example in the
-examples directory. To do so, open a shell in the <em>examples/tcp_echo/</em>
-directory and run the following command:</p></div>
-<div class="listingblock">
-<div class="title">Building and starting a Ranch example</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>$ make run</tt></pre></div></div>
-<div class="paragraph"><p>You can then connect to it using telnet and see the echo server reply
-everything you send to it. Then when you’re done testing, you can use
-the <code>Ctrl+]</code> key to escape to the telnet command line and type
-<code>quit</code> to exit.</p></div>
-<div class="listingblock">
-<div class="title">Connecting to the example listener with telnet</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>$ telnet localhost <span style="color: #993399">5555</span>
-Trying <span style="color: #993399">127.0</span><span style="color: #990000">.</span><span style="color: #993399">0.1</span><span style="color: #990000">...</span>
-Connected to localhost<span style="color: #990000">.</span>
-Escape character is <span style="color: #FF0000">'^]'</span><span style="color: #990000">.</span>
-Hello<span style="color: #990000">!</span>
-Hello<span style="color: #990000">!</span>
-It works<span style="color: #990000">!</span>
-It works<span style="color: #990000">!</span>
-<span style="color: #990000">^]</span>
-
-telnet<span style="color: #990000">></span> quit
-Connection closed<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_stopping_a_listener">Stopping a listener</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>All you need to stop a Ranch listener is to call the
-<code>ranch:stop_listener/1</code> function with the listener’s name
-as argument. In the previous section we started the listener
-named <code>tcp_echo</code>. We can now stop it.</p></div>
-<div class="listingblock">
-<div class="title">Stopping a listener</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="font-weight: bold"><span style="color: #000000">ranch:stop_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_default_transport_options">Default transport options</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>By default the socket will be set to return <code>binary</code> data, with the
-options <code>{active, false}</code>, <code>{packet, raw}</code>, <code>{reuseaddr, true}</code> set.
-These values can’t be overriden when starting the listener, but
-they can be overriden using <code>Transport:setopts/2</code> in the protocol.</p></div>
-<div class="paragraph"><p>It will also set <code>{backlog, 1024}</code> and <code>{nodelay, true}</code>, which
-can be overriden at listener startup.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_listening_on_a_random_port">Listening on a random port</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You do not have to specify a specific port to listen on. If you give
-the port number 0, or if you omit the port number entirely, Ranch will
-start listening on a random port.</p></div>
-<div class="paragraph"><p>You can retrieve this port number by calling <code>ranch:get_port/1</code>. The
-argument is the name of the listener you gave in <code>ranch:start_listener/5</code>.</p></div>
-<div class="listingblock">
-<div class="title">Starting a listener for TCP connections on a random port</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: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>,
- <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">0</span>}],
- <span style="color: #FF6600">echo_protocol</span>, []
-)<span style="color: #990000">.</span>
-<span style="color: #009900">Port</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_port</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_listening_on_privileged_ports">Listening on privileged ports</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Some systems limit access to ports below 1024 for security reasons.
-This can easily be identified by an <code>{error, eacces}</code> error when trying
-to open a listening socket on such a port.</p></div>
-<div class="paragraph"><p>The methods for listening on privileged ports vary between systems,
-please refer to your system’s documentation for more information.</p></div>
-<div class="paragraph"><p>We recommend the use of port rewriting for systems with a single server,
-and load balancing for systems with multiple servers. Documenting these
-solutions is however out of the scope of this guide.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_accepting_connections_on_an_existing_socket">Accepting connections on an existing socket</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>If you want to accept connections on an existing socket, you can use the
-<code>socket</code> transport option, which should just be the relevant data returned
-from the connect function for the transport or the underlying socket library
-(<code>gen_tcp:connect</code>, <code>ssl:connect</code>). The accept function will then be
-called on the passed in socket. You should connect the socket in
-<code>{active, false}</code> mode, as well.</p></div>
-<div class="paragraph"><p>Note, however, that because of a bug in SSL, you cannot change ownership of an
-SSL listen socket prior to R16. Ranch will catch the error thrown, but the
-owner of the SSL socket will remain as whatever process created the socket.
-However, this will not affect accept behaviour unless the owner process dies,
-in which case the socket is closed. Therefore, to use this feature with SSL
-with an erlang release prior to R16, ensure that the SSL socket is opened in a
-persistant process.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_limiting_the_number_of_concurrent_connections">Limiting the number of concurrent connections</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>max_connections</code> transport option allows you to limit the number
-of concurrent connections. It defaults to 1024. Its purpose is to
-prevent your system from being overloaded and ensuring all the
-connections are handled optimally.</p></div>
-<div class="listingblock">
-<div class="title">Customizing the maximum number of concurrent connections</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: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>,
- <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">max_connections</span>, <span style="color: #993399">100</span>}],
- <span style="color: #FF6600">echo_protocol</span>, []
-)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can disable this limit by setting its value to the atom <code>infinity</code>.</p></div>
-<div class="listingblock">
-<div class="title">Disabling the limit for the number of connections</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: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>,
- <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">max_connections</span>, <span style="color: #FF6600">infinity</span>}],
- <span style="color: #FF6600">echo_protocol</span>, []
-)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The maximum number of connections is a soft limit. In practice, it
-can reach <code>max_connections</code> + the number of acceptors.</p></div>
-<div class="paragraph"><p>When the maximum number of connections is reached, Ranch will stop
-accepting connections. This will not result in further connections
-being rejected, as the kernel option allows queueing incoming
-connections. The size of this queue is determined by the <code>backlog</code>
-option and defaults to 1024. Ranch does not know about the number
-of connections that are in the backlog.</p></div>
-<div class="paragraph"><p>You may not always want connections to be counted when checking for
-<code>max_connections</code>. For example you might have a protocol where both
-short-lived and long-lived connections are possible. If the long-lived
-connections are mostly waiting for messages, then they don’t consume
-much resources and can safely be removed from the count.</p></div>
-<div class="paragraph"><p>To remove the connection from the count, you must call the
-<code>ranch:remove_connection/1</code> from within the connection process,
-with the name of the listener as the only argument.</p></div>
-<div class="listingblock">
-<div class="title">Removing a connection from the count of connections</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="font-weight: bold"><span style="color: #000000">ranch:remove_connection</span></span>(<span style="color: #009900">Ref</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>As seen in the chapter covering protocols, this pid is received as the
-first argument of the protocol’s <code>start_link/4</code> callback.</p></div>
-<div class="paragraph"><p>You can modify the <code>max_connections</code> value on a running listener by
-using the <code>ranch:set_max_connections/2</code> function, with the name of the
-listener as first argument and the new value as the second.</p></div>
-<div class="listingblock">
-<div class="title">Upgrading the maximum number of connections</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="font-weight: bold"><span style="color: #000000">ranch:set_max_connections</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #009900">MaxConns</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The change will occur immediately.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_customizing_the_number_of_acceptor_processes">Customizing the number of acceptor processes</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>By default Ranch will use 10 acceptor processes. Their role is
-to accept connections and spawn a connection process for every
-new connection.</p></div>
-<div class="paragraph"><p>This number can be tweaked to improve performance. A good
-number is typically between 10 or 100 acceptors. You must
-measure to find the best value for your application.</p></div>
-<div class="listingblock">
-<div class="title">Specifying a custom number of acceptor processes</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: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>,
- <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">num_acceptors</span>, <span style="color: #993399">42</span>}],
- <span style="color: #FF6600">echo_protocol</span>, []
-)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_when_running_out_of_file_descriptors">When running out of file descriptors</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Operating systems have limits on the number of sockets
-which can be opened by applications. When this maximum is
-reached the listener can no longer accept new connections. The
-accept rate of the listener will be automatically reduced, and a
-warning message will be logged.</p></div>
-<div class="listingblock">
-<div class="content">
-<pre><code>=ERROR REPORT==== 13-Jan-2016::12:24:38 ===
-Ranch acceptor reducing accept rate: out of file descriptors</code></pre>
-</div></div>
-<div class="paragraph"><p>If you notice messages like this you should increase the number
-of file-descriptors which can be opened by your application. How
-this should be done is operating-system dependent. Please consult
-the documentation of your operating system.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_using_a_supervisor_for_connection_processes">Using a supervisor for connection processes</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch allows you to define the type of process that will be used
-for the connection processes. By default it expects a <code>worker</code>.
-When the <code>connection_type</code> configuration value is set to <code>supervisor</code>,
-Ranch will consider that the connection process it manages is a
-supervisor and will reflect that in its supervision tree.</p></div>
-<div class="paragraph"><p>Connection processes of type <code>supervisor</code> can either handle the
-socket directly or through one of their children. In the latter
-case the start function for the connection process must return
-two pids: the pid of the supervisor you created (that will be
-supervised) and the pid of the protocol handling process (that
-will receive the socket).</p></div>
-<div class="paragraph"><p>Instead of returning <code>{ok, ConnPid}</code>, simply return
-<code>{ok, SupPid, ConnPid}</code>.</p></div>
-<div class="paragraph"><p>It is very important that the connection process be created
-under the supervisor process so that everything works as intended.
-If not, you will most likely experience issues when the supervised
-process is stopped.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_upgrading">Upgrading</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch allows you to upgrade the protocol options. This takes effect
-immediately and for all subsequent connections.</p></div>
-<div class="paragraph"><p>To upgrade the protocol options, call <code>ranch:set_protocol_options/2</code>
-with the name of the listener as first argument and the new options
-as the second.</p></div>
-<div class="listingblock">
-<div class="title">Upgrading the protocol options</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="font-weight: bold"><span style="color: #000000">ranch:set_protocol_options</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #009900">NewOpts</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>All future connections will use the new options.</p></div>
-<div class="paragraph"><p>You can also retrieve the current options similarly by
-calling <code>ranch:get_protocol_options/1</code>.</p></div>
-<div class="listingblock">
-<div class="title">Retrieving the current protocol options</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">Opts</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_protocol_options</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_obtaining_information_about_listeners">Obtaining information about listeners</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Ranch provides two functions for retrieving information about the
-listeners, for reporting and diagnostic purposes.</p></div>
-<div class="paragraph"><p>The <code>ranch:info/0</code> function will return detailed information
-about all listeners.</p></div>
-<div class="listingblock">
-<div class="title">Retrieving detailed information</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="font-weight: bold"><span style="color: #000000">ranch:info</span></span>()<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The <code>ranch:procs/2</code> function will return all acceptor or listener
-processes for a given listener.</p></div>
-<div class="listingblock">
-<div class="title">Get all acceptor processes</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="font-weight: bold"><span style="color: #000000">ranch:procs</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #FF6600">acceptors</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Get all connection processes</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="font-weight: bold"><span style="color: #000000">ranch:procs</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #FF6600">connections</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
+<div class="paragraph"><p>A listener is a set of processes whose role is to listen on a port +for new connections. It manages a pool of acceptor processes, each +of them indefinitely accepting connections. When it does, it starts +a new process executing the protocol handler code. All the socket +programming is abstracted through the use of transport handlers.</p></div> +<div class="paragraph"><p>The listener takes care of supervising all the acceptor and connection +processes, allowing developers to focus on building their application.</p></div> +<div class="sect1"> +<h2 id="_starting_a_listener">Starting a listener</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch does nothing by default. It is up to the application developer +to request that Ranch listens for connections.</p></div> +<div class="paragraph"><p>A listener can be started and stopped at will.</p></div> +<div class="paragraph"><p>When starting a listener, a number of different settings are required:</p></div> +<div class="ulist"><ul> +<li> +<p> +A name to identify it locally and be able to interact with it. +</p> +</li> +<li> +<p> +The number of acceptors in the pool. +</p> +</li> +<li> +<p> +A transport handler and its associated options. +</p> +</li> +<li> +<p> +A protocol handler and its associated options. +</p> +</li> +</ul></div> +<div class="paragraph"><p>Ranch includes both TCP and SSL transport handlers, respectively +<code>ranch_tcp</code> and <code>ranch_ssl</code>.</p></div> +<div class="paragraph"><p>A listener can be started by calling the <code>ranch:start_listener/5</code> +function. Before doing so however, you must ensure that the <code>ranch</code> +application is started.</p></div> +<div class="listingblock"> +<div class="title">Starting the Ranch application</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: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">application:start</span></span>(<span style="color: #FF6600">ranch</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You are then ready to start a listener. Let’s call it <code>tcp_echo</code>. It will +have a pool of 100 acceptors, use a TCP transport and forward connections +to the <code>echo_protocol</code> handler.</p></div> +<div class="listingblock"> +<div class="title">Starting a listener for TCP connections on port 5555</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: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, + <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}], + <span style="color: #FF6600">echo_protocol</span>, [] +)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You can try this out by compiling and running the <code>tcp_echo</code> example in the +examples directory. To do so, open a shell in the <em>examples/tcp_echo/</em> +directory and run the following command:</p></div> +<div class="listingblock"> +<div class="title">Building and starting a Ranch example</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>$ make run</tt></pre></div></div> +<div class="paragraph"><p>You can then connect to it using telnet and see the echo server reply +everything you send to it. Then when you’re done testing, you can use +the <code>Ctrl+]</code> key to escape to the telnet command line and type +<code>quit</code> to exit.</p></div> +<div class="listingblock"> +<div class="title">Connecting to the example listener with telnet</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>$ telnet localhost <span style="color: #993399">5555</span> +Trying <span style="color: #993399">127.0</span><span style="color: #990000">.</span><span style="color: #993399">0.1</span><span style="color: #990000">...</span> +Connected to localhost<span style="color: #990000">.</span> +Escape character is <span style="color: #FF0000">'^]'</span><span style="color: #990000">.</span> +Hello<span style="color: #990000">!</span> +Hello<span style="color: #990000">!</span> +It works<span style="color: #990000">!</span> +It works<span style="color: #990000">!</span> +<span style="color: #990000">^]</span> + +telnet<span style="color: #990000">></span> quit +Connection closed<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_stopping_a_listener">Stopping a listener</h2> +<div class="sectionbody"> +<div class="paragraph"><p>All you need to stop a Ranch listener is to call the +<code>ranch:stop_listener/1</code> function with the listener’s name +as argument. In the previous section we started the listener +named <code>tcp_echo</code>. We can now stop it.</p></div> +<div class="listingblock"> +<div class="title">Stopping a listener</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="font-weight: bold"><span style="color: #000000">ranch:stop_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_default_transport_options">Default transport options</h2> +<div class="sectionbody"> +<div class="paragraph"><p>By default the socket will be set to return <code>binary</code> data, with the +options <code>{active, false}</code>, <code>{packet, raw}</code>, <code>{reuseaddr, true}</code> set. +These values can’t be overriden when starting the listener, but +they can be overriden using <code>Transport:setopts/2</code> in the protocol.</p></div> +<div class="paragraph"><p>It will also set <code>{backlog, 1024}</code> and <code>{nodelay, true}</code>, which +can be overriden at listener startup.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_listening_on_a_random_port">Listening on a random port</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You do not have to specify a specific port to listen on. If you give +the port number 0, or if you omit the port number entirely, Ranch will +start listening on a random port.</p></div> +<div class="paragraph"><p>You can retrieve this port number by calling <code>ranch:get_port/1</code>. The +argument is the name of the listener you gave in <code>ranch:start_listener/5</code>.</p></div> +<div class="listingblock"> +<div class="title">Starting a listener for TCP connections on a random port</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: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, + <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">0</span>}], + <span style="color: #FF6600">echo_protocol</span>, [] +)<span style="color: #990000">.</span> +<span style="color: #009900">Port</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_port</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_listening_on_privileged_ports">Listening on privileged ports</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Some systems limit access to ports below 1024 for security reasons. +This can easily be identified by an <code>{error, eacces}</code> error when trying +to open a listening socket on such a port.</p></div> +<div class="paragraph"><p>The methods for listening on privileged ports vary between systems, +please refer to your system’s documentation for more information.</p></div> +<div class="paragraph"><p>We recommend the use of port rewriting for systems with a single server, +and load balancing for systems with multiple servers. Documenting these +solutions is however out of the scope of this guide.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_accepting_connections_on_an_existing_socket">Accepting connections on an existing socket</h2> +<div class="sectionbody"> +<div class="paragraph"><p>If you want to accept connections on an existing socket, you can use the +<code>socket</code> transport option, which should just be the relevant data returned +from the connect function for the transport or the underlying socket library +(<code>gen_tcp:connect</code>, <code>ssl:connect</code>). The accept function will then be +called on the passed in socket. You should connect the socket in +<code>{active, false}</code> mode, as well.</p></div> +<div class="paragraph"><p>Note, however, that because of a bug in SSL, you cannot change ownership of an +SSL listen socket prior to R16. Ranch will catch the error thrown, but the +owner of the SSL socket will remain as whatever process created the socket. +However, this will not affect accept behaviour unless the owner process dies, +in which case the socket is closed. Therefore, to use this feature with SSL +with an erlang release prior to R16, ensure that the SSL socket is opened in a +persistant process.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_limiting_the_number_of_concurrent_connections">Limiting the number of concurrent connections</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>max_connections</code> transport option allows you to limit the number +of concurrent connections. It defaults to 1024. Its purpose is to +prevent your system from being overloaded and ensuring all the +connections are handled optimally.</p></div> +<div class="listingblock"> +<div class="title">Customizing the maximum number of concurrent connections</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: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, + <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">max_connections</span>, <span style="color: #993399">100</span>}], + <span style="color: #FF6600">echo_protocol</span>, [] +)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You can disable this limit by setting its value to the atom <code>infinity</code>.</p></div> +<div class="listingblock"> +<div class="title">Disabling the limit for the number of connections</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: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, + <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">max_connections</span>, <span style="color: #FF6600">infinity</span>}], + <span style="color: #FF6600">echo_protocol</span>, [] +)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The maximum number of connections is a soft limit. In practice, it +can reach <code>max_connections</code> + the number of acceptors.</p></div> +<div class="paragraph"><p>When the maximum number of connections is reached, Ranch will stop +accepting connections. This will not result in further connections +being rejected, as the kernel option allows queueing incoming +connections. The size of this queue is determined by the <code>backlog</code> +option and defaults to 1024. Ranch does not know about the number +of connections that are in the backlog.</p></div> +<div class="paragraph"><p>You may not always want connections to be counted when checking for +<code>max_connections</code>. For example you might have a protocol where both +short-lived and long-lived connections are possible. If the long-lived +connections are mostly waiting for messages, then they don’t consume +much resources and can safely be removed from the count.</p></div> +<div class="paragraph"><p>To remove the connection from the count, you must call the +<code>ranch:remove_connection/1</code> from within the connection process, +with the name of the listener as the only argument.</p></div> +<div class="listingblock"> +<div class="title">Removing a connection from the count of connections</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="font-weight: bold"><span style="color: #000000">ranch:remove_connection</span></span>(<span style="color: #009900">Ref</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>As seen in the chapter covering protocols, this pid is received as the +first argument of the protocol’s <code>start_link/4</code> callback.</p></div> +<div class="paragraph"><p>You can modify the <code>max_connections</code> value on a running listener by +using the <code>ranch:set_max_connections/2</code> function, with the name of the +listener as first argument and the new value as the second.</p></div> +<div class="listingblock"> +<div class="title">Upgrading the maximum number of connections</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="font-weight: bold"><span style="color: #000000">ranch:set_max_connections</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #009900">MaxConns</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The change will occur immediately.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_customizing_the_number_of_acceptor_processes">Customizing the number of acceptor processes</h2> +<div class="sectionbody"> +<div class="paragraph"><p>By default Ranch will use 10 acceptor processes. Their role is +to accept connections and spawn a connection process for every +new connection.</p></div> +<div class="paragraph"><p>This number can be tweaked to improve performance. A good +number is typically between 10 or 100 acceptors. You must +measure to find the best value for your application.</p></div> +<div class="listingblock"> +<div class="title">Specifying a custom number of acceptor processes</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: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">tcp_echo</span>, + <span style="color: #FF6600">ranch_tcp</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">5555</span>}, {<span style="color: #FF6600">num_acceptors</span>, <span style="color: #993399">42</span>}], + <span style="color: #FF6600">echo_protocol</span>, [] +)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_when_running_out_of_file_descriptors">When running out of file descriptors</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Operating systems have limits on the number of sockets +which can be opened by applications. When this maximum is +reached the listener can no longer accept new connections. The +accept rate of the listener will be automatically reduced, and a +warning message will be logged.</p></div> +<div class="listingblock"> +<div class="content"> +<pre><code>=ERROR REPORT==== 13-Jan-2016::12:24:38 === +Ranch acceptor reducing accept rate: out of file descriptors</code></pre> +</div></div> +<div class="paragraph"><p>If you notice messages like this you should increase the number +of file-descriptors which can be opened by your application. How +this should be done is operating-system dependent. Please consult +the documentation of your operating system.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_using_a_supervisor_for_connection_processes">Using a supervisor for connection processes</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch allows you to define the type of process that will be used +for the connection processes. By default it expects a <code>worker</code>. +When the <code>connection_type</code> configuration value is set to <code>supervisor</code>, +Ranch will consider that the connection process it manages is a +supervisor and will reflect that in its supervision tree.</p></div> +<div class="paragraph"><p>Connection processes of type <code>supervisor</code> can either handle the +socket directly or through one of their children. In the latter +case the start function for the connection process must return +two pids: the pid of the supervisor you created (that will be +supervised) and the pid of the protocol handling process (that +will receive the socket).</p></div> +<div class="paragraph"><p>Instead of returning <code>{ok, ConnPid}</code>, simply return +<code>{ok, SupPid, ConnPid}</code>.</p></div> +<div class="paragraph"><p>It is very important that the connection process be created +under the supervisor process so that everything works as intended. +If not, you will most likely experience issues when the supervised +process is stopped.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_upgrading">Upgrading</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch allows you to upgrade the protocol options. This takes effect +immediately and for all subsequent connections.</p></div> +<div class="paragraph"><p>To upgrade the protocol options, call <code>ranch:set_protocol_options/2</code> +with the name of the listener as first argument and the new options +as the second.</p></div> +<div class="listingblock"> +<div class="title">Upgrading the protocol options</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="font-weight: bold"><span style="color: #000000">ranch:set_protocol_options</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #009900">NewOpts</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>All future connections will use the new options.</p></div> +<div class="paragraph"><p>You can also retrieve the current options similarly by +calling <code>ranch:get_protocol_options/1</code>.</p></div> +<div class="listingblock"> +<div class="title">Retrieving the current protocol options</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">Opts</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_protocol_options</span></span>(<span style="color: #FF6600">tcp_echo</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_obtaining_information_about_listeners">Obtaining information about listeners</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Ranch provides two functions for retrieving information about the +listeners, for reporting and diagnostic purposes.</p></div> +<div class="paragraph"><p>The <code>ranch:info/0</code> function will return detailed information +about all listeners.</p></div> +<div class="listingblock"> +<div class="title">Retrieving detailed information</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="font-weight: bold"><span style="color: #000000">ranch:info</span></span>()<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The <code>ranch:procs/2</code> function will return all acceptor or listener +processes for a given listener.</p></div> +<div class="listingblock"> +<div class="title">Get all acceptor processes</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="font-weight: bold"><span style="color: #000000">ranch:procs</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #FF6600">acceptors</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Get all connection processes</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="font-weight: bold"><span style="color: #000000">ranch:procs</span></span>(<span style="color: #FF6600">tcp_echo</span>, <span style="color: #FF6600">connections</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.3/guide/parsers/index.html b/docs/en/ranch/1.3/guide/parsers/index.html index 67fef620..41f19b7e 100644 --- a/docs/en/ranch/1.3/guide/parsers/index.html +++ b/docs/en/ranch/1.3/guide/parsers/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Writing parsers</title> @@ -67,115 +67,118 @@ <h1 class="lined-header"><span>Writing parsers</span></h1> -<div class="paragraph"><p>There are three kinds of protocols:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Text protocols
-</p>
-</li>
-<li>
-<p>
-Schema-less binary protocols
-</p>
-</li>
-<li>
-<p>
-Schema-based binary protocols
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>This chapter introduces the first two kinds. It will not cover
-more advanced topics such as continuations or parser generators.</p></div>
-<div class="paragraph"><p>This chapter isn’t specifically about Ranch, we assume here that
-you know how to read data from the socket. The data you read and
-the data that hasn’t been parsed is saved in a buffer. Every
-time you read from the socket, the data read is appended to the
-buffer. What happens next depends on the kind of protocol. We
-will only cover the first two.</p></div>
-<div class="sect1">
-<h2 id="_parsing_text">Parsing text</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Text protocols are generally line based. This means that we can’t
-do anything with them until we receive the full line.</p></div>
-<div class="paragraph"><p>A simple way to get a full line is to use <code>binary:split/{2,3}</code>.</p></div>
-<div class="listingblock">
-<div class="title">Using binary:split/2 to get a line of input</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="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">binary:split</span></span>(<span style="color: #009900">Buffer</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"\n"</span><span style="color: #990000">>></span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- [<span style="color: #990000">_</span>] <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">get_more_data</span></span>(<span style="color: #009900">Buffer</span>);
- [<span style="color: #009900">Line</span>, <span style="color: #009900">Rest</span>] <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">handle_line</span></span>(<span style="color: #009900">Line</span>, <span style="color: #009900">Rest</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>In the above example, we can have two results. Either there was
-a line break in the buffer and we get it split into two parts,
-the line and the rest of the buffer; or there was no line break
-in the buffer and we need to get more data from the socket.</p></div>
-<div class="paragraph"><p>Next, we need to parse the line. The simplest way is to again
-split, here on space. The difference is that we want to split
-on all spaces character, as we want to tokenize the whole string.</p></div>
-<div class="listingblock">
-<div class="title">Using binary:split/3 to split text</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="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">binary:split</span></span>(<span style="color: #009900">Line</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">" "</span><span style="color: #990000">>></span>, [<span style="color: #FF6600">global</span>]) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- [<span style="color: #990000"><<</span><span style="color: #FF0000">"HELLO"</span><span style="color: #990000">>></span>] <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">be_polite</span></span>();
- [<span style="color: #990000"><<</span><span style="color: #FF0000">"AUTH"</span><span style="color: #990000">>></span>, <span style="color: #009900">User</span>, <span style="color: #009900">Password</span>] <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">authenticate_user</span></span>(<span style="color: #009900">User</span>, <span style="color: #009900">Password</span>);
- [<span style="color: #990000"><<</span><span style="color: #FF0000">"QUIT"</span><span style="color: #990000">>></span>, <span style="color: #009900">Reason</span>] <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">quit</span></span>(<span style="color: #009900">Reason</span>)
- <span style="font-style: italic"><span style="color: #9A1900">%% ...</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>Pretty simple, right? Match on the command name, get the rest
-of the tokens in variables and call the respective functions.</p></div>
-<div class="paragraph"><p>After doing this, you will want to check if there is another
-line in the buffer, and handle it immediately if any.
-Otherwise wait for more data.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_parsing_binary">Parsing binary</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Binary protocols can be more varied, although most of them are
-pretty similar. The first four bytes of a frame tend to be
-the size of the frame, which is followed by a certain number
-of bytes for the type of frame and then various parameters.</p></div>
-<div class="paragraph"><p>Sometimes the size of the frame includes the first four bytes,
-sometimes not. Other times this size is encoded over two bytes.
-And even other times little-endian is used instead of big-endian.</p></div>
-<div class="paragraph"><p>The general idea stays the same though.</p></div>
-<div class="listingblock">
-<div class="title">Using binary pattern matching to split frames</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: #990000"><<</span> <span style="color: #009900">Size</span><span style="color: #990000">:</span><span style="color: #993399">32</span>, <span style="color: #990000">_/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span> <span style="color: #990000">=</span> <span style="color: #009900">Buffer</span>,
-<span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="color: #009900">Buffer</span> <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- <span style="color: #990000"><<</span> <span style="color: #009900">Frame</span><span style="color: #990000">:</span><span style="color: #009900">Size</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span> <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">handle_frame</span></span>(<span style="color: #009900">Frame</span>, <span style="color: #009900">Rest</span>);
- <span style="color: #990000">_</span> <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">get_more_data</span></span>(<span style="color: #009900">Buffer</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 will then need to parse this frame using binary pattern
-matching, and handle it. Then you will want to check if there
-is another frame fully received in the buffer, and handle it
-immediately if any. Otherwise wait for more data.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>There are three kinds of protocols:</p></div> +<div class="ulist"><ul> +<li> +<p> +Text protocols +</p> +</li> +<li> +<p> +Schema-less binary protocols +</p> +</li> +<li> +<p> +Schema-based binary protocols +</p> +</li> +</ul></div> +<div class="paragraph"><p>This chapter introduces the first two kinds. It will not cover +more advanced topics such as continuations or parser generators.</p></div> +<div class="paragraph"><p>This chapter isn’t specifically about Ranch, we assume here that +you know how to read data from the socket. The data you read and +the data that hasn’t been parsed is saved in a buffer. Every +time you read from the socket, the data read is appended to the +buffer. What happens next depends on the kind of protocol. We +will only cover the first two.</p></div> +<div class="sect1"> +<h2 id="_parsing_text">Parsing text</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Text protocols are generally line based. This means that we can’t +do anything with them until we receive the full line.</p></div> +<div class="paragraph"><p>A simple way to get a full line is to use <code>binary:split/{2,3}</code>.</p></div> +<div class="listingblock"> +<div class="title">Using binary:split/2 to get a line of input</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="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">binary:split</span></span>(<span style="color: #009900">Buffer</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"\n"</span><span style="color: #990000">>></span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + [<span style="color: #990000">_</span>] <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">get_more_data</span></span>(<span style="color: #009900">Buffer</span>); + [<span style="color: #009900">Line</span>, <span style="color: #009900">Rest</span>] <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">handle_line</span></span>(<span style="color: #009900">Line</span>, <span style="color: #009900">Rest</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>In the above example, we can have two results. Either there was +a line break in the buffer and we get it split into two parts, +the line and the rest of the buffer; or there was no line break +in the buffer and we need to get more data from the socket.</p></div> +<div class="paragraph"><p>Next, we need to parse the line. The simplest way is to again +split, here on space. The difference is that we want to split +on all spaces character, as we want to tokenize the whole string.</p></div> +<div class="listingblock"> +<div class="title">Using binary:split/3 to split text</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="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="font-weight: bold"><span style="color: #000000">binary:split</span></span>(<span style="color: #009900">Line</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">" "</span><span style="color: #990000">>></span>, [<span style="color: #FF6600">global</span>]) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + [<span style="color: #990000"><<</span><span style="color: #FF0000">"HELLO"</span><span style="color: #990000">>></span>] <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">be_polite</span></span>(); + [<span style="color: #990000"><<</span><span style="color: #FF0000">"AUTH"</span><span style="color: #990000">>></span>, <span style="color: #009900">User</span>, <span style="color: #009900">Password</span>] <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">authenticate_user</span></span>(<span style="color: #009900">User</span>, <span style="color: #009900">Password</span>); + [<span style="color: #990000"><<</span><span style="color: #FF0000">"QUIT"</span><span style="color: #990000">>></span>, <span style="color: #009900">Reason</span>] <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">quit</span></span>(<span style="color: #009900">Reason</span>) + <span style="font-style: italic"><span style="color: #9A1900">%% ...</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>Pretty simple, right? Match on the command name, get the rest +of the tokens in variables and call the respective functions.</p></div> +<div class="paragraph"><p>After doing this, you will want to check if there is another +line in the buffer, and handle it immediately if any. +Otherwise wait for more data.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_parsing_binary">Parsing binary</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Binary protocols can be more varied, although most of them are +pretty similar. The first four bytes of a frame tend to be +the size of the frame, which is followed by a certain number +of bytes for the type of frame and then various parameters.</p></div> +<div class="paragraph"><p>Sometimes the size of the frame includes the first four bytes, +sometimes not. Other times this size is encoded over two bytes. +And even other times little-endian is used instead of big-endian.</p></div> +<div class="paragraph"><p>The general idea stays the same though.</p></div> +<div class="listingblock"> +<div class="title">Using binary pattern matching to split frames</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: #990000"><<</span> <span style="color: #009900">Size</span><span style="color: #990000">:</span><span style="color: #993399">32</span>, <span style="color: #990000">_/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span> <span style="color: #990000">=</span> <span style="color: #009900">Buffer</span>, +<span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="color: #009900">Buffer</span> <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + <span style="color: #990000"><<</span> <span style="color: #009900">Frame</span><span style="color: #990000">:</span><span style="color: #009900">Size</span><span style="color: #990000">/</span><span style="font-weight: bold"><span style="color: #000080">binary</span></span>, <span style="color: #009900">Rest</span><span style="color: #990000">/</span><span style="color: #FF6600">bits</span> <span style="color: #990000">>></span> <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">handle_frame</span></span>(<span style="color: #009900">Frame</span>, <span style="color: #009900">Rest</span>); + <span style="color: #990000">_</span> <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">get_more_data</span></span>(<span style="color: #009900">Buffer</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 will then need to parse this frame using binary pattern +matching, and handle it. Then you will want to check if there +is another frame fully received in the buffer, and handle it +immediately if any. Otherwise wait for more data.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.3/guide/protocols/index.html b/docs/en/ranch/1.3/guide/protocols/index.html index 45e13bf7..d42e9d7d 100644 --- a/docs/en/ranch/1.3/guide/protocols/index.html +++ b/docs/en/ranch/1.3/guide/protocols/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Protocols</title> @@ -67,110 +67,113 @@ <h1 class="lined-header"><span>Protocols</span></h1> -<div class="paragraph"><p>A protocol handler starts a connection process and defines the
-protocol logic executed in this process.</p></div>
-<div class="sect1">
-<h2 id="_writing_a_protocol_handler">Writing a protocol handler</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>All protocol handlers must implement the <code>ranch_protocol</code> behavior
-which defines a single callback, <code>start_link/4</code>. This callback is
-responsible for spawning a new process for handling the connection.
-It receives four arguments: the name of the listener, the socket, the
-transport handler being used and the protocol options defined in
-the call to <code>ranch:start_listener/5</code>. This callback must
-return <code>{ok, Pid}</code>, with <code>Pid</code> the pid of the new process.</p></div>
-<div class="paragraph"><p>The newly started process can then freely initialize itself. However,
-it must call <code>ranch:accept_ack/1</code> before doing any socket operation.
-This will ensure the connection process is the owner of the socket.
-It expects the listener’s name as argument.</p></div>
-<div class="listingblock">
-<div class="title">Acknowledge accepting the socket</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: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>If your protocol code requires specific socket options, you should
-set them while initializing your connection process, after
-calling <code>ranch:accept_ack/1</code>. You can use <code>Transport:setopts/2</code>
-for that purpose.</p></div>
-<div class="paragraph"><p>Following is the complete protocol code for the example found
-in <code>examples/tcp_echo/</code>.</p></div>
-<div class="listingblock">
-<div class="title">Protocol module that echoes everything it receives</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="font-weight: bold"><span style="color: #000080">-module</span></span>(<span style="color: #FF6600">echo_protocol</span>)<span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">ranch_protocol</span>)<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">start_link</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">init</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">start_link</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span>
- <span style="color: #009900">Pid</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000080">spawn_link</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, <span style="color: #FF6600">init</span>, [<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>]),
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Pid</span>}<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">_Opts</span> <span style="color: #990000">=</span> []) <span style="color: #990000">-></span>
- <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>),
- <span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>)<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>) <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">recv</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #993399">0</span>, <span style="color: #993399">5000</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: #990000">-></span>
- <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Data</span>),
- <span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>);
- <span style="color: #990000">_</span> <span style="color: #990000">-></span>
- <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">close</span></span>(<span style="color: #009900">Socket</span>)
- <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_using_gen_server">Using gen_server</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Special processes like the ones that use the <code>gen_server</code> or <code>gen_fsm</code>
-behaviours have the particularity of having their <code>start_link</code> call not
-return until the <code>init</code> function returns. This is problematic, because
-you won’t be able to call <code>ranch:accept_ack/1</code> from the <code>init</code> callback
-as this would cause a deadlock to happen.</p></div>
-<div class="paragraph"><p>Use the <code>gen_server:enter_loop/3</code> function. It allows you to start your process
-normally (although it must be started with <code>proc_lib</code> like all special
-processes), then perform any needed operations before falling back into
-the normal <code>gen_server</code> execution loop.</p></div>
-<div class="listingblock">
-<div class="title">Use a gen_server for protocol handling</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="font-weight: bold"><span style="color: #000080">-module</span></span>(<span style="color: #FF6600">my_protocol</span>)<span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">gen_server</span>)<span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">ranch_protocol</span>)<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">start_link</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span>
-<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">init</span></span><span style="color: #990000">/</span><span style="color: #993399">1</span>])<span style="color: #990000">.</span>
-<span style="font-style: italic"><span style="color: #9A1900">%% Exports of other gen_server callbacks here.</span></span>
-
-<span style="font-weight: bold"><span style="color: #000000">start_link</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="font-weight: bold"><span style="color: #000000">proc_lib:spawn_link</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, <span style="color: #FF6600">init</span>, [{<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>}])}<span style="color: #990000">.</span>
-
-<span style="font-weight: bold"><span style="color: #000000">init</span></span>({<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">_Opts</span> <span style="color: #990000">=</span> []}) <span style="color: #990000">-></span>
- <span style="font-style: italic"><span style="color: #9A1900">%% Perform any required state initialization here.</span></span>
- <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>),
- <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">setopts</span></span>(<span style="color: #009900">Socket</span>, [{<span style="color: #FF6600">active</span>, <span style="color: #FF6600">once</span>}]),
- <span style="font-weight: bold"><span style="color: #000000">gen_server:enter_loop</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, [], {<span style="color: #FF6600">state</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>})<span style="color: #990000">.</span>
-
-<span style="font-style: italic"><span style="color: #9A1900">%% Other gen_server callbacks here.</span></span></tt></pre></div></div>
-<div class="paragraph"><p>Check the <code>tcp_reverse</code> example for a complete example.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>A protocol handler starts a connection process and defines the +protocol logic executed in this process.</p></div> +<div class="sect1"> +<h2 id="_writing_a_protocol_handler">Writing a protocol handler</h2> +<div class="sectionbody"> +<div class="paragraph"><p>All protocol handlers must implement the <code>ranch_protocol</code> behavior +which defines a single callback, <code>start_link/4</code>. This callback is +responsible for spawning a new process for handling the connection. +It receives four arguments: the name of the listener, the socket, the +transport handler being used and the protocol options defined in +the call to <code>ranch:start_listener/5</code>. This callback must +return <code>{ok, Pid}</code>, with <code>Pid</code> the pid of the new process.</p></div> +<div class="paragraph"><p>The newly started process can then freely initialize itself. However, +it must call <code>ranch:accept_ack/1</code> before doing any socket operation. +This will ensure the connection process is the owner of the socket. +It expects the listener’s name as argument.</p></div> +<div class="listingblock"> +<div class="title">Acknowledge accepting the socket</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: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>If your protocol code requires specific socket options, you should +set them while initializing your connection process, after +calling <code>ranch:accept_ack/1</code>. You can use <code>Transport:setopts/2</code> +for that purpose.</p></div> +<div class="paragraph"><p>Following is the complete protocol code for the example found +in <code>examples/tcp_echo/</code>.</p></div> +<div class="listingblock"> +<div class="title">Protocol module that echoes everything it receives</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="font-weight: bold"><span style="color: #000080">-module</span></span>(<span style="color: #FF6600">echo_protocol</span>)<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">ranch_protocol</span>)<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">start_link</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">init</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">start_link</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span> + <span style="color: #009900">Pid</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000080">spawn_link</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, <span style="color: #FF6600">init</span>, [<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>]), + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Pid</span>}<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">init</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">_Opts</span> <span style="color: #990000">=</span> []) <span style="color: #990000">-></span> + <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>), + <span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>)<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>) <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #0000FF">case</span></span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">recv</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #993399">0</span>, <span style="color: #993399">5000</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: #990000">-></span> + <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Data</span>), + <span style="font-weight: bold"><span style="color: #000000">loop</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>); + <span style="color: #990000">_</span> <span style="color: #990000">-></span> + <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">close</span></span>(<span style="color: #009900">Socket</span>) + <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_using_gen_server">Using gen_server</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Special processes like the ones that use the <code>gen_server</code> or <code>gen_fsm</code> +behaviours have the particularity of having their <code>start_link</code> call not +return until the <code>init</code> function returns. This is problematic, because +you won’t be able to call <code>ranch:accept_ack/1</code> from the <code>init</code> callback +as this would cause a deadlock to happen.</p></div> +<div class="paragraph"><p>Use the <code>gen_server:enter_loop/3</code> function. It allows you to start your process +normally (although it must be started with <code>proc_lib</code> like all special +processes), then perform any needed operations before falling back into +the normal <code>gen_server</code> execution loop.</p></div> +<div class="listingblock"> +<div class="title">Use a gen_server for protocol handling</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="font-weight: bold"><span style="color: #000080">-module</span></span>(<span style="color: #FF6600">my_protocol</span>)<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">gen_server</span>)<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-behaviour</span></span>(<span style="color: #FF6600">ranch_protocol</span>)<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">start_link</span></span><span style="color: #990000">/</span><span style="color: #993399">4</span>])<span style="color: #990000">.</span> +<span style="font-weight: bold"><span style="color: #000080">-export</span></span>([<span style="font-weight: bold"><span style="color: #000000">init</span></span><span style="color: #990000">/</span><span style="color: #993399">1</span>])<span style="color: #990000">.</span> +<span style="font-style: italic"><span style="color: #9A1900">%% Exports of other gen_server callbacks here.</span></span> + +<span style="font-weight: bold"><span style="color: #000000">start_link</span></span>(<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="font-weight: bold"><span style="color: #000000">proc_lib:spawn_link</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, <span style="color: #FF6600">init</span>, [{<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">Opts</span>}])}<span style="color: #990000">.</span> + +<span style="font-weight: bold"><span style="color: #000000">init</span></span>({<span style="color: #009900">Ref</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>, <span style="color: #009900">_Opts</span> <span style="color: #990000">=</span> []}) <span style="color: #990000">-></span> + <span style="font-style: italic"><span style="color: #9A1900">%% Perform any required state initialization here.</span></span> + <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:accept_ack</span></span>(<span style="color: #009900">Ref</span>), + <span style="color: #0000FF">ok</span> <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">setopts</span></span>(<span style="color: #009900">Socket</span>, [{<span style="color: #FF6600">active</span>, <span style="color: #FF6600">once</span>}]), + <span style="font-weight: bold"><span style="color: #000000">gen_server:enter_loop</span></span>(<span style="font-weight: bold"><span style="color: #000080">?MODULE</span></span>, [], {<span style="color: #FF6600">state</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Transport</span>})<span style="color: #990000">.</span> + +<span style="font-style: italic"><span style="color: #9A1900">%% Other gen_server callbacks here.</span></span></tt></pre></div></div> +<div class="paragraph"><p>Check the <code>tcp_reverse</code> example for a complete example.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.3/guide/ssl_auth/index.html b/docs/en/ranch/1.3/guide/ssl_auth/index.html index b831fbe2..3cc585f2 100644 --- a/docs/en/ranch/1.3/guide/ssl_auth/index.html +++ b/docs/en/ranch/1.3/guide/ssl_auth/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: SSL client authentication</title> @@ -67,164 +67,167 @@ <h1 class="lined-header"><span>SSL client authentication</span></h1> -<div class="sect1">
-<h2 id="_purpose">Purpose</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>SSL client authentication is a mechanism allowing applications to
-identify certificates. This allows your application to make sure that
-the client is an authorized certificate, but makes no claim about
-whether the user can be trusted. This can be combined with a password
-based authentication to attain greater security.</p></div>
-<div class="paragraph"><p>The server only needs to retain the certificate serial number and
-the certificate issuer to authenticate the certificate. Together,
-they can be used to uniquely identify a certicate.</p></div>
-<div class="paragraph"><p>As Ranch allows the same protocol code to be used for both SSL and
-non-SSL transports, you need to make sure you are in an SSL context
-before attempting to perform an SSL client authentication. This
-can be done by checking the return value of <code>Transport:name/0</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_obtaining_client_certificates">Obtaining client certificates</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can obtain client certificates from various sources. You can
-generate them yourself, or you can use a service like CAcert.org
-which allows you to generate client and server certificates for
-free.</p></div>
-<div class="paragraph"><p>Following are the steps you need to take to create a CAcert.org
-account, generate a certificate and install it in your favorite
-browser.</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Open <a href="http://cacert.org">http://cacert.org</a> in your favorite browser
-</p>
-</li>
-<li>
-<p>
-Root Certificate link: install both certificates
-</p>
-</li>
-<li>
-<p>
-Join (Register an account)
-</p>
-</li>
-<li>
-<p>
-Verify your account (check your email inbox!)
-</p>
-</li>
-<li>
-<p>
-Log in
-</p>
-</li>
-<li>
-<p>
-Client Certificates: New
-</p>
-</li>
-<li>
-<p>
-Follow instructions to create the certificate
-</p>
-</li>
-<li>
-<p>
-Install the certificate in your browser
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>You can optionally save the certificate for later use, for example
-to extract the <code>IssuerID</code> information as will be detailed later on.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_transport_configuration">Transport configuration</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The SSL transport does not request a client certificate by default.
-You need to specify the <code>{verify, verify_peer}</code> option when starting
-the listener to enable this behavior.</p></div>
-<div class="listingblock">
-<div class="title">Configure a listener for SSL authentication</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: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">my_ssl</span>,
- <span style="color: #FF6600">ranch_ssl</span>, [
- {<span style="color: #FF6600">port</span>, <span style="color: #009900">SSLPort</span>},
- {<span style="color: #FF6600">certfile</span>, <span style="color: #009900">PathToCertfile</span>},
- {<span style="color: #FF6600">cacertfile</span>, <span style="color: #009900">PathToCACertfile</span>},
- {<span style="color: #FF6600">verify</span>, <span style="color: #FF6600">verify_peer</span>}
- ],
- <span style="color: #FF6600">my_protocol</span>, []
-)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>In this example we set the required <code>port</code> and <code>certfile</code>, but also
-the <code>cacertfile</code> containing the CACert.org root certificate, and
-the option to request the client certificate.</p></div>
-<div class="paragraph"><p>If you enable the <code>{verify, verify_peer}</code> option and the client does
-not have a client certificate configured for your domain, then no
-certificate will be sent. This allows you to use SSL for more than
-just authenticated clients.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_authentication">Authentication</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>To authenticate users, you must first save the certificate information
-required. If you have your users' certificate files, you can simply
-load the certificate and retrieve the information directly.</p></div>
-<div class="listingblock">
-<div class="title">Retrieve the issuer ID from a certificate</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="font-weight: bold"><span style="color: #000000">certfile_to_issuer_id</span></span>(<span style="color: #009900">Filename</span>) <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:read_file</span></span>(<span style="color: #009900">Filename</span>),
- [{<span style="color: #FF6600">'Certificate'</span>, <span style="color: #009900">Cert</span>, <span style="color: #FF6600">not_encrypted</span>}] <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pem_decode</span></span>(<span style="color: #009900">Data</span>),
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">IssuerID</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pkix_issuer_id</span></span>(<span style="color: #009900">Cert</span>, <span style="font-weight: bold"><span style="color: #000080">self</span></span>),
- <span style="color: #009900">IssuerID</span><span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>The <code>IssuerID</code> variable contains both the certificate serial number
-and the certificate issuer stored in a tuple, so this value alone can
-be used to uniquely identify the user certificate. You can save this
-value in a database, a configuration file or any other place where an
-Erlang term can be stored and retrieved.</p></div>
-<div class="paragraph"><p>To retrieve the <code>IssuerID</code> from a running connection, you need to first
-retrieve the client certificate and then extract this information from
-it. Ranch does not provide a function to retrieve the client certificate.
-Instead you can use the <code>ssl:peercert/1</code> function. Once you have the
-certificate, you can again use the <code>public_key:pkix_issuer_id/2</code> to
-extract the <code>IssuerID</code> value.</p></div>
-<div class="paragraph"><p>The following function returns the <code>IssuerID</code> or <code>false</code> if no client
-certificate was found. This snippet is intended to be used from your
-protocol code.</p></div>
-<div class="listingblock">
-<div class="title">Retrieve the issuer ID from the certificate for the current connection</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="font-weight: bold"><span style="color: #000000">socket_to_issuer_id</span></span>(<span style="color: #009900">Socket</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">ssl:peercert</span></span>(<span style="color: #009900">Socket</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>
- {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">no_peercert</span>} <span style="color: #990000">-></span>
- <span style="color: #000080">false</span>;
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Cert</span>} <span style="color: #990000">-></span>
- {<span style="color: #FF6600">ok</span>, <span style="color: #009900">IssuerID</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pkix_issuer_id</span></span>(<span style="color: #009900">Cert</span>, <span style="font-weight: bold"><span style="color: #000080">self</span></span>),
- <span style="color: #009900">IssuerID</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 then only need to match the <code>IssuerID</code> value to authenticate the
-user.</p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_purpose">Purpose</h2> +<div class="sectionbody"> +<div class="paragraph"><p>SSL client authentication is a mechanism allowing applications to +identify certificates. This allows your application to make sure that +the client is an authorized certificate, but makes no claim about +whether the user can be trusted. This can be combined with a password +based authentication to attain greater security.</p></div> +<div class="paragraph"><p>The server only needs to retain the certificate serial number and +the certificate issuer to authenticate the certificate. Together, +they can be used to uniquely identify a certicate.</p></div> +<div class="paragraph"><p>As Ranch allows the same protocol code to be used for both SSL and +non-SSL transports, you need to make sure you are in an SSL context +before attempting to perform an SSL client authentication. This +can be done by checking the return value of <code>Transport:name/0</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_obtaining_client_certificates">Obtaining client certificates</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You can obtain client certificates from various sources. You can +generate them yourself, or you can use a service like CAcert.org +which allows you to generate client and server certificates for +free.</p></div> +<div class="paragraph"><p>Following are the steps you need to take to create a CAcert.org +account, generate a certificate and install it in your favorite +browser.</p></div> +<div class="ulist"><ul> +<li> +<p> +Open <a href="http://cacert.org">http://cacert.org</a> in your favorite browser +</p> +</li> +<li> +<p> +Root Certificate link: install both certificates +</p> +</li> +<li> +<p> +Join (Register an account) +</p> +</li> +<li> +<p> +Verify your account (check your email inbox!) +</p> +</li> +<li> +<p> +Log in +</p> +</li> +<li> +<p> +Client Certificates: New +</p> +</li> +<li> +<p> +Follow instructions to create the certificate +</p> +</li> +<li> +<p> +Install the certificate in your browser +</p> +</li> +</ul></div> +<div class="paragraph"><p>You can optionally save the certificate for later use, for example +to extract the <code>IssuerID</code> information as will be detailed later on.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_transport_configuration">Transport configuration</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The SSL transport does not request a client certificate by default. +You need to specify the <code>{verify, verify_peer}</code> option when starting +the listener to enable this behavior.</p></div> +<div class="listingblock"> +<div class="title">Configure a listener for SSL authentication</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: #FF6600">ok</span>, <span style="color: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:start_listener</span></span>(<span style="color: #FF6600">my_ssl</span>, + <span style="color: #FF6600">ranch_ssl</span>, [ + {<span style="color: #FF6600">port</span>, <span style="color: #009900">SSLPort</span>}, + {<span style="color: #FF6600">certfile</span>, <span style="color: #009900">PathToCertfile</span>}, + {<span style="color: #FF6600">cacertfile</span>, <span style="color: #009900">PathToCACertfile</span>}, + {<span style="color: #FF6600">verify</span>, <span style="color: #FF6600">verify_peer</span>} + ], + <span style="color: #FF6600">my_protocol</span>, [] +)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>In this example we set the required <code>port</code> and <code>certfile</code>, but also +the <code>cacertfile</code> containing the CACert.org root certificate, and +the option to request the client certificate.</p></div> +<div class="paragraph"><p>If you enable the <code>{verify, verify_peer}</code> option and the client does +not have a client certificate configured for your domain, then no +certificate will be sent. This allows you to use SSL for more than +just authenticated clients.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_authentication">Authentication</h2> +<div class="sectionbody"> +<div class="paragraph"><p>To authenticate users, you must first save the certificate information +required. If you have your users' certificate files, you can simply +load the certificate and retrieve the information directly.</p></div> +<div class="listingblock"> +<div class="title">Retrieve the issuer ID from a certificate</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="font-weight: bold"><span style="color: #000000">certfile_to_issuer_id</span></span>(<span style="color: #009900">Filename</span>) <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:read_file</span></span>(<span style="color: #009900">Filename</span>), + [{<span style="color: #FF6600">'Certificate'</span>, <span style="color: #009900">Cert</span>, <span style="color: #FF6600">not_encrypted</span>}] <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pem_decode</span></span>(<span style="color: #009900">Data</span>), + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">IssuerID</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pkix_issuer_id</span></span>(<span style="color: #009900">Cert</span>, <span style="font-weight: bold"><span style="color: #000080">self</span></span>), + <span style="color: #009900">IssuerID</span><span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>The <code>IssuerID</code> variable contains both the certificate serial number +and the certificate issuer stored in a tuple, so this value alone can +be used to uniquely identify the user certificate. You can save this +value in a database, a configuration file or any other place where an +Erlang term can be stored and retrieved.</p></div> +<div class="paragraph"><p>To retrieve the <code>IssuerID</code> from a running connection, you need to first +retrieve the client certificate and then extract this information from +it. Ranch does not provide a function to retrieve the client certificate. +Instead you can use the <code>ssl:peercert/1</code> function. Once you have the +certificate, you can again use the <code>public_key:pkix_issuer_id/2</code> to +extract the <code>IssuerID</code> value.</p></div> +<div class="paragraph"><p>The following function returns the <code>IssuerID</code> or <code>false</code> if no client +certificate was found. This snippet is intended to be used from your +protocol code.</p></div> +<div class="listingblock"> +<div class="title">Retrieve the issuer ID from the certificate for the current connection</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="font-weight: bold"><span style="color: #000000">socket_to_issuer_id</span></span>(<span style="color: #009900">Socket</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">ssl:peercert</span></span>(<span style="color: #009900">Socket</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span> + {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">no_peercert</span>} <span style="color: #990000">-></span> + <span style="color: #000080">false</span>; + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">Cert</span>} <span style="color: #990000">-></span> + {<span style="color: #FF6600">ok</span>, <span style="color: #009900">IssuerID</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">public_key:pkix_issuer_id</span></span>(<span style="color: #009900">Cert</span>, <span style="font-weight: bold"><span style="color: #000080">self</span></span>), + <span style="color: #009900">IssuerID</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 then only need to match the <code>IssuerID</code> value to authenticate the +user.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.3/guide/transports/index.html b/docs/en/ranch/1.3/guide/transports/index.html index 56103db3..1b13c696 100644 --- a/docs/en/ranch/1.3/guide/transports/index.html +++ b/docs/en/ranch/1.3/guide/transports/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Transports</title> @@ -67,185 +67,188 @@ <h1 class="lined-header"><span>Transports</span></h1> -<div class="paragraph"><p>A transport defines the interface to interact with a socket.</p></div>
-<div class="paragraph"><p>Transports can be used for connecting, listening and accepting
-connections, but also for receiving and sending data. Both
-passive and active mode are supported, although all sockets
-are initialized as passive.</p></div>
-<div class="sect1">
-<h2 id="_tcp_transport">TCP transport</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The TCP transport is a thin wrapper around <code>gen_tcp</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_ssl_transport">SSL transport</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The SSL transport is a thin wrapper around <code>ssl</code>.</p></div>
-<div class="paragraph"><p>Ranch depends on <code>ssl</code> by default so any necessary
-dependencies will start when Ranch is started. It is
-possible to remove the dependency when the SSL transport
-will not be used. Refer to your release build tool’s
-documentation for more information.</p></div>
-<div class="paragraph"><p>When embedding Ranch listeners that have an SSL transport,
-your application must depend on the <code>ssl</code> application for
-proper behavior.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_sending_and_receiving_data">Sending and receiving data</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This section assumes that <code>Transport</code> is a valid transport handler
-(like <code>ranch_tcp</code> or <code>ranch_ssl</code>) and <code>Socket</code> is a connected
-socket obtained through the listener.</p></div>
-<div class="paragraph"><p>You can send data to a socket by calling the <code>Transport:send/2</code>
-function. The data can be given as <code>iodata()</code>, which is defined as
-<code>binary() | iolist()</code>. All the following calls will work:</p></div>
-<div class="listingblock">
-<div class="title">Sending data to the socket</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">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"Ranch is cool!"</span><span style="color: #990000">>></span>)<span style="color: #990000">.</span>
-<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #FF0000">"Ranch is cool!"</span>)<span style="color: #990000">.</span>
-<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, [<span style="color: #FF0000">"Ranch"</span>, [<span style="color: #FF0000">"is"</span>, <span style="color: #FF0000">"cool!"</span>]])<span style="color: #990000">.</span>
-<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, [<span style="color: #FF0000">"Ranch"</span>, [<span style="color: #990000"><<</span><span style="color: #FF0000">"is"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"cool!"</span>]])<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can receive data either in passive or in active mode. Passive mode
-means that you will perform a blocking <code>Transport:recv/3</code> call, while
-active mode means that you will receive the data as a message.</p></div>
-<div class="paragraph"><p>By default, all data will be received as binary. It is possible to
-receive data as strings, although this is not recommended as binaries
-are a more efficient construct, especially for binary protocols.</p></div>
-<div class="paragraph"><p>Receiving data using passive mode requires a single function call. The
-first argument is the socket, and the third argument is a timeout duration
-before the call returns with <code>{error, timeout}</code>.</p></div>
-<div class="paragraph"><p>The second argument is the amount of data in bytes that we want to receive.
-The function will wait for data until it has received exactly this amount.
-If you are not expecting a precise size, you can specify 0 which will make
-this call return as soon as data was read, regardless of its size.</p></div>
-<div class="listingblock">
-<div class="title">Receiving data from the socket in passive mode</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: #FF6600">ok</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">recv</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #993399">0</span>, <span style="color: #993399">5000</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Active mode requires you to inform the socket that you want to receive
-data as a message and to write the code to actually receive it.</p></div>
-<div class="paragraph"><p>There are two kinds of active modes: <code>{active, once}</code> and
-<code>{active, true}</code>. The first will send a single message before going
-back to passive mode; the second will send messages indefinitely.
-We recommend not using the <code>{active, true}</code> mode as it could quickly
-flood your process mailbox. It’s better to keep the data in the socket
-and read it only when required.</p></div>
-<div class="paragraph"><p>Three different messages can be received:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<code>{OK, Socket, Data}</code>
-</p>
-</li>
-<li>
-<p>
-<code>{Closed, Socket}</code>
-</p>
-</li>
-<li>
-<p>
-<code>{Error, Socket, Reason}</code>
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>The value of <code>OK</code>, <code>Closed</code> and <code>Error</code> can be different
-depending on the transport being used. To be able to properly match
-on them you must first call the <code>Transport:messages/0</code> function.</p></div>
-<div class="listingblock">
-<div class="title">Retrieving the transport’s active message identifiers</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">OK</span>, <span style="color: #009900">Closed</span>, <span style="color: #009900">Error</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">messages</span></span>()<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>To start receiving messages you will need to call the <code>Transport:setopts/2</code>
-function, and do so every time you want to receive data.</p></div>
-<div class="listingblock">
-<div class="title">Receiving messages from the socket in active mode</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">OK</span>, <span style="color: #009900">Closed</span>, <span style="color: #009900">Error</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">messages</span></span>(),
-<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">setopts</span></span>(<span style="color: #009900">Socket</span>, [{<span style="color: #FF6600">active</span>, <span style="color: #FF6600">once</span>}]),
-<span style="font-weight: bold"><span style="color: #0000FF">receive</span></span>
- {<span style="color: #009900">OK</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"data received: ~p~n"</span>, [<span style="color: #009900">Data</span>]);
- {<span style="color: #009900">Closed</span>, <span style="color: #009900">Socket</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"socket got closed!~n"</span>);
- {<span style="color: #009900">Error</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span>
- <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"error happened: ~p~n"</span>, [<span style="color: #009900">Reason</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 easily integrate active sockets with existing Erlang code as all
-you really need is just a few more clauses when receiving messages.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_sending_files">Sending files</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>As in the previous section it is assumed <code>Transport</code> is a valid transport
-handler and <code>Socket</code> is a connected socket obtained through the listener.</p></div>
-<div class="paragraph"><p>To send a whole file, with name <code>Filename</code>, over a socket:</p></div>
-<div class="listingblock">
-<div class="title">Sending a file by filename</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: #FF6600">ok</span>, <span style="color: #009900">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Filename</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Or part of a file, with <code>Offset</code> greater than or equal to 0, <code>Bytes</code> number of
-bytes and chunks of size <code>ChunkSize</code>:</p></div>
-<div class="listingblock">
-<div class="title">Sending part of a file by filename in chunks</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">Opts</span> <span style="color: #990000">=</span> [{<span style="color: #FF6600">chunk_size</span>, <span style="color: #009900">ChunkSize</span>}],
-{<span style="color: #FF6600">ok</span>, <span style="color: #009900">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Filename</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Bytes</span>, <span style="color: #009900">Opts</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>To improve efficiency when sending multiple parts of the same file it is also
-possible to use a file descriptor opened in raw mode:</p></div>
-<div class="listingblock">
-<div class="title">Sending a file opened in raw mode</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: #FF6600">ok</span>, <span style="color: #009900">RawFile</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:open</span></span>(<span style="color: #009900">Filename</span>, [<span style="color: #FF6600">raw</span>, <span style="color: #FF6600">read</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>]),
-{<span style="color: #FF6600">ok</span>, <span style="color: #009900">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">RawFile</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Bytes</span>, <span style="color: #009900">Opts</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_writing_a_transport_handler">Writing a transport handler</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A transport handler is a module implementing the <code>ranch_transport</code> behavior.
-It defines a certain number of callbacks that must be written in order to
-allow transparent usage of the transport handler.</p></div>
-<div class="paragraph"><p>The behavior doesn’t define the socket options available when opening a
-socket. These do not need to be common to all transports as it’s easy enough
-to write different initialization functions for the different transports that
-will be used. With one exception though. The <code>setopts/2</code> function <strong>must</strong>
-implement the <code>{active, once}</code> and the <code>{active, true}</code> options.</p></div>
-<div class="paragraph"><p>If the transport handler doesn’t have a native implementation of <code>sendfile/5</code> a
-fallback is available, <code>ranch_transport:sendfile/6</code>. The extra first argument
-is the transport’s module. See <code>ranch_ssl</code> for an example.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>A transport defines the interface to interact with a socket.</p></div> +<div class="paragraph"><p>Transports can be used for connecting, listening and accepting +connections, but also for receiving and sending data. Both +passive and active mode are supported, although all sockets +are initialized as passive.</p></div> +<div class="sect1"> +<h2 id="_tcp_transport">TCP transport</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The TCP transport is a thin wrapper around <code>gen_tcp</code>.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_ssl_transport">SSL transport</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The SSL transport is a thin wrapper around <code>ssl</code>.</p></div> +<div class="paragraph"><p>Ranch depends on <code>ssl</code> by default so any necessary +dependencies will start when Ranch is started. It is +possible to remove the dependency when the SSL transport +will not be used. Refer to your release build tool’s +documentation for more information.</p></div> +<div class="paragraph"><p>When embedding Ranch listeners that have an SSL transport, +your application must depend on the <code>ssl</code> application for +proper behavior.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_sending_and_receiving_data">Sending and receiving data</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This section assumes that <code>Transport</code> is a valid transport handler +(like <code>ranch_tcp</code> or <code>ranch_ssl</code>) and <code>Socket</code> is a connected +socket obtained through the listener.</p></div> +<div class="paragraph"><p>You can send data to a socket by calling the <code>Transport:send/2</code> +function. The data can be given as <code>iodata()</code>, which is defined as +<code>binary() | iolist()</code>. All the following calls will work:</p></div> +<div class="listingblock"> +<div class="title">Sending data to the socket</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">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"Ranch is cool!"</span><span style="color: #990000">>></span>)<span style="color: #990000">.</span> +<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #FF0000">"Ranch is cool!"</span>)<span style="color: #990000">.</span> +<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, [<span style="color: #FF0000">"Ranch"</span>, [<span style="color: #FF0000">"is"</span>, <span style="color: #FF0000">"cool!"</span>]])<span style="color: #990000">.</span> +<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">send</span></span>(<span style="color: #009900">Socket</span>, [<span style="color: #FF0000">"Ranch"</span>, [<span style="color: #990000"><<</span><span style="color: #FF0000">"is"</span><span style="color: #990000">>></span>, <span style="color: #FF0000">"cool!"</span>]])<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>You can receive data either in passive or in active mode. Passive mode +means that you will perform a blocking <code>Transport:recv/3</code> call, while +active mode means that you will receive the data as a message.</p></div> +<div class="paragraph"><p>By default, all data will be received as binary. It is possible to +receive data as strings, although this is not recommended as binaries +are a more efficient construct, especially for binary protocols.</p></div> +<div class="paragraph"><p>Receiving data using passive mode requires a single function call. The +first argument is the socket, and the third argument is a timeout duration +before the call returns with <code>{error, timeout}</code>.</p></div> +<div class="paragraph"><p>The second argument is the amount of data in bytes that we want to receive. +The function will wait for data until it has received exactly this amount. +If you are not expecting a precise size, you can specify 0 which will make +this call return as soon as data was read, regardless of its size.</p></div> +<div class="listingblock"> +<div class="title">Receiving data from the socket in passive mode</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: #FF6600">ok</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">recv</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #993399">0</span>, <span style="color: #993399">5000</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Active mode requires you to inform the socket that you want to receive +data as a message and to write the code to actually receive it.</p></div> +<div class="paragraph"><p>There are two kinds of active modes: <code>{active, once}</code> and +<code>{active, true}</code>. The first will send a single message before going +back to passive mode; the second will send messages indefinitely. +We recommend not using the <code>{active, true}</code> mode as it could quickly +flood your process mailbox. It’s better to keep the data in the socket +and read it only when required.</p></div> +<div class="paragraph"><p>Three different messages can be received:</p></div> +<div class="ulist"><ul> +<li> +<p> +<code>{OK, Socket, Data}</code> +</p> +</li> +<li> +<p> +<code>{Closed, Socket}</code> +</p> +</li> +<li> +<p> +<code>{Error, Socket, Reason}</code> +</p> +</li> +</ul></div> +<div class="paragraph"><p>The value of <code>OK</code>, <code>Closed</code> and <code>Error</code> can be different +depending on the transport being used. To be able to properly match +on them you must first call the <code>Transport:messages/0</code> function.</p></div> +<div class="listingblock"> +<div class="title">Retrieving the transport’s active message identifiers</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">OK</span>, <span style="color: #009900">Closed</span>, <span style="color: #009900">Error</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">messages</span></span>()<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>To start receiving messages you will need to call the <code>Transport:setopts/2</code> +function, and do so every time you want to receive data.</p></div> +<div class="listingblock"> +<div class="title">Receiving messages from the socket in active mode</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">OK</span>, <span style="color: #009900">Closed</span>, <span style="color: #009900">Error</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">messages</span></span>(), +<span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">setopts</span></span>(<span style="color: #009900">Socket</span>, [{<span style="color: #FF6600">active</span>, <span style="color: #FF6600">once</span>}]), +<span style="font-weight: bold"><span style="color: #0000FF">receive</span></span> + {<span style="color: #009900">OK</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Data</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"data received: ~p~n"</span>, [<span style="color: #009900">Data</span>]); + {<span style="color: #009900">Closed</span>, <span style="color: #009900">Socket</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"socket got closed!~n"</span>); + {<span style="color: #009900">Error</span>, <span style="color: #009900">Socket</span>, <span style="color: #009900">Reason</span>} <span style="color: #990000">-></span> + <span style="font-weight: bold"><span style="color: #000000">io:format</span></span>(<span style="color: #FF0000">"error happened: ~p~n"</span>, [<span style="color: #009900">Reason</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 easily integrate active sockets with existing Erlang code as all +you really need is just a few more clauses when receiving messages.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_sending_files">Sending files</h2> +<div class="sectionbody"> +<div class="paragraph"><p>As in the previous section it is assumed <code>Transport</code> is a valid transport +handler and <code>Socket</code> is a connected socket obtained through the listener.</p></div> +<div class="paragraph"><p>To send a whole file, with name <code>Filename</code>, over a socket:</p></div> +<div class="listingblock"> +<div class="title">Sending a file by filename</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: #FF6600">ok</span>, <span style="color: #009900">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Filename</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>Or part of a file, with <code>Offset</code> greater than or equal to 0, <code>Bytes</code> number of +bytes and chunks of size <code>ChunkSize</code>:</p></div> +<div class="listingblock"> +<div class="title">Sending part of a file by filename in chunks</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">Opts</span> <span style="color: #990000">=</span> [{<span style="color: #FF6600">chunk_size</span>, <span style="color: #009900">ChunkSize</span>}], +{<span style="color: #FF6600">ok</span>, <span style="color: #009900">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">Filename</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Bytes</span>, <span style="color: #009900">Opts</span>)<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>To improve efficiency when sending multiple parts of the same file it is also +possible to use a file descriptor opened in raw mode:</p></div> +<div class="listingblock"> +<div class="title">Sending a file opened in raw mode</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: #FF6600">ok</span>, <span style="color: #009900">RawFile</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">file:open</span></span>(<span style="color: #009900">Filename</span>, [<span style="color: #FF6600">raw</span>, <span style="color: #FF6600">read</span>, <span style="font-weight: bold"><span style="color: #000080">binary</span></span>]), +{<span style="color: #FF6600">ok</span>, <span style="color: #009900">SentBytes</span>} <span style="color: #990000">=</span> <span style="color: #009900">Transport</span><span style="color: #990000">:</span><span style="font-weight: bold"><span style="color: #000000">sendfile</span></span>(<span style="color: #009900">Socket</span>, <span style="color: #009900">RawFile</span>, <span style="color: #009900">Offset</span>, <span style="color: #009900">Bytes</span>, <span style="color: #009900">Opts</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_writing_a_transport_handler">Writing a transport handler</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A transport handler is a module implementing the <code>ranch_transport</code> behavior. +It defines a certain number of callbacks that must be written in order to +allow transparent usage of the transport handler.</p></div> +<div class="paragraph"><p>The behavior doesn’t define the socket options available when opening a +socket. These do not need to be common to all transports as it’s easy enough +to write different initialization functions for the different transports that +will be used. With one exception though. The <code>setopts/2</code> function <strong>must</strong> +implement the <code>{active, once}</code> and the <code>{active, true}</code> options.</p></div> +<div class="paragraph"><p>If the transport handler doesn’t have a native implementation of <code>sendfile/5</code> a +fallback is available, <code>ranch_transport:sendfile/6</code>. The extra first argument +is the transport’s module. See <code>ranch_ssl</code> for an example.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> diff --git a/docs/en/ranch/1.3/manual/index.html b/docs/en/ranch/1.3/manual/index.html index a1122ab0..c0d63cf2 100644 --- a/docs/en/ranch/1.3/manual/index.html +++ b/docs/en/ranch/1.3/manual/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Ranch Function Reference</title> @@ -67,38 +67,38 @@ <h1 class="lined-header"><span>Ranch Function Reference</span></h1> -<div class="ulist"><ul>
-<li>
-<p>
-<a href="ranch_app">ranch(7)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch">ranch(3)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch_protocol">ranch_protocol(3)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch_ssl">ranch_ssl(3)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch_tcp">ranch_tcp(3)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch_transport">ranch_transport(3)</a>
-</p>
-</li>
-</ul></div>
+<div class="ulist"><ul> +<li> +<p> +<a href="ranch_app">ranch(7)</a> +</p> +</li> +<li> +<p> +<a href="ranch">ranch(3)</a> +</p> +</li> +<li> +<p> +<a href="ranch_protocol">ranch_protocol(3)</a> +</p> +</li> +<li> +<p> +<a href="ranch_ssl">ranch_ssl(3)</a> +</p> +</li> +<li> +<p> +<a href="ranch_tcp">ranch_tcp(3)</a> +</p> +</li> +<li> +<p> +<a href="ranch_transport">ranch_transport(3)</a> +</p> +</li> +</ul></div> diff --git a/docs/en/ranch/1.3/manual/ranch/index.html b/docs/en/ranch/1.3/manual/ranch/index.html index 5c2f9f3e..b8b4b35d 100644 --- a/docs/en/ranch/1.3/manual/ranch/index.html +++ b/docs/en/ranch/1.3/manual/ranch/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch(3)</title> @@ -67,567 +67,567 @@ <h1 class="lined-header"><span>ranch(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>ranch - socket acceptor pool</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>ranch</code> module provides functions for starting and
-manipulating Ranch listeners.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_max_conns_non_neg_integer_infinity">max_conns() = non_neg_integer() | infinity</h3>
-<div class="paragraph"><p>Maximum number of connections allowed on this listener.</p></div>
-<div class="paragraph"><p>This is a soft limit. The actual number of connections
-might be slightly above the limit due to concurrency
-when accepting new connections. Some connections may
-also be removed from this count explicitly by the user
-code.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_opt">opt()</h3>
-<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">opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">ack_timeout</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()}
- | {<span style="color: #FF6600">connection_type</span>, <span style="color: #FF6600">worker</span> | <span style="color: #FF6600">supervisor</span>}
- | {<span style="color: #FF6600">max_connections</span>, <span style="font-weight: bold"><span style="color: #000000">max_conns</span></span>()}
- | {<span style="color: #FF6600">num_acceptors</span>, <span style="font-weight: bold"><span style="color: #000000">pos_integer</span></span>()}
- | {<span style="color: #000080">shutdown</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>() | <span style="color: #FF6600">brutal_kill</span>}
- | {<span style="color: #FF6600">socket</span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>Ranch-specific transport options.</p></div>
-<div class="paragraph"><p>These options are not passed on to the transports.
-They are used by Ranch while setting up the listeners.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_ref_any">ref() = any()</h3>
-<div class="paragraph"><p>Unique name used to refer to a listener.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_option_descriptions">Option descriptions</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>None of the options are required.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-ack_timeout (5000)
-</dt>
-<dd>
-<p>
- Maximum allowed time for the <code>ranch:accept_ack/1</code> call to finish.
-</p>
-</dd>
-<dt class="hdlist1">
-connection_type (worker)
-</dt>
-<dd>
-<p>
- Type of process that will handle the connection.
-</p>
-</dd>
-<dt class="hdlist1">
-max_connections (1024)
-</dt>
-<dd>
-<p>
- Maximum number of active connections. Soft limit. Using <code>infinity</code> will disable the limit entirely.
-</p>
-</dd>
-<dt class="hdlist1">
-num_acceptors (10)
-</dt>
-<dd>
-<p>
- Number of processes that accept connections.
-</p>
-</dd>
-<dt class="hdlist1">
-shutdown (5000)
-</dt>
-<dd>
-<p>
- Maximum allowed time for children to stop on listener shutdown.
-</p>
-</dd>
-<dt class="hdlist1">
-socket
-</dt>
-<dd>
-<p>
- Listening socket opened externally to be used instead of calling <code>Transport:listen/1</code>.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exports">Exports</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_accept_ack_ref_8594_ok">accept_ack(Ref) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Acknowledge that the connection is accepted.</p></div>
-<div class="paragraph"><p>This function MUST be used by a connection process to inform
-Ranch that it initialized properly and let it perform any
-additional operations before the socket can be safely used.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_child_spec_ref_numacceptors_transport_transopts_protocol_protoopts_8594_supervisor_child_spec">child_spec(Ref, NumAcceptors, Transport, TransOpts, Protocol, ProtoOpts) → supervisor:child_spec()</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-NumAcceptors = non_neg_integer()
-</dt>
-<dd>
-<p>
-Number of acceptor processes.
-</p>
-</dd>
-<dt class="hdlist1">
-Transport = module()
-</dt>
-<dd>
-<p>
-Transport module.
-</p>
-</dd>
-<dt class="hdlist1">
-TransOpts = any()
-</dt>
-<dd>
-<p>
-Transport options.
-</p>
-</dd>
-<dt class="hdlist1">
-Protocol = module()
-</dt>
-<dd>
-<p>
-Protocol module.
-</p>
-</dd>
-<dt class="hdlist1">
-ProtoOpts = any()
-</dt>
-<dd>
-<p>
-Protocol options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return child specifications for a new listener.</p></div>
-<div class="paragraph"><p>This function can be used to embed a listener directly
-in an application instead of letting Ranch handle it.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_get_addr_ref_8594_ip_port">get_addr(Ref) → {IP, Port}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-IP = inet:ip_address()
-</dt>
-<dd>
-<p>
-IP of the interface used by this listener.
-</p>
-</dd>
-<dt class="hdlist1">
-Port = inet:port_number()
-</dt>
-<dd>
-<p>
-Port number used by this listener.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the IP address and port for the given listener.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_get_max_connections_ref_8594_maxconns">get_max_connections(Ref) → MaxConns</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-MaxConns = max_conns()
-</dt>
-<dd>
-<p>
-Current maximum number of connections.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the max number of connections allowed for the given listener.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_get_port_ref_8594_port">get_port(Ref) → Port</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-Port = inet:port_number()
-</dt>
-<dd>
-<p>
-Port number used by this listener.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the port for the given listener.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_get_protocol_options_ref_8594_protoopts">get_protocol_options(Ref) → ProtoOpts</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-ProtoOpts = any()
-</dt>
-<dd>
-<p>
-Current protocol options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the protocol options set for the given listener.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_info_8594_ref_key_value">info() → [{Ref, [{Key, Value}]}]</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-Key = atom()
-</dt>
-<dd>
-<p>
-Information key.
-</p>
-</dd>
-<dt class="hdlist1">
-Value = any()
-</dt>
-<dd>
-<p>
-Information value.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return detailed information about all Ranch listeners.</p></div>
-<div class="paragraph"><p>The following keys are defined:</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-pid
-</dt>
-<dd>
-<p>
-Pid of the listener’s top-level supervisor.
-</p>
-</dd>
-<dt class="hdlist1">
-ip
-</dt>
-<dd>
-<p>
-Interface Ranch listens on.
-</p>
-</dd>
-<dt class="hdlist1">
-port
-</dt>
-<dd>
-<p>
-Port number Ranch listens on.
-</p>
-</dd>
-<dt class="hdlist1">
-num_acceptors
-</dt>
-<dd>
-<p>
-Number of acceptor processes.
-</p>
-</dd>
-<dt class="hdlist1">
-max_connections
-</dt>
-<dd>
-<p>
-Maximum number of connections.
-</p>
-</dd>
-<dt class="hdlist1">
-active_connections
-</dt>
-<dd>
-<p>
-Number of active connections.
-</p>
-</dd>
-<dt class="hdlist1">
-all_connections
-</dt>
-<dd>
-<p>
-Number of connections, including those removed from the count.
-</p>
-</dd>
-<dt class="hdlist1">
-transport
-</dt>
-<dd>
-<p>
-Transport module.
-</p>
-</dd>
-<dt class="hdlist1">
-transport_options
-</dt>
-<dd>
-<p>
-Transport options.
-</p>
-</dd>
-<dt class="hdlist1">
-protocol
-</dt>
-<dd>
-<p>
-Protocol module.
-</p>
-</dd>
-<dt class="hdlist1">
-protocol_options
-</dt>
-<dd>
-<p>
-Protocol options.
-</p>
-</dd>
-</dl></div>
-</div>
-<div class="sect2">
-<h3 id="_procs_ref_acceptors_connections_8594_pid">procs(Ref, acceptors | connections) → [pid()]</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return all acceptor or connection processes for one listener.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_remove_connection_ref_8594_ok">remove_connection(Ref) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Do not count this connection when limiting the number of connections.</p></div>
-<div class="paragraph"><p>You can use this function for long-running connection processes
-which spend most of their time idling rather than consuming
-resources. This allows Ranch to accept a lot more connections
-without sacrificing the latency of the system.</p></div>
-<div class="paragraph"><p>This function may only be called from a connection process.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_set_max_connections_ref_maxconns_8594_ok">set_max_connections(Ref, MaxConns) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-MaxConns = max_conns()
-</dt>
-<dd>
-<p>
-New maximum number of connections.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Set the max number of connections for the given listener.</p></div>
-<div class="paragraph"><p>The change will be applied immediately. If the new value is
-smaller than the previous one, Ranch will not kill the extra
-connections, but will wait for them to terminate properly.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_set_protocol_options_ref_protoopts_8594_ok">set_protocol_options(Ref, ProtoOpts) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-ProtoOpts = any()
-</dt>
-<dd>
-<p>
-New protocol options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Set the protocol options for the given listener.</p></div>
-<div class="paragraph"><p>The change will be applied immediately for all new connections.
-Old connections will not receive the new options.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_start_listener_ref_numacceptors_transport_transopts_protocol_protoopts_8594_ok_pid_error_badarg">start_listener(Ref, NumAcceptors, Transport, TransOpts, Protocol, ProtoOpts) → {ok, pid()} | {error, badarg}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-NumAcceptors = non_neg_integer()
-</dt>
-<dd>
-<p>
-Number of acceptor processes.
-</p>
-</dd>
-<dt class="hdlist1">
-Transport = module()
-</dt>
-<dd>
-<p>
-Transport module.
-</p>
-</dd>
-<dt class="hdlist1">
-TransOpts = any()
-</dt>
-<dd>
-<p>
-Transport options.
-</p>
-</dd>
-<dt class="hdlist1">
-Protocol = module()
-</dt>
-<dd>
-<p>
-Protocol module.
-</p>
-</dd>
-<dt class="hdlist1">
-ProtoOpts = any()
-</dt>
-<dd>
-<p>
-Protocol options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Start listening for connections using the given transport
-and protocol. Returns the pid for this listener’s supervisor.</p></div>
-<div class="paragraph"><p>There are additional transport options that apply
-regardless of transport. They allow configuring how the
-connections are supervised, rate limited and more. Please
-consult the previous section for more details.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_stop_listener_ref_8594_ok_error_not_found">stop_listener(Ref) → ok | {error, not_found}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Stop the given listener.</p></div>
-<div class="paragraph"><p>The listener is stopped gracefully, first by closing the
-listening port, then by stopping the connection processes.
-These processes are stopped according to the <code>shutdown</code>
-transport option, which may be set to brutally kill all
-connection processes or give them some time to stop properly.</p></div>
-<div class="paragraph"><p>This function does not return until the listener is
-completely stopped.</p></div>
-</div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch - socket acceptor pool</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch</code> module provides functions for starting and +manipulating Ranch listeners.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_max_conns_non_neg_integer_infinity">max_conns() = non_neg_integer() | infinity</h3> +<div class="paragraph"><p>Maximum number of connections allowed on this listener.</p></div> +<div class="paragraph"><p>This is a soft limit. The actual number of connections +might be slightly above the limit due to concurrency +when accepting new connections. Some connections may +also be removed from this count explicitly by the user +code.</p></div> +</div> +<div class="sect2"> +<h3 id="_opt">opt()</h3> +<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">opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">ack_timeout</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()} + | {<span style="color: #FF6600">connection_type</span>, <span style="color: #FF6600">worker</span> | <span style="color: #FF6600">supervisor</span>} + | {<span style="color: #FF6600">max_connections</span>, <span style="font-weight: bold"><span style="color: #000000">max_conns</span></span>()} + | {<span style="color: #FF6600">num_acceptors</span>, <span style="font-weight: bold"><span style="color: #000000">pos_integer</span></span>()} + | {<span style="color: #000080">shutdown</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>() | <span style="color: #FF6600">brutal_kill</span>} + | {<span style="color: #FF6600">socket</span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Ranch-specific transport options.</p></div> +<div class="paragraph"><p>These options are not passed on to the transports. +They are used by Ranch while setting up the listeners.</p></div> +</div> +<div class="sect2"> +<h3 id="_ref_any">ref() = any()</h3> +<div class="paragraph"><p>Unique name used to refer to a listener.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_option_descriptions">Option descriptions</h2> +<div class="sectionbody"> +<div class="paragraph"><p>None of the options are required.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +ack_timeout (5000) +</dt> +<dd> +<p> + Maximum allowed time for the <code>ranch:accept_ack/1</code> call to finish. +</p> +</dd> +<dt class="hdlist1"> +connection_type (worker) +</dt> +<dd> +<p> + Type of process that will handle the connection. +</p> +</dd> +<dt class="hdlist1"> +max_connections (1024) +</dt> +<dd> +<p> + Maximum number of active connections. Soft limit. Using <code>infinity</code> will disable the limit entirely. +</p> +</dd> +<dt class="hdlist1"> +num_acceptors (10) +</dt> +<dd> +<p> + Number of processes that accept connections. +</p> +</dd> +<dt class="hdlist1"> +shutdown (5000) +</dt> +<dd> +<p> + Maximum allowed time for children to stop on listener shutdown. +</p> +</dd> +<dt class="hdlist1"> +socket +</dt> +<dd> +<p> + Listening socket opened externally to be used instead of calling <code>Transport:listen/1</code>. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_accept_ack_ref_8594_ok">accept_ack(Ref) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Acknowledge that the connection is accepted.</p></div> +<div class="paragraph"><p>This function MUST be used by a connection process to inform +Ranch that it initialized properly and let it perform any +additional operations before the socket can be safely used.</p></div> +</div> +<div class="sect2"> +<h3 id="_child_spec_ref_numacceptors_transport_transopts_protocol_protoopts_8594_supervisor_child_spec">child_spec(Ref, NumAcceptors, Transport, TransOpts, Protocol, ProtoOpts) → supervisor:child_spec()</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +NumAcceptors = non_neg_integer() +</dt> +<dd> +<p> +Number of acceptor processes. +</p> +</dd> +<dt class="hdlist1"> +Transport = module() +</dt> +<dd> +<p> +Transport module. +</p> +</dd> +<dt class="hdlist1"> +TransOpts = any() +</dt> +<dd> +<p> +Transport options. +</p> +</dd> +<dt class="hdlist1"> +Protocol = module() +</dt> +<dd> +<p> +Protocol module. +</p> +</dd> +<dt class="hdlist1"> +ProtoOpts = any() +</dt> +<dd> +<p> +Protocol options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return child specifications for a new listener.</p></div> +<div class="paragraph"><p>This function can be used to embed a listener directly +in an application instead of letting Ranch handle it.</p></div> +</div> +<div class="sect2"> +<h3 id="_get_addr_ref_8594_ip_port">get_addr(Ref) → {IP, Port}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +IP = inet:ip_address() +</dt> +<dd> +<p> +IP of the interface used by this listener. +</p> +</dd> +<dt class="hdlist1"> +Port = inet:port_number() +</dt> +<dd> +<p> +Port number used by this listener. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the IP address and port for the given listener.</p></div> +</div> +<div class="sect2"> +<h3 id="_get_max_connections_ref_8594_maxconns">get_max_connections(Ref) → MaxConns</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +MaxConns = max_conns() +</dt> +<dd> +<p> +Current maximum number of connections. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the max number of connections allowed for the given listener.</p></div> +</div> +<div class="sect2"> +<h3 id="_get_port_ref_8594_port">get_port(Ref) → Port</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +Port = inet:port_number() +</dt> +<dd> +<p> +Port number used by this listener. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the port for the given listener.</p></div> +</div> +<div class="sect2"> +<h3 id="_get_protocol_options_ref_8594_protoopts">get_protocol_options(Ref) → ProtoOpts</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +ProtoOpts = any() +</dt> +<dd> +<p> +Current protocol options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the protocol options set for the given listener.</p></div> +</div> +<div class="sect2"> +<h3 id="_info_8594_ref_key_value">info() → [{Ref, [{Key, Value}]}]</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +Key = atom() +</dt> +<dd> +<p> +Information key. +</p> +</dd> +<dt class="hdlist1"> +Value = any() +</dt> +<dd> +<p> +Information value. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return detailed information about all Ranch listeners.</p></div> +<div class="paragraph"><p>The following keys are defined:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +pid +</dt> +<dd> +<p> +Pid of the listener’s top-level supervisor. +</p> +</dd> +<dt class="hdlist1"> +ip +</dt> +<dd> +<p> +Interface Ranch listens on. +</p> +</dd> +<dt class="hdlist1"> +port +</dt> +<dd> +<p> +Port number Ranch listens on. +</p> +</dd> +<dt class="hdlist1"> +num_acceptors +</dt> +<dd> +<p> +Number of acceptor processes. +</p> +</dd> +<dt class="hdlist1"> +max_connections +</dt> +<dd> +<p> +Maximum number of connections. +</p> +</dd> +<dt class="hdlist1"> +active_connections +</dt> +<dd> +<p> +Number of active connections. +</p> +</dd> +<dt class="hdlist1"> +all_connections +</dt> +<dd> +<p> +Number of connections, including those removed from the count. +</p> +</dd> +<dt class="hdlist1"> +transport +</dt> +<dd> +<p> +Transport module. +</p> +</dd> +<dt class="hdlist1"> +transport_options +</dt> +<dd> +<p> +Transport options. +</p> +</dd> +<dt class="hdlist1"> +protocol +</dt> +<dd> +<p> +Protocol module. +</p> +</dd> +<dt class="hdlist1"> +protocol_options +</dt> +<dd> +<p> +Protocol options. +</p> +</dd> +</dl></div> +</div> +<div class="sect2"> +<h3 id="_procs_ref_acceptors_connections_8594_pid">procs(Ref, acceptors | connections) → [pid()]</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return all acceptor or connection processes for one listener.</p></div> +</div> +<div class="sect2"> +<h3 id="_remove_connection_ref_8594_ok">remove_connection(Ref) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Do not count this connection when limiting the number of connections.</p></div> +<div class="paragraph"><p>You can use this function for long-running connection processes +which spend most of their time idling rather than consuming +resources. This allows Ranch to accept a lot more connections +without sacrificing the latency of the system.</p></div> +<div class="paragraph"><p>This function may only be called from a connection process.</p></div> +</div> +<div class="sect2"> +<h3 id="_set_max_connections_ref_maxconns_8594_ok">set_max_connections(Ref, MaxConns) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +MaxConns = max_conns() +</dt> +<dd> +<p> +New maximum number of connections. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Set the max number of connections for the given listener.</p></div> +<div class="paragraph"><p>The change will be applied immediately. If the new value is +smaller than the previous one, Ranch will not kill the extra +connections, but will wait for them to terminate properly.</p></div> +</div> +<div class="sect2"> +<h3 id="_set_protocol_options_ref_protoopts_8594_ok">set_protocol_options(Ref, ProtoOpts) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +ProtoOpts = any() +</dt> +<dd> +<p> +New protocol options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Set the protocol options for the given listener.</p></div> +<div class="paragraph"><p>The change will be applied immediately for all new connections. +Old connections will not receive the new options.</p></div> +</div> +<div class="sect2"> +<h3 id="_start_listener_ref_numacceptors_transport_transopts_protocol_protoopts_8594_ok_pid_error_badarg">start_listener(Ref, NumAcceptors, Transport, TransOpts, Protocol, ProtoOpts) → {ok, pid()} | {error, badarg}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +NumAcceptors = non_neg_integer() +</dt> +<dd> +<p> +Number of acceptor processes. +</p> +</dd> +<dt class="hdlist1"> +Transport = module() +</dt> +<dd> +<p> +Transport module. +</p> +</dd> +<dt class="hdlist1"> +TransOpts = any() +</dt> +<dd> +<p> +Transport options. +</p> +</dd> +<dt class="hdlist1"> +Protocol = module() +</dt> +<dd> +<p> +Protocol module. +</p> +</dd> +<dt class="hdlist1"> +ProtoOpts = any() +</dt> +<dd> +<p> +Protocol options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Start listening for connections using the given transport +and protocol. Returns the pid for this listener’s supervisor.</p></div> +<div class="paragraph"><p>There are additional transport options that apply +regardless of transport. They allow configuring how the +connections are supervised, rate limited and more. Please +consult the previous section for more details.</p></div> +</div> +<div class="sect2"> +<h3 id="_stop_listener_ref_8594_ok_error_not_found">stop_listener(Ref) → ok | {error, not_found}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Stop the given listener.</p></div> +<div class="paragraph"><p>The listener is stopped gracefully, first by closing the +listening port, then by stopping the connection processes. +These processes are stopped according to the <code>shutdown</code> +transport option, which may be set to brutally kill all +connection processes or give them some time to stop properly.</p></div> +<div class="paragraph"><p>This function does not return until the listener is +completely stopped.</p></div> +</div> +</div> +</div> diff --git a/docs/en/ranch/1.3/manual/ranch_app/index.html b/docs/en/ranch/1.3/manual/ranch_app/index.html index 3c834556..2ad98222 100644 --- a/docs/en/ranch/1.3/manual/ranch_app/index.html +++ b/docs/en/ranch/1.3/manual/ranch_app/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch(7)</title> @@ -67,41 +67,41 @@ <h1 class="lined-header"><span>ranch(7)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>ranch - Socket acceptor pool for TCP protocols.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_dependencies">Dependencies</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>ranch</code> application depends on the <code>ssl</code> application to
-start. It is used for handling secure connections, when the
-transport is <code>ranch_ssl</code>. It can be disabled if SSL is not
-used.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_environment">Environment</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>ranch</code> application defines one application environment
-configuration parameter.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-profile (false)
-</dt>
-<dd>
-<p>
- When enabled, Ranch will start <code>eprof</code> profiling automatically.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>You can use the <code>ranch_app:profile_output/0</code> function to stop
-profiling and output the results to the files <em>procs.profile</em>
-and <em>total.profile</em>. Do not use in production.</p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch - Socket acceptor pool for TCP protocols.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_dependencies">Dependencies</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch</code> application depends on the <code>ssl</code> application to +start. It is used for handling secure connections, when the +transport is <code>ranch_ssl</code>. It can be disabled if SSL is not +used.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_environment">Environment</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch</code> application defines one application environment +configuration parameter.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +profile (false) +</dt> +<dd> +<p> + When enabled, Ranch will start <code>eprof</code> profiling automatically. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>You can use the <code>ranch_app:profile_output/0</code> function to stop +profiling and output the results to the files <em>procs.profile</em> +and <em>total.profile</em>. Do not use in production.</p></div> +</div> +</div> diff --git a/docs/en/ranch/1.3/manual/ranch_protocol/index.html b/docs/en/ranch/1.3/manual/ranch_protocol/index.html index 59f945d2..ce82c3f0 100644 --- a/docs/en/ranch/1.3/manual/ranch_protocol/index.html +++ b/docs/en/ranch/1.3/manual/ranch_protocol/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch_protocol(3)</title> @@ -67,83 +67,83 @@ <h1 class="lined-header"><span>ranch_protocol(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>ranch_protocol - behaviour for protocol modules</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>ranch_protocol</code> behaviour defines the interface used
-by Ranch protocols.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>None.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_callbacks">Callbacks</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_start_link_ref_socket_transport_protoopts_8594_ok_pid_ok_pid_pid">start_link(Ref, Socket, Transport, ProtoOpts) → {ok, pid()} | {ok, pid(), pid()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Ref = ranch:ref()
-</dt>
-<dd>
-<p>
-Listener name.
-</p>
-</dd>
-<dt class="hdlist1">
-Socket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-Transport = module()
-</dt>
-<dd>
-<p>
-Transport module for this socket.
-</p>
-</dd>
-<dt class="hdlist1">
-ProtoOpts = any()
-</dt>
-<dd>
-<p>
-Protocol options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Start a new connection process for the given socket.</p></div>
-<div class="paragraph"><p>The only purpose of this callback is to start a process that
-will handle the socket. It must spawn the process, link and
-then return the new pid. This function will always be called
-from inside a supervisor.</p></div>
-<div class="paragraph"><p>This callback can also return two pids. The first pid is the
-pid of the process that will be supervised. The second pid is
-the pid of the process that will receive ownership of the
-socket. This second process must be a child of the first. This
-form is only available when <code>connection_type</code> is set to
-<code>supervisor</code>.</p></div>
-<div class="paragraph"><p>If any other value is returned, the supervisor will close the
-socket and assume no process has been started.</p></div>
-<div class="paragraph"><p>Do not perform any operations in this callback, as this would
-block the supervisor responsible for starting connection
-processes and degrade performance severely.</p></div>
-</div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch_protocol - behaviour for protocol modules</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch_protocol</code> behaviour defines the interface used +by Ranch protocols.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="paragraph"><p>None.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_callbacks">Callbacks</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_start_link_ref_socket_transport_protoopts_8594_ok_pid_ok_pid_pid">start_link(Ref, Socket, Transport, ProtoOpts) → {ok, pid()} | {ok, pid(), pid()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Ref = ranch:ref() +</dt> +<dd> +<p> +Listener name. +</p> +</dd> +<dt class="hdlist1"> +Socket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +Transport = module() +</dt> +<dd> +<p> +Transport module for this socket. +</p> +</dd> +<dt class="hdlist1"> +ProtoOpts = any() +</dt> +<dd> +<p> +Protocol options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Start a new connection process for the given socket.</p></div> +<div class="paragraph"><p>The only purpose of this callback is to start a process that +will handle the socket. It must spawn the process, link and +then return the new pid. This function will always be called +from inside a supervisor.</p></div> +<div class="paragraph"><p>This callback can also return two pids. The first pid is the +pid of the process that will be supervised. The second pid is +the pid of the process that will receive ownership of the +socket. This second process must be a child of the first. This +form is only available when <code>connection_type</code> is set to +<code>supervisor</code>.</p></div> +<div class="paragraph"><p>If any other value is returned, the supervisor will close the +socket and assume no process has been started.</p></div> +<div class="paragraph"><p>Do not perform any operations in this callback, as this would +block the supervisor responsible for starting connection +processes and degrade performance severely.</p></div> +</div> +</div> +</div> diff --git a/docs/en/ranch/1.3/manual/ranch_ssl/index.html b/docs/en/ranch/1.3/manual/ranch_ssl/index.html index d923f172..3a466dee 100644 --- a/docs/en/ranch/1.3/manual/ranch_ssl/index.html +++ b/docs/en/ranch/1.3/manual/ranch_ssl/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch_ssl(3)</title> @@ -67,385 +67,385 @@ <h1 class="lined-header"><span>ranch_ssl(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>ranch_ssl - SSL transport module</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>ranch_ssl</code> module implements an SSL Ranch transport.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_ssl_opt">ssl_opt()</h3>
-<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">ssl_opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">alpn_preferred_protocols</span>, [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()]}
- | {<span style="color: #FF6600">beast_mitigation</span>, <span style="color: #FF6600">one_n_minus_one</span> | <span style="color: #FF6600">zero_n</span> | <span style="color: #FF6600">disabled</span>}
- | {<span style="color: #FF6600">cacertfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
- | {<span style="color: #FF6600">cacerts</span>, [<span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()]}
- | {<span style="color: #FF6600">cert</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()}
- | {<span style="color: #FF6600">certfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
- | {<span style="color: #FF6600">ciphers</span>, [<span style="font-weight: bold"><span style="color: #000000">ssl:erl_cipher_suite</span></span>()] | <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
- | {<span style="color: #FF6600">client_renegotiation</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">crl_cache</span>, {<span style="font-weight: bold"><span style="color: #000000">module</span></span>(), {<span style="color: #FF6600">internal</span> | <span style="font-weight: bold"><span style="color: #000000">any</span></span>(), <span style="font-weight: bold"><span style="color: #000080">list</span></span>()}}}
- | {<span style="color: #FF6600">crl_check</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() | <span style="color: #FF6600">peer</span> | <span style="color: #FF6600">best_effort</span>}
- | {<span style="color: #FF6600">depth</span>, <span style="color: #993399">0</span><span style="color: #990000">..</span><span style="color: #993399">255</span>}
- | {<span style="color: #FF6600">dh</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()}
- | {<span style="color: #FF6600">dhfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
- | {<span style="color: #FF6600">fail_if_no_peer_cert</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">hibernate_after</span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>() | <span style="color: #000080">undefined</span>}
- | {<span style="color: #FF6600">honor_cipher_order</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">key</span>, {<span style="color: #FF6600">'RSAPrivateKey'</span> | <span style="color: #FF6600">'DSAPrivateKey'</span> | <span style="color: #FF6600">'PrivateKeyInfo'</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()}}
- | {<span style="color: #FF6600">keyfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
- | {<span style="color: #FF6600">log_alert</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">next_protocols_advertised</span>, [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()]}
- | {<span style="color: #FF6600">padding_check</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">partial_chain</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(([<span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()]) <span style="color: #990000">-></span> {<span style="color: #FF6600">trusted_ca</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()} | <span style="color: #FF6600">unknown_ca</span>)}
- | {<span style="color: #FF6600">password</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
- | {<span style="color: #FF6600">psk_identity</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()}
- | {<span style="color: #FF6600">reuse_session</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>()}
- | {<span style="color: #FF6600">reuse_sessions</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">secure_renegotiate</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">signature_algs</span>, [{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>(), <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()}]}
- | {<span style="color: #FF6600">sni_fun</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>()}
- | {<span style="color: #FF6600">sni_hosts</span>, [{<span style="font-weight: bold"><span style="color: #000000">string</span></span>(), <span style="font-weight: bold"><span style="color: #000000">ssl_opt</span></span>()}]}
- | {<span style="color: #FF6600">user_lookup_fun</span>, {<span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(), <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}}
- | {<span style="color: #FF6600">v2_hello_compatible</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">verify</span>, <span style="font-weight: bold"><span style="color: #000000">ssl:verify_type</span></span>()}
- | {<span style="color: #FF6600">verify_fun</span>, {<span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(), <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}}
- | {<span style="color: #FF6600">versions</span>, [<span style="font-weight: bold"><span style="color: #000080">atom</span></span>()]}<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>SSL-specific listen options.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_opt_ranch_tcp_opt_ssl_opt">opt() = ranch_tcp:opt() | ssl_opt()</h3>
-<div class="paragraph"><p>Listen options.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_opts_opt">opts() = [opt()]</h3>
-<div class="paragraph"><p>List of listen options.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_option_descriptions">Option descriptions</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Specifying a certificate is mandatory, either through the <code>cert</code>
-or the <code>certfile</code> option. None of the other options are required.</p></div>
-<div class="paragraph"><p>The default value is given next to the option name.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-alpn_preferred_protocols
-</dt>
-<dd>
-<p>
- Perform Application-Layer Protocol Negotiation with the given list of preferred protocols.
-</p>
-</dd>
-<dt class="hdlist1">
-beast_mitigation
-</dt>
-<dd>
-<p>
- Change the BEAST mitigation strategy for SSL-3.0 and TLS-1.0 to interoperate with legacy software.
-</p>
-</dd>
-<dt class="hdlist1">
-cacertfile
-</dt>
-<dd>
-<p>
- Path to PEM encoded trusted certificates file used to verify peer certificates.
-</p>
-</dd>
-<dt class="hdlist1">
-cacerts
-</dt>
-<dd>
-<p>
- List of DER encoded trusted certificates.
-</p>
-</dd>
-<dt class="hdlist1">
-cert
-</dt>
-<dd>
-<p>
- DER encoded user certificate.
-</p>
-</dd>
-<dt class="hdlist1">
-certfile
-</dt>
-<dd>
-<p>
- Path to the PEM encoded user certificate file. May also contain the private key.
-</p>
-</dd>
-<dt class="hdlist1">
-ciphers
-</dt>
-<dd>
-<p>
- List of ciphers that clients are allowed to use.
-</p>
-</dd>
-<dt class="hdlist1">
-client_renegotiation (true)
-</dt>
-<dd>
-<p>
- Whether to allow client-initiated renegotiation.
-</p>
-</dd>
-<dt class="hdlist1">
-crl_cache ({ssl_crl_cache, {internal, []}})
-</dt>
-<dd>
-<p>
- Customize the module used to cache Certificate Revocation Lists.
-</p>
-</dd>
-<dt class="hdlist1">
-crl_check (false)
-</dt>
-<dd>
-<p>
- Whether to perform CRL check on all certificates in the chain during validation.
-</p>
-</dd>
-<dt class="hdlist1">
-depth (1)
-</dt>
-<dd>
-<p>
- Maximum of intermediate certificates allowed in the certification path.
-</p>
-</dd>
-<dt class="hdlist1">
-dh
-</dt>
-<dd>
-<p>
- DER encoded Diffie-Hellman parameters.
-</p>
-</dd>
-<dt class="hdlist1">
-dhfile
-</dt>
-<dd>
-<p>
- Path to the PEM encoded Diffie-Hellman parameters file.
-</p>
-</dd>
-<dt class="hdlist1">
-fail_if_no_peer_cert (false)
-</dt>
-<dd>
-<p>
- Whether to refuse the connection if the client sends an empty certificate.
-</p>
-</dd>
-<dt class="hdlist1">
-hibernate_after (undefined)
-</dt>
-<dd>
-<p>
- Time in ms after which SSL socket processes go into hibernation to reduce memory usage.
-</p>
-</dd>
-<dt class="hdlist1">
-honor_cipher_order (false)
-</dt>
-<dd>
-<p>
- If true, use the server’s preference for cipher selection. If false, use the client’s preference.
-</p>
-</dd>
-<dt class="hdlist1">
-key
-</dt>
-<dd>
-<p>
- DER encoded user private key.
-</p>
-</dd>
-<dt class="hdlist1">
-keyfile
-</dt>
-<dd>
-<p>
- Path to the PEM encoded private key file, if different than the certfile.
-</p>
-</dd>
-<dt class="hdlist1">
-log_alert (true)
-</dt>
-<dd>
-<p>
- If false, error reports will not be displayed.
-</p>
-</dd>
-<dt class="hdlist1">
-next_protocols_advertised
-</dt>
-<dd>
-<p>
- List of protocols to send to the client if it supports the Next Protocol extension.
-</p>
-</dd>
-<dt class="hdlist1">
-nodelay (true)
-</dt>
-<dd>
-<p>
- Whether to enable TCP_NODELAY.
-</p>
-</dd>
-<dt class="hdlist1">
-padding_check
-</dt>
-<dd>
-<p>
- Allow disabling the block cipher padding check for TLS-1.0 to be able to interoperate with legacy software.
-</p>
-</dd>
-<dt class="hdlist1">
-partial_chain
-</dt>
-<dd>
-<p>
- Claim an intermediate CA in the chain as trusted.
-</p>
-</dd>
-<dt class="hdlist1">
-password
-</dt>
-<dd>
-<p>
- Password to the private key file, if password protected.
-</p>
-</dd>
-<dt class="hdlist1">
-psk_identity
-</dt>
-<dd>
-<p>
- Provide the given PSK identity hint to the client during the handshake.
-</p>
-</dd>
-<dt class="hdlist1">
-reuse_session
-</dt>
-<dd>
-<p>
- Custom policy to decide whether a session should be reused.
-</p>
-</dd>
-<dt class="hdlist1">
-reuse_sessions (false)
-</dt>
-<dd>
-<p>
- Whether to allow session reuse.
-</p>
-</dd>
-<dt class="hdlist1">
-secure_renegotiate (false)
-</dt>
-<dd>
-<p>
- Whether to reject renegotiation attempts that do not conform to RFC5746.
-</p>
-</dd>
-<dt class="hdlist1">
-signature_algs
-</dt>
-<dd>
-<p>
- The TLS signature algorithm extension may be used, from TLS 1.2, to negotiate which signature algorithm to use during the TLS handshake.
-</p>
-</dd>
-<dt class="hdlist1">
-sni_fun
-</dt>
-<dd>
-<p>
- Function called when the client requests a host using Server Name Indication. Returns options to apply.
-</p>
-</dd>
-<dt class="hdlist1">
-sni_hosts
-</dt>
-<dd>
-<p>
- Options to apply for the host that matches what the client requested with Server Name Indication.
-</p>
-</dd>
-<dt class="hdlist1">
-user_lookup_fun
-</dt>
-<dd>
-<p>
- Function called to determine the shared secret when using PSK, or provide parameters when using SRP.
-</p>
-</dd>
-<dt class="hdlist1">
-v2_hello_compatible
-</dt>
-<dd>
-<p>
- Accept clients that send hello messages in SSL-2.0 format while offering supported SSL/TLS versions.
-</p>
-</dd>
-<dt class="hdlist1">
-verify (verify_none)
-</dt>
-<dd>
-<p>
- Use <code>verify_peer</code> to request a certificate from the client.
-</p>
-</dd>
-<dt class="hdlist1">
-verify_fun
-</dt>
-<dd>
-<p>
- Custom policy to decide whether a client certificate is valid.
-</p>
-</dd>
-<dt class="hdlist1">
-versions
-</dt>
-<dd>
-<p>
- TLS protocol versions that will be supported.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Note that the client will not send a certificate unless the
-value for the <code>verify</code> option is set to <code>verify_peer</code>. This
-means that the <code>fail_if_no_peer_cert</code> only apply when combined
-with the <code>verify</code> option. The <code>verify_fun</code> option allows
-greater control over the client certificate validation.</p></div>
-<div class="paragraph"><p>The options <code>sni_fun</code> and <code>sni_hosts</code> are mutually exclusive.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exports">Exports</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>None.</p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch_ssl - SSL transport module</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch_ssl</code> module implements an SSL Ranch transport.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_ssl_opt">ssl_opt()</h3> +<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">ssl_opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">alpn_preferred_protocols</span>, [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()]} + | {<span style="color: #FF6600">beast_mitigation</span>, <span style="color: #FF6600">one_n_minus_one</span> | <span style="color: #FF6600">zero_n</span> | <span style="color: #FF6600">disabled</span>} + | {<span style="color: #FF6600">cacertfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">cacerts</span>, [<span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()]} + | {<span style="color: #FF6600">cert</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()} + | {<span style="color: #FF6600">certfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">ciphers</span>, [<span style="font-weight: bold"><span style="color: #000000">ssl:erl_cipher_suite</span></span>()] | <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">client_renegotiation</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">crl_cache</span>, {<span style="font-weight: bold"><span style="color: #000000">module</span></span>(), {<span style="color: #FF6600">internal</span> | <span style="font-weight: bold"><span style="color: #000000">any</span></span>(), <span style="font-weight: bold"><span style="color: #000080">list</span></span>()}}} + | {<span style="color: #FF6600">crl_check</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>() | <span style="color: #FF6600">peer</span> | <span style="color: #FF6600">best_effort</span>} + | {<span style="color: #FF6600">depth</span>, <span style="color: #993399">0</span><span style="color: #990000">..</span><span style="color: #993399">255</span>} + | {<span style="color: #FF6600">dh</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()} + | {<span style="color: #FF6600">dhfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">fail_if_no_peer_cert</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">hibernate_after</span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>() | <span style="color: #000080">undefined</span>} + | {<span style="color: #FF6600">honor_cipher_order</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">key</span>, {<span style="color: #FF6600">'RSAPrivateKey'</span> | <span style="color: #FF6600">'DSAPrivateKey'</span> | <span style="color: #FF6600">'PrivateKeyInfo'</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()}} + | {<span style="color: #FF6600">keyfile</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">log_alert</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">next_protocols_advertised</span>, [<span style="font-weight: bold"><span style="color: #000080">binary</span></span>()]} + | {<span style="color: #FF6600">padding_check</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">partial_chain</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(([<span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()]) <span style="color: #990000">-></span> {<span style="color: #FF6600">trusted_ca</span>, <span style="font-weight: bold"><span style="color: #000000">public_key:der_encoded</span></span>()} | <span style="color: #FF6600">unknown_ca</span>)} + | {<span style="color: #FF6600">password</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">psk_identity</span>, <span style="font-weight: bold"><span style="color: #000000">string</span></span>()} + | {<span style="color: #FF6600">reuse_session</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>()} + | {<span style="color: #FF6600">reuse_sessions</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">secure_renegotiate</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">signature_algs</span>, [{<span style="font-weight: bold"><span style="color: #000080">atom</span></span>(), <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()}]} + | {<span style="color: #FF6600">sni_fun</span>, <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>()} + | {<span style="color: #FF6600">sni_hosts</span>, [{<span style="font-weight: bold"><span style="color: #000000">string</span></span>(), <span style="font-weight: bold"><span style="color: #000000">ssl_opt</span></span>()}]} + | {<span style="color: #FF6600">user_lookup_fun</span>, {<span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(), <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}} + | {<span style="color: #FF6600">v2_hello_compatible</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">verify</span>, <span style="font-weight: bold"><span style="color: #000000">ssl:verify_type</span></span>()} + | {<span style="color: #FF6600">verify_fun</span>, {<span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(), <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}} + | {<span style="color: #FF6600">versions</span>, [<span style="font-weight: bold"><span style="color: #000080">atom</span></span>()]}<span style="color: #990000">.</span></tt></pre></div></div> +<div class="paragraph"><p>SSL-specific listen options.</p></div> +</div> +<div class="sect2"> +<h3 id="_opt_ranch_tcp_opt_ssl_opt">opt() = ranch_tcp:opt() | ssl_opt()</h3> +<div class="paragraph"><p>Listen options.</p></div> +</div> +<div class="sect2"> +<h3 id="_opts_opt">opts() = [opt()]</h3> +<div class="paragraph"><p>List of listen options.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_option_descriptions">Option descriptions</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Specifying a certificate is mandatory, either through the <code>cert</code> +or the <code>certfile</code> option. None of the other options are required.</p></div> +<div class="paragraph"><p>The default value is given next to the option name.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +alpn_preferred_protocols +</dt> +<dd> +<p> + Perform Application-Layer Protocol Negotiation with the given list of preferred protocols. +</p> +</dd> +<dt class="hdlist1"> +beast_mitigation +</dt> +<dd> +<p> + Change the BEAST mitigation strategy for SSL-3.0 and TLS-1.0 to interoperate with legacy software. +</p> +</dd> +<dt class="hdlist1"> +cacertfile +</dt> +<dd> +<p> + Path to PEM encoded trusted certificates file used to verify peer certificates. +</p> +</dd> +<dt class="hdlist1"> +cacerts +</dt> +<dd> +<p> + List of DER encoded trusted certificates. +</p> +</dd> +<dt class="hdlist1"> +cert +</dt> +<dd> +<p> + DER encoded user certificate. +</p> +</dd> +<dt class="hdlist1"> +certfile +</dt> +<dd> +<p> + Path to the PEM encoded user certificate file. May also contain the private key. +</p> +</dd> +<dt class="hdlist1"> +ciphers +</dt> +<dd> +<p> + List of ciphers that clients are allowed to use. +</p> +</dd> +<dt class="hdlist1"> +client_renegotiation (true) +</dt> +<dd> +<p> + Whether to allow client-initiated renegotiation. +</p> +</dd> +<dt class="hdlist1"> +crl_cache ({ssl_crl_cache, {internal, []}}) +</dt> +<dd> +<p> + Customize the module used to cache Certificate Revocation Lists. +</p> +</dd> +<dt class="hdlist1"> +crl_check (false) +</dt> +<dd> +<p> + Whether to perform CRL check on all certificates in the chain during validation. +</p> +</dd> +<dt class="hdlist1"> +depth (1) +</dt> +<dd> +<p> + Maximum of intermediate certificates allowed in the certification path. +</p> +</dd> +<dt class="hdlist1"> +dh +</dt> +<dd> +<p> + DER encoded Diffie-Hellman parameters. +</p> +</dd> +<dt class="hdlist1"> +dhfile +</dt> +<dd> +<p> + Path to the PEM encoded Diffie-Hellman parameters file. +</p> +</dd> +<dt class="hdlist1"> +fail_if_no_peer_cert (false) +</dt> +<dd> +<p> + Whether to refuse the connection if the client sends an empty certificate. +</p> +</dd> +<dt class="hdlist1"> +hibernate_after (undefined) +</dt> +<dd> +<p> + Time in ms after which SSL socket processes go into hibernation to reduce memory usage. +</p> +</dd> +<dt class="hdlist1"> +honor_cipher_order (false) +</dt> +<dd> +<p> + If true, use the server’s preference for cipher selection. If false, use the client’s preference. +</p> +</dd> +<dt class="hdlist1"> +key +</dt> +<dd> +<p> + DER encoded user private key. +</p> +</dd> +<dt class="hdlist1"> +keyfile +</dt> +<dd> +<p> + Path to the PEM encoded private key file, if different than the certfile. +</p> +</dd> +<dt class="hdlist1"> +log_alert (true) +</dt> +<dd> +<p> + If false, error reports will not be displayed. +</p> +</dd> +<dt class="hdlist1"> +next_protocols_advertised +</dt> +<dd> +<p> + List of protocols to send to the client if it supports the Next Protocol extension. +</p> +</dd> +<dt class="hdlist1"> +nodelay (true) +</dt> +<dd> +<p> + Whether to enable TCP_NODELAY. +</p> +</dd> +<dt class="hdlist1"> +padding_check +</dt> +<dd> +<p> + Allow disabling the block cipher padding check for TLS-1.0 to be able to interoperate with legacy software. +</p> +</dd> +<dt class="hdlist1"> +partial_chain +</dt> +<dd> +<p> + Claim an intermediate CA in the chain as trusted. +</p> +</dd> +<dt class="hdlist1"> +password +</dt> +<dd> +<p> + Password to the private key file, if password protected. +</p> +</dd> +<dt class="hdlist1"> +psk_identity +</dt> +<dd> +<p> + Provide the given PSK identity hint to the client during the handshake. +</p> +</dd> +<dt class="hdlist1"> +reuse_session +</dt> +<dd> +<p> + Custom policy to decide whether a session should be reused. +</p> +</dd> +<dt class="hdlist1"> +reuse_sessions (false) +</dt> +<dd> +<p> + Whether to allow session reuse. +</p> +</dd> +<dt class="hdlist1"> +secure_renegotiate (false) +</dt> +<dd> +<p> + Whether to reject renegotiation attempts that do not conform to RFC5746. +</p> +</dd> +<dt class="hdlist1"> +signature_algs +</dt> +<dd> +<p> + The TLS signature algorithm extension may be used, from TLS 1.2, to negotiate which signature algorithm to use during the TLS handshake. +</p> +</dd> +<dt class="hdlist1"> +sni_fun +</dt> +<dd> +<p> + Function called when the client requests a host using Server Name Indication. Returns options to apply. +</p> +</dd> +<dt class="hdlist1"> +sni_hosts +</dt> +<dd> +<p> + Options to apply for the host that matches what the client requested with Server Name Indication. +</p> +</dd> +<dt class="hdlist1"> +user_lookup_fun +</dt> +<dd> +<p> + Function called to determine the shared secret when using PSK, or provide parameters when using SRP. +</p> +</dd> +<dt class="hdlist1"> +v2_hello_compatible +</dt> +<dd> +<p> + Accept clients that send hello messages in SSL-2.0 format while offering supported SSL/TLS versions. +</p> +</dd> +<dt class="hdlist1"> +verify (verify_none) +</dt> +<dd> +<p> + Use <code>verify_peer</code> to request a certificate from the client. +</p> +</dd> +<dt class="hdlist1"> +verify_fun +</dt> +<dd> +<p> + Custom policy to decide whether a client certificate is valid. +</p> +</dd> +<dt class="hdlist1"> +versions +</dt> +<dd> +<p> + TLS protocol versions that will be supported. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Note that the client will not send a certificate unless the +value for the <code>verify</code> option is set to <code>verify_peer</code>. This +means that the <code>fail_if_no_peer_cert</code> only apply when combined +with the <code>verify</code> option. The <code>verify_fun</code> option allows +greater control over the client certificate validation.</p></div> +<div class="paragraph"><p>The options <code>sni_fun</code> and <code>sni_hosts</code> are mutually exclusive.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="paragraph"><p>None.</p></div> +</div> +</div> diff --git a/docs/en/ranch/1.3/manual/ranch_tcp/index.html b/docs/en/ranch/1.3/manual/ranch_tcp/index.html index b33bfd20..60574604 100644 --- a/docs/en/ranch/1.3/manual/ranch_tcp/index.html +++ b/docs/en/ranch/1.3/manual/ranch_tcp/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch_tcp(3)</title> @@ -67,283 +67,283 @@ <h1 class="lined-header"><span>ranch_tcp(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>ranch_tcp - TCP transport module</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>ranch_tcp</code> module implements a TCP Ranch transport.</p></div>
-<div class="paragraph"><p>Note that due to bugs in OTP up to at least R16B02, it is
-recommended to disable async threads when using the
-<code>sendfile</code> function of this transport, as it can make
-the threads stuck indefinitely.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_opt">opt()</h3>
-<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">opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">backlog</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">buffer</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">delay_send</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">dontroute</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">exit_on_close</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">fd</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">high_msgq_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">high_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | <span style="color: #FF6600">inet</span>
- | <span style="color: #FF6600">inet6</span>
- | {<span style="color: #FF6600">ip</span>, <span style="font-weight: bold"><span style="color: #000000">inet:ip_address</span></span>()}
- | {<span style="color: #FF6600">ipv6_v6only</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">keepalive</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">linger</span>, {<span style="font-weight: bold"><span style="color: #000000">boolean</span></span>(), <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}}
- | {<span style="color: #FF6600">low_msgq_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">low_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">nodelay</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">port</span>, <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>()}
- | {<span style="font-weight: bold"><span style="color: #000080">priority</span></span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>()}
- | {<span style="color: #FF6600">raw</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}
- | {<span style="color: #FF6600">recbuf</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">send_timeout</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()}
- | {<span style="color: #FF6600">send_timeout_close</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()}
- | {<span style="color: #FF6600">sndbuf</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}
- | {<span style="color: #FF6600">tos</span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>Listen options.</p></div>
-<div class="paragraph"><p>This does not represent the entirety of the options that can
-be set on the socket, but only the options that may be
-set independently of protocol implementation.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_opts_opt">opts() = [opt()]</h3>
-<div class="paragraph"><p>List of listen options.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_option_descriptions">Option descriptions</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>None of the options are required.</p></div>
-<div class="paragraph"><p>Please consult the <code>gen_tcp</code> and <code>inet</code> manuals for a more
-thorough description of these options. This manual only aims
-to provide a short description along with what the defaults
-are. Defaults may be different in Ranch compared to <code>gen_tcp</code>.
-Defaults are given next to the option name.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-backlog (1024)
-</dt>
-<dd>
-<p>
- Max length of the queue of pending connections.
-</p>
-</dd>
-<dt class="hdlist1">
-buffer
-</dt>
-<dd>
-<p>
- Size of the buffer used by the Erlang driver. Default is system-dependent.
-</p>
-</dd>
-<dt class="hdlist1">
-delay_send (false)
-</dt>
-<dd>
-<p>
- Always queue packets before sending, to send fewer, larger packets over the network.
-</p>
-</dd>
-<dt class="hdlist1">
-dontroute (false)
-</dt>
-<dd>
-<p>
- Don’t send via a gateway, only send to directly connected hosts.
-</p>
-</dd>
-<dt class="hdlist1">
-exit_on_close (true)
-</dt>
-<dd>
-<p>
- Disable to allow sending data after a close has been detected.
-</p>
-</dd>
-<dt class="hdlist1">
-fd
-</dt>
-<dd>
-<p>
- File descriptor of the socket, if it was opened externally.
-</p>
-</dd>
-<dt class="hdlist1">
-high_msgq_watermark (8192)
-</dt>
-<dd>
-<p>
- Limit in the amount of data in the socket message queue before the socket queue becomes busy.
-</p>
-</dd>
-<dt class="hdlist1">
-high_watermark (8192)
-</dt>
-<dd>
-<p>
- Limit in the amount of data in the ERTS socket implementation’s queue before the socket becomes busy.
-</p>
-</dd>
-<dt class="hdlist1">
-inet
-</dt>
-<dd>
-<p>
- Set up the socket for IPv4.
-</p>
-</dd>
-<dt class="hdlist1">
-inet6
-</dt>
-<dd>
-<p>
- Set up the socket for IPv6.
-</p>
-</dd>
-<dt class="hdlist1">
-ip
-</dt>
-<dd>
-<p>
- Interface to listen on. Listen on all interfaces by default.
-</p>
-</dd>
-<dt class="hdlist1">
-ipv6_v6only (false)
-</dt>
-<dd>
-<p>
- Listen on IPv4 and IPv6 (false) or only on IPv6 (true). Use with inet6.
-</p>
-</dd>
-<dt class="hdlist1">
-keepalive (false)
-</dt>
-<dd>
-<p>
- Enable sending of keep-alive messages.
-</p>
-</dd>
-<dt class="hdlist1">
-linger ({false, 0})
-</dt>
-<dd>
-<p>
- Whether to wait and how long to flush data sent before closing the socket.
-</p>
-</dd>
-<dt class="hdlist1">
-low_msgq_watermark (4096)
-</dt>
-<dd>
-<p>
- Amount of data in the socket message queue before the socket queue leaves busy state.
-</p>
-</dd>
-<dt class="hdlist1">
-low_watermark (4096)
-</dt>
-<dd>
-<p>
- Amount of data in the ERTS socket implementation’s queue before the socket leaves busy state.
-</p>
-</dd>
-<dt class="hdlist1">
-nodelay (true)
-</dt>
-<dd>
-<p>
- Whether to enable TCP_NODELAY.
-</p>
-</dd>
-<dt class="hdlist1">
-port (0)
-</dt>
-<dd>
-<p>
- TCP port number to listen on. 0 means a random port will be used.
-</p>
-</dd>
-<dt class="hdlist1">
-priority (0)
-</dt>
-<dd>
-<p>
- Priority value for all packets to be sent by this socket.
-</p>
-</dd>
-<dt class="hdlist1">
-recbuf
-</dt>
-<dd>
-<p>
- Minimum size of the socket’s receive buffer. Default is system-dependent.
-</p>
-</dd>
-<dt class="hdlist1">
-send_timeout (30000)
-</dt>
-<dd>
-<p>
- How long the send call may wait for confirmation before returning.
-</p>
-</dd>
-<dt class="hdlist1">
-send_timeout_close (true)
-</dt>
-<dd>
-<p>
- Whether to close the socket when the confirmation wasn’t received.
-</p>
-</dd>
-<dt class="hdlist1">
-sndbuf
-</dt>
-<dd>
-<p>
- Minimum size of the socket’s send buffer. Default is system-dependent.
-</p>
-</dd>
-<dt class="hdlist1">
-tos
-</dt>
-<dd>
-<p>
- Value for the IP_TOS IP level option. Use with caution.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>In addition, the <code>raw</code> option can be used to set system-specific
-options by specifying the protocol level, the option number and
-the actual option value specified as a binary. This option is not
-portable. Use with caution.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exports">Exports</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>None.</p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch_tcp - TCP transport module</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch_tcp</code> module implements a TCP Ranch transport.</p></div> +<div class="paragraph"><p>Note that due to bugs in OTP up to at least R16B02, it is +recommended to disable async threads when using the +<code>sendfile</code> function of this transport, as it can make +the threads stuck indefinitely.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_opt">opt()</h3> +<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">opt</span></span>() <span style="color: #990000">=</span> {<span style="color: #FF6600">backlog</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">buffer</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">delay_send</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">dontroute</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">exit_on_close</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">fd</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">high_msgq_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">high_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | <span style="color: #FF6600">inet</span> + | <span style="color: #FF6600">inet6</span> + | {<span style="color: #FF6600">ip</span>, <span style="font-weight: bold"><span style="color: #000000">inet:ip_address</span></span>()} + | {<span style="color: #FF6600">ipv6_v6only</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">keepalive</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">linger</span>, {<span style="font-weight: bold"><span style="color: #000000">boolean</span></span>(), <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()}} + | {<span style="color: #FF6600">low_msgq_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">low_watermark</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">nodelay</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">port</span>, <span style="font-weight: bold"><span style="color: #000000">inet:port_number</span></span>()} + | {<span style="font-weight: bold"><span style="color: #000080">priority</span></span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>()} + | {<span style="color: #FF6600">raw</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>(), <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()} + | {<span style="color: #FF6600">recbuf</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">send_timeout</span>, <span style="font-weight: bold"><span style="color: #000000">timeout</span></span>()} + | {<span style="color: #FF6600">send_timeout_close</span>, <span style="font-weight: bold"><span style="color: #000000">boolean</span></span>()} + | {<span style="color: #FF6600">sndbuf</span>, <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()} + | {<span style="color: #FF6600">tos</span>, <span style="font-weight: bold"><span style="color: #000080">integer</span></span>()}</tt></pre></div></div> +<div class="paragraph"><p>Listen options.</p></div> +<div class="paragraph"><p>This does not represent the entirety of the options that can +be set on the socket, but only the options that may be +set independently of protocol implementation.</p></div> +</div> +<div class="sect2"> +<h3 id="_opts_opt">opts() = [opt()]</h3> +<div class="paragraph"><p>List of listen options.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_option_descriptions">Option descriptions</h2> +<div class="sectionbody"> +<div class="paragraph"><p>None of the options are required.</p></div> +<div class="paragraph"><p>Please consult the <code>gen_tcp</code> and <code>inet</code> manuals for a more +thorough description of these options. This manual only aims +to provide a short description along with what the defaults +are. Defaults may be different in Ranch compared to <code>gen_tcp</code>. +Defaults are given next to the option name.</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +backlog (1024) +</dt> +<dd> +<p> + Max length of the queue of pending connections. +</p> +</dd> +<dt class="hdlist1"> +buffer +</dt> +<dd> +<p> + Size of the buffer used by the Erlang driver. Default is system-dependent. +</p> +</dd> +<dt class="hdlist1"> +delay_send (false) +</dt> +<dd> +<p> + Always queue packets before sending, to send fewer, larger packets over the network. +</p> +</dd> +<dt class="hdlist1"> +dontroute (false) +</dt> +<dd> +<p> + Don’t send via a gateway, only send to directly connected hosts. +</p> +</dd> +<dt class="hdlist1"> +exit_on_close (true) +</dt> +<dd> +<p> + Disable to allow sending data after a close has been detected. +</p> +</dd> +<dt class="hdlist1"> +fd +</dt> +<dd> +<p> + File descriptor of the socket, if it was opened externally. +</p> +</dd> +<dt class="hdlist1"> +high_msgq_watermark (8192) +</dt> +<dd> +<p> + Limit in the amount of data in the socket message queue before the socket queue becomes busy. +</p> +</dd> +<dt class="hdlist1"> +high_watermark (8192) +</dt> +<dd> +<p> + Limit in the amount of data in the ERTS socket implementation’s queue before the socket becomes busy. +</p> +</dd> +<dt class="hdlist1"> +inet +</dt> +<dd> +<p> + Set up the socket for IPv4. +</p> +</dd> +<dt class="hdlist1"> +inet6 +</dt> +<dd> +<p> + Set up the socket for IPv6. +</p> +</dd> +<dt class="hdlist1"> +ip +</dt> +<dd> +<p> + Interface to listen on. Listen on all interfaces by default. +</p> +</dd> +<dt class="hdlist1"> +ipv6_v6only (false) +</dt> +<dd> +<p> + Listen on IPv4 and IPv6 (false) or only on IPv6 (true). Use with inet6. +</p> +</dd> +<dt class="hdlist1"> +keepalive (false) +</dt> +<dd> +<p> + Enable sending of keep-alive messages. +</p> +</dd> +<dt class="hdlist1"> +linger ({false, 0}) +</dt> +<dd> +<p> + Whether to wait and how long to flush data sent before closing the socket. +</p> +</dd> +<dt class="hdlist1"> +low_msgq_watermark (4096) +</dt> +<dd> +<p> + Amount of data in the socket message queue before the socket queue leaves busy state. +</p> +</dd> +<dt class="hdlist1"> +low_watermark (4096) +</dt> +<dd> +<p> + Amount of data in the ERTS socket implementation’s queue before the socket leaves busy state. +</p> +</dd> +<dt class="hdlist1"> +nodelay (true) +</dt> +<dd> +<p> + Whether to enable TCP_NODELAY. +</p> +</dd> +<dt class="hdlist1"> +port (0) +</dt> +<dd> +<p> + TCP port number to listen on. 0 means a random port will be used. +</p> +</dd> +<dt class="hdlist1"> +priority (0) +</dt> +<dd> +<p> + Priority value for all packets to be sent by this socket. +</p> +</dd> +<dt class="hdlist1"> +recbuf +</dt> +<dd> +<p> + Minimum size of the socket’s receive buffer. Default is system-dependent. +</p> +</dd> +<dt class="hdlist1"> +send_timeout (30000) +</dt> +<dd> +<p> + How long the send call may wait for confirmation before returning. +</p> +</dd> +<dt class="hdlist1"> +send_timeout_close (true) +</dt> +<dd> +<p> + Whether to close the socket when the confirmation wasn’t received. +</p> +</dd> +<dt class="hdlist1"> +sndbuf +</dt> +<dd> +<p> + Minimum size of the socket’s send buffer. Default is system-dependent. +</p> +</dd> +<dt class="hdlist1"> +tos +</dt> +<dd> +<p> + Value for the IP_TOS IP level option. Use with caution. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>In addition, the <code>raw</code> option can be used to set system-specific +options by specifying the protocol level, the option number and +the actual option value specified as a binary. This option is not +portable. Use with caution.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="paragraph"><p>None.</p></div> +</div> +</div> diff --git a/docs/en/ranch/1.3/manual/ranch_transport/index.html b/docs/en/ranch/1.3/manual/ranch_transport/index.html index aa57afd8..8840daad 100644 --- a/docs/en/ranch/1.3/manual/ranch_transport/index.html +++ b/docs/en/ranch/1.3/manual/ranch_transport/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: ranch_transport(3)</title> @@ -67,494 +67,494 @@ <h1 class="lined-header"><span>ranch_transport(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>ranch_transport - behaviour for transport modules</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>ranch_transport</code> behaviour defines the interface used
-by Ranch transports.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_sendfile_opts_chunk_size_non_neg_integer">sendfile_opts() = [{chunk_size, non_neg_integer()}]</h3>
-<div class="paragraph"><p>Options used by the sendfile function and callbacks.</p></div>
-<div class="paragraph"><p>Allows configuring the chunk size, in bytes. Defaults to 8191 bytes.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_callbacks">Callbacks</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_accept_lsocket_timeout_8594_ok_csocket_error_closed_timeout_atom">accept(LSocket, Timeout) → {ok, CSocket} | {error, closed | timeout | atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-LSocket = CSocket = any()
-</dt>
-<dd>
-<p>
-Listening socket.
-</p>
-</dd>
-<dt class="hdlist1">
-Timeout = timeout()
-</dt>
-<dd>
-<p>
-Accept timeout.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Accept a connection on the given listening socket.</p></div>
-<div class="paragraph"><p>The <code>accept_ack</code> callback will be used to initialize the socket
-after accepting the connection. This is most useful when the
-transport is not raw TCP, like with SSL for example.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_accept_ack_csocket_timeout_8594_ok">accept_ack(CSocket, Timeout) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-Timeout = timeout()
-</dt>
-<dd>
-<p>
-Ack timeout.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Perform post-accept initialization of the connection.</p></div>
-<div class="paragraph"><p>This function will be called by connection processes
-before performing any socket operation. It allows
-transports that require extra initialization to perform
-their task and make the socket ready to use.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_close_socket_8594_ok">close(Socket) → ok</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Socket = any()
-</dt>
-<dd>
-<p>
-Socket opened with listen/1 or accept/2.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Close the given socket.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_controlling_process_socket_pid_8594_ok_error_closed_not_owner_atom">controlling_process(Socket, Pid) → ok | {error, closed | not_owner | atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Socket = any()
-</dt>
-<dd>
-<p>
-Socket opened with listen/1 or accept/2.
-</p>
-</dd>
-<dt class="hdlist1">
-Pid = pid()
-</dt>
-<dd>
-<p>
-Pid of the new owner of the socket.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Change the controlling process for the given socket.</p></div>
-<div class="paragraph"><p>The controlling process is the process that is allowed to
-perform operations on the socket, and that will receive
-messages from the socket when active mode is used. When
-the controlling process dies, the socket is closed.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_listen_transopts_8594_ok_lsocket_error_atom">listen(TransOpts) → {ok, LSocket} | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-TransOpts = any()
-</dt>
-<dd>
-<p>
-Transport options.
-</p>
-</dd>
-<dt class="hdlist1">
-LSocket = any()
-</dt>
-<dd>
-<p>
-Listening socket.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Listen for connections on the given port.</p></div>
-<div class="paragraph"><p>The port is given as part of the transport options under
-the key <code>port</code>. Any other option is transport dependent.</p></div>
-<div class="paragraph"><p>The socket returned by this call can then be used to
-accept connections. It is not possible to send or receive
-data from the listening socket.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_messages_8594_ok_closed_error">messages() → {OK, Closed, Error}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-OK = Closed = Error = atom()
-</dt>
-<dd>
-<p>
-Tuple names.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the atoms used to identify messages sent in active mode.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_name_8594_name">name() → Name</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name = atom()
-</dt>
-<dd>
-<p>
-Transport module name.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the name of the transport.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_peername_csocket_8594_ok_ip_port_error_atom">peername(CSocket) → {ok, {IP, Port}} | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-IP = inet:ip_address()
-</dt>
-<dd>
-<p>
-IP of the remote endpoint.
-</p>
-</dd>
-<dt class="hdlist1">
-Port = inet:port_number()
-</dt>
-<dd>
-<p>
-Port of the remote endpoint.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the IP and port of the remote endpoint.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_recv_csocket_length_timeout_8594_ok_packet_error_closed_timeout_atom">recv(CSocket, Length, Timeout) → {ok, Packet} | {error, closed | timeout | atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-Length = non_neg_integer()
-</dt>
-<dd>
-<p>
-Requested length.
-</p>
-</dd>
-<dt class="hdlist1">
-Timeout = timeout()
-</dt>
-<dd>
-<p>
-Receive timeout.
-</p>
-</dd>
-<dt class="hdlist1">
-Packet = iodata() | any()
-</dt>
-<dd>
-<p>
-Data received.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Receive data from the given socket when in passive mode.</p></div>
-<div class="paragraph"><p>Trying to receive data from a socket that is in active mode
-will return an error.</p></div>
-<div class="paragraph"><p>A length of 0 will return any data available on the socket.</p></div>
-<div class="paragraph"><p>While it is possible to use the timeout value <code>infinity</code>,
-this is highly discouraged as this could cause your process
-to get stuck waiting for data that will never come. This may
-happen when a socket becomes half-open due to a crash of the
-remote endpoint. Wi-Fi going down is another common culprit
-of this issue.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_send_csocket_packet_8594_ok_error_atom">send(CSocket, Packet) → ok | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-Packet = iodata()
-</dt>
-<dd>
-<p>
-Data to be sent.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Send data to the given socket.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_sendfile_csocket_file_8594_sendfile_csocket_file_0_0">sendfile(CSocket, File) → sendfile(CSocket, File, 0, 0, [])</h3>
-<div class="paragraph"><p>Alias of <code>ranch_transport:sendfile/5</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_sendfile_csocket_file_offset_bytes_8594_sendfile_csocket_file_offset_bytes">sendfile(CSocket, File, Offset, Bytes) → sendfile(CSocket, File, Offset, Bytes, [])</h3>
-<div class="paragraph"><p>Alias of <code>ranch_transport:sendfile/5</code>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_sendfile_csocket_file_offset_bytes_sfopts_8594_ok_sentbytes_error_atom">sendfile(CSocket, File, Offset, Bytes, SfOpts) → {ok, SentBytes} | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-File = file:filename_all() | file:fd()
-</dt>
-<dd>
-<p>
-Filename or file descriptor for the file to be sent.
-</p>
-</dd>
-<dt class="hdlist1">
-Offset = non_neg_integer()
-</dt>
-<dd>
-<p>
-Begin sending at this position in the file.
-</p>
-</dd>
-<dt class="hdlist1">
-Bytes = non_neg_integer()
-</dt>
-<dd>
-<p>
-Send this many bytes.
-</p>
-</dd>
-<dt class="hdlist1">
-SentBytes = non_neg_integer()
-</dt>
-<dd>
-<p>
-This many bytes were sent.
-</p>
-</dd>
-<dt class="hdlist1">
-SfOpts = sendfile_opts()
-</dt>
-<dd>
-<p>
-Sendfile options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Send data from a file to the given socket.</p></div>
-<div class="paragraph"><p>The file may be sent full or in parts, and may be specified
-by its filename or by an already open file descriptor.</p></div>
-<div class="paragraph"><p>Transports that manipulate TCP directly may use the
-<code>file:sendfile/{2,4,5}</code> function, which calls the sendfile
-syscall where applicable (on Linux, for example). Other
-transports can use the <code>sendfile/6</code> function exported from
-this module.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_setopts_csocket_sockopts_8594_ok_error_atom">setopts(CSocket, SockOpts) → ok | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-SockOpts = any()
-</dt>
-<dd>
-<p>
-Socket options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Change options for the given socket.</p></div>
-<div class="paragraph"><p>This is mainly useful for switching to active or passive mode
-or to set protocol-specific options.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_shutdown_csocket_how_8594_ok_error_atom">shutdown(CSocket, How) → ok | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-How = read | write | read_write
-</dt>
-<dd>
-<p>
-Which side(s) of the socket to close.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Immediately close the socket in one or two directions.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_sockname_socket_8594_ok_ip_port_error_atom">sockname(Socket) → {ok, {IP, Port}} | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Socket = any()
-</dt>
-<dd>
-<p>
-Socket opened with listen/1 or accept/2.
-</p>
-</dd>
-<dt class="hdlist1">
-IP = inet:ip_address()
-</dt>
-<dd>
-<p>
-IP of the local endpoint.
-</p>
-</dd>
-<dt class="hdlist1">
-Port = inet:port_number()
-</dt>
-<dd>
-<p>
-Port of the local endpoint.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Return the IP and port of the local endpoint.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exports">Exports</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_sendfile_transport_csocket_file_offset_bytes_sfopts_8594_ok_sentbytes_error_atom">sendfile(Transport, CSocket, File, Offset, Bytes, SfOpts) → {ok, SentBytes} | {error, atom()}</h3>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Transport = module()
-</dt>
-<dd>
-<p>
-Transport module for this socket.
-</p>
-</dd>
-<dt class="hdlist1">
-CSocket = any()
-</dt>
-<dd>
-<p>
-Socket for this connection.
-</p>
-</dd>
-<dt class="hdlist1">
-File = file:filename_all() | file:fd()
-</dt>
-<dd>
-<p>
-Filename or file descriptor for the file to be sent.
-</p>
-</dd>
-<dt class="hdlist1">
-Offset = non_neg_integer()
-</dt>
-<dd>
-<p>
-Begin sending at this position in the file.
-</p>
-</dd>
-<dt class="hdlist1">
-Bytes = non_neg_integer()
-</dt>
-<dd>
-<p>
-Send this many bytes.
-</p>
-</dd>
-<dt class="hdlist1">
-SentBytes = non_neg_integer()
-</dt>
-<dd>
-<p>
-This many bytes were sent.
-</p>
-</dd>
-<dt class="hdlist1">
-SfOpts = sendfile_opts()
-</dt>
-<dd>
-<p>
-Sendfile options.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p>Send data from a file to the given socket.</p></div>
-<div class="paragraph"><p>This function emulates the function <code>file:sendfile/{2,4,5}</code>
-and may be used when transports are not manipulating TCP
-directly.</p></div>
-</div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>ranch_transport - behaviour for transport modules</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The <code>ranch_transport</code> behaviour defines the interface used +by Ranch transports.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_types">Types</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_sendfile_opts_chunk_size_non_neg_integer">sendfile_opts() = [{chunk_size, non_neg_integer()}]</h3> +<div class="paragraph"><p>Options used by the sendfile function and callbacks.</p></div> +<div class="paragraph"><p>Allows configuring the chunk size, in bytes. Defaults to 8191 bytes.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_callbacks">Callbacks</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_accept_lsocket_timeout_8594_ok_csocket_error_closed_timeout_atom">accept(LSocket, Timeout) → {ok, CSocket} | {error, closed | timeout | atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +LSocket = CSocket = any() +</dt> +<dd> +<p> +Listening socket. +</p> +</dd> +<dt class="hdlist1"> +Timeout = timeout() +</dt> +<dd> +<p> +Accept timeout. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Accept a connection on the given listening socket.</p></div> +<div class="paragraph"><p>The <code>accept_ack</code> callback will be used to initialize the socket +after accepting the connection. This is most useful when the +transport is not raw TCP, like with SSL for example.</p></div> +</div> +<div class="sect2"> +<h3 id="_accept_ack_csocket_timeout_8594_ok">accept_ack(CSocket, Timeout) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +Timeout = timeout() +</dt> +<dd> +<p> +Ack timeout. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Perform post-accept initialization of the connection.</p></div> +<div class="paragraph"><p>This function will be called by connection processes +before performing any socket operation. It allows +transports that require extra initialization to perform +their task and make the socket ready to use.</p></div> +</div> +<div class="sect2"> +<h3 id="_close_socket_8594_ok">close(Socket) → ok</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Socket = any() +</dt> +<dd> +<p> +Socket opened with listen/1 or accept/2. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Close the given socket.</p></div> +</div> +<div class="sect2"> +<h3 id="_controlling_process_socket_pid_8594_ok_error_closed_not_owner_atom">controlling_process(Socket, Pid) → ok | {error, closed | not_owner | atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Socket = any() +</dt> +<dd> +<p> +Socket opened with listen/1 or accept/2. +</p> +</dd> +<dt class="hdlist1"> +Pid = pid() +</dt> +<dd> +<p> +Pid of the new owner of the socket. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Change the controlling process for the given socket.</p></div> +<div class="paragraph"><p>The controlling process is the process that is allowed to +perform operations on the socket, and that will receive +messages from the socket when active mode is used. When +the controlling process dies, the socket is closed.</p></div> +</div> +<div class="sect2"> +<h3 id="_listen_transopts_8594_ok_lsocket_error_atom">listen(TransOpts) → {ok, LSocket} | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +TransOpts = any() +</dt> +<dd> +<p> +Transport options. +</p> +</dd> +<dt class="hdlist1"> +LSocket = any() +</dt> +<dd> +<p> +Listening socket. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Listen for connections on the given port.</p></div> +<div class="paragraph"><p>The port is given as part of the transport options under +the key <code>port</code>. Any other option is transport dependent.</p></div> +<div class="paragraph"><p>The socket returned by this call can then be used to +accept connections. It is not possible to send or receive +data from the listening socket.</p></div> +</div> +<div class="sect2"> +<h3 id="_messages_8594_ok_closed_error">messages() → {OK, Closed, Error}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +OK = Closed = Error = atom() +</dt> +<dd> +<p> +Tuple names. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the atoms used to identify messages sent in active mode.</p></div> +</div> +<div class="sect2"> +<h3 id="_name_8594_name">name() → Name</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name = atom() +</dt> +<dd> +<p> +Transport module name. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the name of the transport.</p></div> +</div> +<div class="sect2"> +<h3 id="_peername_csocket_8594_ok_ip_port_error_atom">peername(CSocket) → {ok, {IP, Port}} | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +IP = inet:ip_address() +</dt> +<dd> +<p> +IP of the remote endpoint. +</p> +</dd> +<dt class="hdlist1"> +Port = inet:port_number() +</dt> +<dd> +<p> +Port of the remote endpoint. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the IP and port of the remote endpoint.</p></div> +</div> +<div class="sect2"> +<h3 id="_recv_csocket_length_timeout_8594_ok_packet_error_closed_timeout_atom">recv(CSocket, Length, Timeout) → {ok, Packet} | {error, closed | timeout | atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +Length = non_neg_integer() +</dt> +<dd> +<p> +Requested length. +</p> +</dd> +<dt class="hdlist1"> +Timeout = timeout() +</dt> +<dd> +<p> +Receive timeout. +</p> +</dd> +<dt class="hdlist1"> +Packet = iodata() | any() +</dt> +<dd> +<p> +Data received. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Receive data from the given socket when in passive mode.</p></div> +<div class="paragraph"><p>Trying to receive data from a socket that is in active mode +will return an error.</p></div> +<div class="paragraph"><p>A length of 0 will return any data available on the socket.</p></div> +<div class="paragraph"><p>While it is possible to use the timeout value <code>infinity</code>, +this is highly discouraged as this could cause your process +to get stuck waiting for data that will never come. This may +happen when a socket becomes half-open due to a crash of the +remote endpoint. Wi-Fi going down is another common culprit +of this issue.</p></div> +</div> +<div class="sect2"> +<h3 id="_send_csocket_packet_8594_ok_error_atom">send(CSocket, Packet) → ok | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +Packet = iodata() +</dt> +<dd> +<p> +Data to be sent. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Send data to the given socket.</p></div> +</div> +<div class="sect2"> +<h3 id="_sendfile_csocket_file_8594_sendfile_csocket_file_0_0">sendfile(CSocket, File) → sendfile(CSocket, File, 0, 0, [])</h3> +<div class="paragraph"><p>Alias of <code>ranch_transport:sendfile/5</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_sendfile_csocket_file_offset_bytes_8594_sendfile_csocket_file_offset_bytes">sendfile(CSocket, File, Offset, Bytes) → sendfile(CSocket, File, Offset, Bytes, [])</h3> +<div class="paragraph"><p>Alias of <code>ranch_transport:sendfile/5</code>.</p></div> +</div> +<div class="sect2"> +<h3 id="_sendfile_csocket_file_offset_bytes_sfopts_8594_ok_sentbytes_error_atom">sendfile(CSocket, File, Offset, Bytes, SfOpts) → {ok, SentBytes} | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +File = file:filename_all() | file:fd() +</dt> +<dd> +<p> +Filename or file descriptor for the file to be sent. +</p> +</dd> +<dt class="hdlist1"> +Offset = non_neg_integer() +</dt> +<dd> +<p> +Begin sending at this position in the file. +</p> +</dd> +<dt class="hdlist1"> +Bytes = non_neg_integer() +</dt> +<dd> +<p> +Send this many bytes. +</p> +</dd> +<dt class="hdlist1"> +SentBytes = non_neg_integer() +</dt> +<dd> +<p> +This many bytes were sent. +</p> +</dd> +<dt class="hdlist1"> +SfOpts = sendfile_opts() +</dt> +<dd> +<p> +Sendfile options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Send data from a file to the given socket.</p></div> +<div class="paragraph"><p>The file may be sent full or in parts, and may be specified +by its filename or by an already open file descriptor.</p></div> +<div class="paragraph"><p>Transports that manipulate TCP directly may use the +<code>file:sendfile/{2,4,5}</code> function, which calls the sendfile +syscall where applicable (on Linux, for example). Other +transports can use the <code>sendfile/6</code> function exported from +this module.</p></div> +</div> +<div class="sect2"> +<h3 id="_setopts_csocket_sockopts_8594_ok_error_atom">setopts(CSocket, SockOpts) → ok | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +SockOpts = any() +</dt> +<dd> +<p> +Socket options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Change options for the given socket.</p></div> +<div class="paragraph"><p>This is mainly useful for switching to active or passive mode +or to set protocol-specific options.</p></div> +</div> +<div class="sect2"> +<h3 id="_shutdown_csocket_how_8594_ok_error_atom">shutdown(CSocket, How) → ok | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +How = read | write | read_write +</dt> +<dd> +<p> +Which side(s) of the socket to close. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Immediately close the socket in one or two directions.</p></div> +</div> +<div class="sect2"> +<h3 id="_sockname_socket_8594_ok_ip_port_error_atom">sockname(Socket) → {ok, {IP, Port}} | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Socket = any() +</dt> +<dd> +<p> +Socket opened with listen/1 or accept/2. +</p> +</dd> +<dt class="hdlist1"> +IP = inet:ip_address() +</dt> +<dd> +<p> +IP of the local endpoint. +</p> +</dd> +<dt class="hdlist1"> +Port = inet:port_number() +</dt> +<dd> +<p> +Port of the local endpoint. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Return the IP and port of the local endpoint.</p></div> +</div> +</div> +</div> +<div class="sect1"> +<h2 id="_exports">Exports</h2> +<div class="sectionbody"> +<div class="sect2"> +<h3 id="_sendfile_transport_csocket_file_offset_bytes_sfopts_8594_ok_sentbytes_error_atom">sendfile(Transport, CSocket, File, Offset, Bytes, SfOpts) → {ok, SentBytes} | {error, atom()}</h3> +<div class="dlist"><dl> +<dt class="hdlist1"> +Transport = module() +</dt> +<dd> +<p> +Transport module for this socket. +</p> +</dd> +<dt class="hdlist1"> +CSocket = any() +</dt> +<dd> +<p> +Socket for this connection. +</p> +</dd> +<dt class="hdlist1"> +File = file:filename_all() | file:fd() +</dt> +<dd> +<p> +Filename or file descriptor for the file to be sent. +</p> +</dd> +<dt class="hdlist1"> +Offset = non_neg_integer() +</dt> +<dd> +<p> +Begin sending at this position in the file. +</p> +</dd> +<dt class="hdlist1"> +Bytes = non_neg_integer() +</dt> +<dd> +<p> +Send this many bytes. +</p> +</dd> +<dt class="hdlist1"> +SentBytes = non_neg_integer() +</dt> +<dd> +<p> +This many bytes were sent. +</p> +</dd> +<dt class="hdlist1"> +SfOpts = sendfile_opts() +</dt> +<dd> +<p> +Sendfile options. +</p> +</dd> +</dl></div> +<div class="paragraph"><p>Send data from a file to the given socket.</p></div> +<div class="paragraph"><p>This function emulates the function <code>file:sendfile/{2,4,5}</code> +and may be used when transports are not manipulating TCP +directly.</p></div> +</div> +</div> +</div> diff --git a/docs/en/ranch/index.html b/docs/en/ranch/index.html index d87c4243..0194031a 100644 --- a/docs/en/ranch/index.html +++ b/docs/en/ranch/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/docs/</title><link rel="canonical" href="https://ninenines.eu/docs/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/docs/" /></head></html>
\ No newline at end of file diff --git a/docs/index.html b/docs/index.html index 4d81cc8c..b6f126d1 100644 --- a/docs/index.html +++ b/docs/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Documentation</title> @@ -167,12 +167,12 @@ </ul> -<div class="sect2">
-<h3 id="_contribute">Contribute</h3>
-<div class="paragraph"><p>Do you have examples, tutorials, videos about one or more
-of my projects? I would happily include them on this page.</p></div>
-<div class="paragraph"><p><a href="mailto:[email protected]">Send me an email with the details</a>.</p></div>
-</div>
+<div class="sect2"> +<h3 id="_contribute">Contribute</h3> +<div class="paragraph"><p>Do you have examples, tutorials, videos about one or more +of my projects? I would happily include them on this page.</p></div> +<div class="paragraph"><p><a href="mailto:[email protected]">Send me an email with the details</a>.</p></div> +</div> </div> </div> diff --git a/docs/index.xml b/docs/index.xml index 704b0a6e..779b38a0 100644 --- a/docs/index.xml +++ b/docs/index.xml @@ -1,12 +1,841 @@ <?xml version="1.0" encoding="utf-8" standalone="yes" ?> <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"> <channel> - <title>Docs-rsses on Nine Nines</title> - <link>https://ninenines.eu/docs/index.xml</link> - <description>Recent content in Docs-rsses on Nine Nines</description> + <title>Docs on Nine Nines</title> + <link>https://ninenines.eu/docs/</link> + <description>Recent content in Docs on Nine Nines</description> <generator>Hugo -- gohugo.io</generator> <language>en-us</language> - <atom:link href="https://ninenines.eu/docs/index.xml" rel="self" type="application/rss+xml" /> + + <atom:link href="https://ninenines.eu/docs/index.xml" rel="self" type="application/rss+xml" /> + + + <item> + <title>Installation</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/installation/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/installation/</guid> + <description>On Unix Erlang.mk requires GNU Make to be installed. While it will currently work with GNU Make 3.81, support for this version is deprecated and will be removed in 2017. We recommend GNU Make 4.1 or later. + Git and Erlang/OTP must also be installed. + Some functionality requires that Autoconf 2.59 or later be installed, in order to compile Erlang/OTP. Erlang/OTP may have further requirements depending on your needs.</description> + </item> + + <item> + <title>Introduction</title> + <link>https://ninenines.eu/docs/en/gun/1.0/guide/introduction/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/gun/1.0/guide/introduction/</guid> + <description>Gun is an Erlang HTTP client with support for HTTP/1.1, HTTP/2 and Websocket. + Prerequisites Knowledge of Erlang, but also of the HTTP/1.1, HTTP/2 and Websocket protocols is required in order to read this guide. + Supported platforms Gun is tested and supported on Linux. + Gun is developed for Erlang 18+. + Gun may be compiled on earlier Erlang versions with small source code modifications but there is no guarantee that it will work as intended.</description> + </item> + + <item> + <title>Introduction</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/guide/introduction/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/guide/introduction/</guid> + <description>Ranch is a socket acceptor pool for TCP protocols. + Ranch aims to provide everything you need to accept TCP connections with a small code base and low latency while being easy to use directly as an application or to embed into your own. + Prerequisites It is assumed the developer already knows Erlang and has some experience with socket programming and TCP protocols. + Supported platforms Ranch is tested and supported on Linux.</description> + </item> + + <item> + <title>Introduction</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/guide/introduction/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/guide/introduction/</guid> + <description>Ranch is a socket acceptor pool for TCP protocols. + Ranch aims to provide everything you need to accept TCP connections with a small code base and low latency while being easy to use directly as an application or to embed into your own. + Prerequisites It is assumed the developer already knows Erlang and has some experience with socket programming and TCP protocols. + Supported platforms Ranch is tested and supported on Linux, FreeBSD, OSX and Windows.</description> + </item> + + <item> + <title>The modern Web</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/modern_web/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/modern_web/</guid> + <description>Cowboy is a server for the modern Web. This chapter explains what it means and details all the standards involved. + Cowboy supports all the standards listed in this document. + HTTP/2 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.</description> + </item> + + <item> + <title>Erlang and the Web</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/erlang_web/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/erlang_web/</guid> + <description>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 involved. A few connections are opened and requests are sent through these connections. Then the web page is displayed on your screen. Your browser will only open up to 4 or 8 connections to the server, depending on your settings.</description> + </item> + + <item> + <title>Getting started</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/getting_started/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/getting_started/</guid> + <description>This chapter explains how to get started using Erlang.mk. + Creating a folder for your project The first step is always to create a new folder that will contain your project. + $ mkdir hello_joe $ cd hello_joe Most people tend to put all their projects side by side in a common folder. We recommend keeping an organization similar to your remote repositories. For example, for GitHub users, put all your projects in a common folder with the same name as your username.</description> + </item> + + <item> + <title>Listeners</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/guide/listeners/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/guide/listeners/</guid> + <description>A listener is a set of processes whose role is to listen on a port for new connections. It manages a pool of acceptor processes, each of them indefinitely accepting connections. When it does, it starts a new process executing the protocol handler code. All the socket programming is abstracted through the user of transport handlers. + The listener takes care of supervising all the acceptor and connection processes, allowing developers to focus on building their application.</description> + </item> + + <item> + <title>Listeners</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/guide/listeners/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/guide/listeners/</guid> + <description>A listener is a set of processes whose role is to listen on a port for new connections. It manages a pool of acceptor processes, each of them indefinitely accepting connections. When it does, it starts a new process executing the protocol handler code. All the socket programming is abstracted through the use of transport handlers. + The listener takes care of supervising all the acceptor and connection processes, allowing developers to focus on building their application.</description> + </item> + + <item> + <title>Starting and stopping</title> + <link>https://ninenines.eu/docs/en/gun/1.0/guide/start/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/gun/1.0/guide/start/</guid> + <description>This chapter describes how to start and stop the Gun application. + Setting up Before Gun can be used it needs to be in Erlang&#8217;s ERL_LIBS path variable. If you use erlang.mk or a similar build tool, you only need to specify Gun as a dependency to your application and the tool will take care of downloading Gun and setting up paths. + With erlang.mk this is done by adding gun to the DEPS variable in your Makefile.</description> + </item> + + <item> + <title>Supported protocols</title> + <link>https://ninenines.eu/docs/en/gun/1.0/guide/protocols/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/gun/1.0/guide/protocols/</guid> + <description>This chapter describes the protocols supported and the operations available to them. + HTTP/1.1 HTTP/1.1 is a text request-response protocol. The client sends a request, the server sends back a response. + Gun provides convenience functions for performing GET, HEAD, OPTIONS, POST, PATCH, PUT, and DELETE requests. All these functions are aliases of gun:request/{4,5,6} for each respective methods. Gun also provides a gun:data/4 function for streaming the request body. + Gun will send a gun_response message for every response received, followed by zero or more gun_data messages for the response body.</description> + </item> + + <item> + <title>Introduction</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/introduction/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/introduction/</guid> + <description>Cowboy is a small, fast and modern HTTP server for Erlang/OTP. + Cowboy aims to provide a complete 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 in another application.</description> + </item> + + <item> + <title>Transports</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/guide/transports/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/guide/transports/</guid> + <description>A transport defines the interface to interact with a socket. + Transports can be used for connecting, listening and accepting connections, but also for receiving and sending data. Both passive and active mode are supported, although all sockets are initialized as passive. + TCP transport The TCP transport is a thin wrapper around gen_tcp. + SSL transport The SSL transport is a thin wrapper around ssl. It requires the crypto, asn1, public_key and ssl applications to be started.</description> + </item> + + <item> + <title>Transports</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/guide/transports/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/guide/transports/</guid> + <description>A transport defines the interface to interact with a socket. + Transports can be used for connecting, listening and accepting connections, but also for receiving and sending data. Both passive and active mode are supported, although all sockets are initialized as passive. + TCP transport The TCP transport is a thin wrapper around gen_tcp. + SSL transport The SSL transport is a thin wrapper around ssl. + Ranch depends on ssl by default so any necessary dependencies will start when Ranch is started.</description> + </item> + + <item> + <title>Overview</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/overview/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/overview/</guid> + <description>Now that you know how to get started, let&#8217;s take a look at what Erlang.mk can do for you. + Building your project Erlang.mk is first and foremost a build tool. It is especially tailored for Erlang developers and follows widely accepted practices in the Erlang community. + Erlang.mk will happily build all Erlang-specific files you throw at it. Other kinds of files too, like C or C++ code when you are working on a NIF or a port driver.</description> + </item> + + <item> + <title>Connection</title> + <link>https://ninenines.eu/docs/en/gun/1.0/guide/connect/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/gun/1.0/guide/connect/</guid> + <description>This chapter describes how to open, monitor and close a connection using the Gun client. + Gun connections Gun is designed with the HTTP/2 and Websocket protocols in mind. They are built for long-running connections that allow concurrent exchange of data, either in the form of request/responses for HTTP/2 or in the form of messages for Websocket. + A Gun connection is an Erlang process that manages a socket to a remote endpoint.</description> + </item> + + <item> + <title>Protocols</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/guide/protocols/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/guide/protocols/</guid> + <description>A protocol handler starts a connection process and defines the protocol logic executed in this process. + Writing a protocol handler All protocol handlers must implement the ranch_protocol behavior which defines a single callback, start_link/4. This callback is responsible for spawning a new process for handling the connection. It receives four arguments: the name of the listener, the socket, the transport handler being used and the protocol options defined in the call to ranch:start_listener/6.</description> + </item> + + <item> + <title>Protocols</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/guide/protocols/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/guide/protocols/</guid> + <description>A protocol handler starts a connection process and defines the protocol logic executed in this process. + Writing a protocol handler All protocol handlers must implement the ranch_protocol behavior which defines a single callback, start_link/4. This callback is responsible for spawning a new process for handling the connection. It receives four arguments: the name of the listener, the socket, the transport handler being used and the protocol options defined in the call to ranch:start_listener/5.</description> + </item> + + <item> + <title>Getting started</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/getting_started/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/getting_started/</guid> + <description>Erlang is more than a language, it is also an operating system for your applications. Erlang developers rarely write standalone modules, they write libraries or applications, and then bundle those into what is called a release. A release contains the Erlang VM plus all applications required to run the node, so it can be pushed to production directly. + This chapter walks you through all the steps of setting up Cowboy, writing your first application and generating your first release.</description> + </item> + + <item> + <title>Updating Erlang.mk</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/updating/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/updating/</guid> + <description>This chapter describes how to update the erlang.mk file in your repository. + Initial bootstrap The first time you use Erlang.mk, it will bootstrap itself. It always uses the most recent version for this, so you don&#8217;t have to update after creating your project. + Updating Later on though, updating becomes a necessity. Erlang.mk developers and contributors relentlessly improve the project and add new features; it would be a waste not to benefit from this.</description> + </item> + + <item> + <title>HTTP</title> + <link>https://ninenines.eu/docs/en/gun/1.0/guide/http/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/gun/1.0/guide/http/</guid> + <description>This chapter describes how to use the Gun client for communicating with an HTTP/1.1 or HTTP/2 server. + Streams Every time a request is initiated, Gun creates a stream. A stream reference uniquely identifies a set of request and response(s) and must be used to perform additional operations with a stream or to identify its messages. + Stream references use the Erlang reference data type and are therefore unique. + Streams can be canceled at any time.</description> + </item> + + <item> + <title>Embedded mode</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/guide/embedded/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/guide/embedded/</guid> + <description>Embedded mode allows you to insert Ranch listeners directly in your supervision tree. This allows for greater fault tolerance control by permitting the shutdown of a listener due to the failure of another part of the application and vice versa. + Embedding To embed Ranch in your application you can simply add the child specs to your supervision tree. This can all be done in the init/1 function of one of your application supervisors.</description> + </item> + + <item> + <title>Embedded mode</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/guide/embedded/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/guide/embedded/</guid> + <description>Embedded mode allows you to insert Ranch listeners directly in your supervision tree. This allows for greater fault tolerance control by permitting the shutdown of a listener due to the failure of another part of the application and vice versa. + Embedding To embed Ranch in your application you can simply add the child specs to your supervision tree. This can all be done in the init/1 function of one of your application supervisors.</description> + </item> + + <item> + <title>Limitations</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/limitations/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/limitations/</guid> + <description>No software is perfect. + It&#8217;s very important, when evaluating and when using a tool, to understand its limitations, so as to avoid making mistakes and wasting valuable time. + This chapter lists all known limitations of Erlang.mk. + Erlang must be available Currently Erlang.mk requires you to install Erlang beforehand. Installing Erlang is not always easy, particularly if you need a specific version of Erlang for a specific project.</description> + </item> + + <item> + <title>Flow diagram</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/flow_diagram/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/flow_diagram/</guid> + <description>Cowboy is a lightweight HTTP server with support for HTTP/1.1, HTTP/2 and Websocket. + It is built on top of Ranch. Please see the Ranch guide for more information about how the network connections are handled. + Overview As you can see on the diagram, the client begins by connecting to the server. This step is handled by a Ranch acceptor, which is a process dedicated to accepting new connections.</description> + </item> + + <item> + <title>Websocket</title> + <link>https://ninenines.eu/docs/en/gun/1.0/guide/websocket/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/gun/1.0/guide/websocket/</guid> + <description>This chapter describes how to use the Gun client for communicating with a Websocket server. + @todo recovering from connection failure reconnecting to Websocket etc. + HTTP upgrade Websocket is a protocol built on top of HTTP. To use Websocket, you must first request for the connection to be upgraded. Only HTTP/1.1 connections can be upgraded to Websocket, so you might need to restrict the protocol to HTTP/1.1 if you are planning to use Websocket over TLS.</description> + </item> + + <item> + <title>Writing parsers</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/guide/parsers/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/guide/parsers/</guid> + <description>There are three kinds of protocols: + Text protocols Schema-less binary protocols Schema-based binary protocols This chapter introduces the first two kinds. It will not cover more advanced topics such as continuations or parser generators. + This chapter isn&#8217;t specifically about Ranch, we assume here that you know how to read data from the socket. The data you read and the data that hasn&#8217;t been parsed is saved in a buffer.</description> + </item> + + <item> + <title>Writing parsers</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/guide/parsers/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/guide/parsers/</guid> + <description>There are three kinds of protocols: + Text protocols Schema-less binary protocols Schema-based binary protocols This chapter introduces the first two kinds. It will not cover more advanced topics such as continuations or parser generators. + This chapter isn&#8217;t specifically about Ranch, we assume here that you know how to read data from the socket. The data you read and the data that hasn&#8217;t been parsed is saved in a buffer.</description> + </item> + + <item> + <title>Building</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/app/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/app/</guid> + <description>Erlang.mk can do a lot of things, but it is, first and foremost, a build tool. In this chapter we will cover the basics of building a project with Erlang.mk. + For most of this chapter, we will assume that you are using a project generated by Erlang.mk. + How to build To build a project, all you have to do is type make: + $ make It will work regardless of your project: OTP applications, library applications, NIFs, port drivers or even releases.</description> + </item> + + <item> + <title>Listeners</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/listeners/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/listeners/</guid> + <description>A listener is a set of processes that listens on a port for new connections. Incoming connections get handled by Cowboy. Depending on the connection handshake, one or another protocol may be used. + This chapter is specific to Cowboy. Please refer to the Ranch User Guide for more information about listeners. + Cowboy provides two types of listeners: one listening for clear TCP connections, and one listening for secure TLS connections.</description> + </item> + + <item> + <title>SSL client authentication</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/guide/ssl_auth/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/guide/ssl_auth/</guid> + <description>Purpose SSL client authentication is a mechanism allowing applications to identify certificates. This allows your application to make sure that the client is an authorized certificate, but makes no claim about whether the user can be trusted. This can be combined with a password based authentication to attain greater security. + The server only needs to retain the certificate serial number and the certificate issuer to authenticate the certificate. Together, they can be used to uniquely identify a certicate.</description> + </item> + + <item> + <title>SSL client authentication</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/guide/ssl_auth/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/guide/ssl_auth/</guid> + <description>Purpose SSL client authentication is a mechanism allowing applications to identify certificates. This allows your application to make sure that the client is an authorized certificate, but makes no claim about whether the user can be trusted. This can be combined with a password based authentication to attain greater security. + The server only needs to retain the certificate serial number and the certificate issuer to authenticate the certificate. Together, they can be used to uniquely identify a certicate.</description> + </item> + + <item> + <title>Packages and dependencies</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/deps/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/deps/</guid> + <description>Erlang.mk can fetch and compile the dependencies that your project requires. Erlang.mk improves upon the concepts introduced by Rebar, so they should be familiar to many seasoned Erlang developers. + Erlang.mk is not a package manager, nor is it trying to be, but it does include an index of Erlang packages to make discovering useful projects easier. + This chapter will explain how to use packages, add dependencies to your project or bundle them directly in a single repository.</description> + </item> + + <item> + <title>Routing</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/routing/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/routing/</guid> + <description>Cowboy does nothing by default. + To make Cowboy useful, you need to map URIs to Erlang modules that will handle the requests. This is called routing. + When Cowboy receives a request, it tries to match the requested host and path to the configured routes. When there&#8217;s a match, the route&#8217;s associated handler is executed. + Routes need to be compiled before they can be used by Cowboy. The result of the compilation is the dispatch rules.</description> + </item> + + <item> + <title>NIFs and port drivers</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/ports/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/ports/</guid> + <description>Erlang.mk can not only build Erlang projects, but also the C code that some projects come with, like NIFs and port drivers. + There are two ways to build the C code: using a custom Makefile, or making Erlang.mk do it directly. The C code will be built as needed when you run make. + C source code location and Erlang environment The C source code should be located in the $(C_SRC_DIR) directory.</description> + </item> + + <item> + <title>Internals</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/guide/internals/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/guide/internals/</guid> + <description>This chapter may not apply to embedded Ranch as embedding allows you to use an architecture specific to your application, which may or may not be compatible with the description of the Ranch application. + Note that for everything related to efficiency and performance, you should perform the benchmarks yourself to get the numbers that matter to you. Generic benchmarks found on the web may or may not be of use to you, you can never know until you benchmark your own system.</description> + </item> + + <item> + <title>Internals</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/guide/internals/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/guide/internals/</guid> + <description>This chapter may not apply to embedded Ranch as embedding allows you to use an architecture specific to your application, which may or may not be compatible with the description of the Ranch application. + Note that for everything related to efficiency and performance, you should perform the benchmarks yourself to get the numbers that matter to you. Generic benchmarks found on the web may or may not be of use to you, you can never know until you benchmark your own system.</description> + </item> + + <item> + <title>Constraints</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/constraints/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/constraints/</guid> + <description>Constraints are validation and conversion functions applied to user input. + They are used in various places in Cowboy, including the router and the cowboy_req match functions. + Syntax Constraints are provided as a list of fields. For each field in the list, specific constraints can be applied, as well as a default value if the field is missing. + A field can take the form of an atom field, a tuple with constraints {field, Constraints} or a tuple with constraints and a default value {field, Constraints, Default}.</description> + </item> + + <item> + <title>Releases</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/releases/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/releases/</guid> + <description>Erlang.mk relies on Relx for generating releases. This chapter covers the Erlang.mk-specific bits. Consult the Relx website for more information. + Setup Erlang.mk will create a release if it detects a Relx configuration file in the $(RELX_CONFIG) location. This defaults to $(CURDIR)/relx.config. You can override it by defining the variable before including Erlang.mk: + RELX_CONFIG = $(CURDIR)/webchat.config Relx does not need to be installed. Erlang.mk will download and build it automatically.</description> + </item> + + <item> + <title>Self-extracting releases</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/sfx/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/sfx/</guid> + <description>Erlang.mk allows you to package Relx releases as self-extracting archives. These archives contain all the files in the release and come in the form of a script that will extract and run the release automatically. + This allows you to package the release as a single file that can then be executed. + This feature is currently experimental. Feedback is much appreciated. + Generating the self-extracting archive To generate a self-extracting release, all you need to do is pass the SFX=1 variable to Make when you build the release:</description> + </item> + + <item> + <title>Handlers</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/handlers/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/handlers/</guid> + <description>Handlers are Erlang modules that handle HTTP requests. + Plain HTTP handlers 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 Req object and the initial state defined in the router configuration. + A handler that does nothing would look like this: + init(Req, State) -&gt; {ok, Req, State}. 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.</description> + </item> + + <item> + <title>Escripts</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/escripts/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/escripts/</guid> + <description>Escripts are an alternative to release. They are meant to be used for small command line executables written in Erlang. + They are not self-contained, unlike releases. Erlang must be installed for them to run. This however means that they are fairly small compared to releases. + For self-contained executables, check self-extracting releases. + Requirements Erlang.mk uses p7zip by default to generate the escript archive. Make sure it is installed. On most systems the package is named p7zip; on Ubuntu you need p7zip-full.</description> + </item> + + <item> + <title>Loop handlers</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/loop_handlers/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/loop_handlers/</guid> + <description>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 a response. + Loop handlers are used for requests where a response might not be immediately available, but where you would like to keep the connection open for a while in case the response arrives. The most known example of such practice is known as long polling.</description> + </item> + + <item> + <title>OTP version management</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/kerl/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/kerl/</guid> + <description>Erlang.mk comes with integrated support for Kerl, a shell script that automates the downloading, building and installing of Erlang/OTP. It can be used to easily build a specific Erlang/OTP version (with or without custom build options) or maintain different versions side by side. + Erlang versions Erlang.mk uses the Git tags from Erlang/OTP to identify OTP versions. The most recent tag at the time of writing is OTP-20.0.4, which is a patch release of OTP-20.</description> + </item> + + <item> + <title>Static files</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/static_files/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/static_files/</guid> + <description>Cowboy comes with a ready to use handler for serving static files. It is provided as a convenience for serving files during development. + For systems in production, consider using one of the many Content Distribution Network (CDN) available on the market, as they are the best solution for serving files. + The static handler can serve either one file or all files from a given directory. The etag generation and mime types can be configured.</description> + </item> + + <item> + <title>Compatibility with other build tools</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/compat/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/compat/</guid> + <description>Erlang.mk tries its best to be compatible with the other Erlang build tools. It can use dependencies written with other build tools in mind, and can also make your projects usable by those build tools as well. Erlang.mk is like the cool kid that gets along with everybody. + In this chapter I will use the term Rebar project to refer to a project built using Rebar 2, Rebar 3 or Mad.</description> + </item> + + <item> + <title>AsciiDoc documentation</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/asciidoc/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/asciidoc/</guid> + <description>Erlang.mk provides rules for generating documentation from AsciiDoc files. It can automatically build a user guide PDF, chunked HTML documentation and Unix manual pages. + Requirements It is necessary to have AsciiDoc, xsltproc and dblatex installed on your system for Erlang.mk to generate documentation from AsciiDoc sources. + Writing AsciiDoc documentation AsciiDoc is a text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages, man pages and blogs.</description> + </item> + + <item> + <title>The Req object</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/req/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/req/</guid> + <description>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.</description> + </item> + + <item> + <title>Reading the request body</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/req_body/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/req_body/</guid> + <description>The request body can be read using the Req object. + 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 cache the body, it is therefore only possible to read it once. + 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.</description> + </item> + + <item> + <title>EDoc comments</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/edoc/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/edoc/</guid> + <description>Erlang.mk provides a thin wrapper on top of EDoc, an application that generates documentation based on comments found in modules. + Writing EDoc comments The EDoc user guide explains everything you need to know about EDoc comments. + Configuration The EDOC_OPTS variable allows you to specify additional EDoc options. Options are documented in the EDoc manual. + A common use for this variable is to enable Markdown in doc comments, using the edown application:</description> + </item> + + <item> + <title>Erlang shell</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/shell/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/shell/</guid> + <description>Erlang.mk provides a convenient target for starting a shell with all the paths set properly to experiment with your code. + Configuration The SHELL_DEPS variable can be used to define dependencies that are only to be used when the make shell command is called. For example, if you want to use kjell as your shell: + SHELL_DEPS = kjell Dependencies are downloaded and compiled the first time you run the make shell command.</description> + </item> + + <item> + <title>Sending a response</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/resp/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/resp/</guid> + <description>The response must be sent using the Req object. + Cowboy provides two different ways of sending responses: either directly or by streaming the body. Response headers and body may be set in advance. The response is sent as soon as one of the reply or stream reply function is called. + Cowboy also provides a simplified interface for sending files. It can also send only specific parts of a file.</description> + </item> + + <item> + <title>EUnit</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/eunit/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/eunit/</guid> + <description>EUnit is the tool of choice for unit testing. Erlang.mk automates a few things on top of EUnit, including the discovery and running of unit tests. + Writing tests The EUnit user guide is the best place to learn how to write tests. Of note is that all functions ending with _test or _test_ will be picked up as EUnit test cases. + Erlang.mk will automatically pick up tests found in any of the Erlang modules of your application.</description> + </item> + + <item> + <title>Using cookies</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/cookies/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/cookies/</guid> + <description>Cookies are a mechanism allowing applications to maintain state on top of the stateless HTTP protocol. + Cookies are a name/value store where the names and values are stored in plain text. They expire either after a delay or when the browser closes. They can be configured on a specific domain name or path, and restricted to secure resources (sent or downloaded over HTTPS), or restricted to the server (disallowing access from client-side scripts).</description> + </item> + + <item> + <title>Common Test</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/common_test/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/common_test/</guid> + <description>Common Test is Erlang&#8217;s functional testing framework. Erlang.mk automates the discovery and running of Common Test suites. + Writing tests The Common Test user guide is the best place to learn how to write tests. Erlang.mk requires that file names for test suites end with _SUITE.erl and that the files be located in the $(TEST_DIR) directory. This defaults to test/. + Configuration The CT_OPTS variable allows you to set extra Common Test options.</description> + </item> + + <item> + <title>Multipart requests</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/multipart/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/multipart/</guid> + <description>Multipart originates from MIME, an Internet standard that extends the format of emails. + A multipart message is a list of parts. A part contains headers and a body. The body of the parts may be of any media type, and contain text or binary data. It is possible for parts to contain a multipart media type. + In the context of HTTP, multipart is most often used with the multipart/form-data media type.</description> + </item> + + <item> + <title>Code coverage</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/coverage/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/coverage/</guid> + <description>Placeholder chapter. + </description> + </item> + + <item> + <title>REST principles</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/rest_principles/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/rest_principles/</guid> + <description>This chapter will attempt to define the concepts behind REST and explain what makes a service RESTful. + REST is often confused with performing a distinct operation depending on the HTTP method, while using more than the GET and POST methods. That&#8217;s highly misguided at best. + We will first attempt to define REST and will look at what it means in the context of HTTP and the Web. For a more in-depth explanation of REST, you can read Roy T.</description> + </item> + + <item> + <title>Continuous integration</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/ci/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/ci/</guid> + <description>Erlang.mk comes with some support for continuous integration, aimed at open source projects that need to support more than one specific Erlang/OTP release. (If you target one specific release, check the OTP version pinning section of the OTP version management chapter.) + Configuring Erlang/OTP versions to test To use the CI plugin you must first configure which versions of Erlang/OTP will be used. Erlang.mk provides three separate configuration variables depending on whether you need a normal OTP release, a HiPE-enabled release or an ErLLVM-enabled release.</description> + </item> + + <item> + <title>REST handlers</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/rest_handlers/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/rest_handlers/</guid> + <description>REST is implemented in Cowboy as a sub protocol. The request is handled as a state machine with many optional callbacks describing the resource and modifying the machine&#8217;s behavior. + The REST handler is the recommended way to handle HTTP requests. + Initialization First, the init/2 callback is called. This callback is common to all handlers. To use REST for the current request, this function must return a cowboy_rest tuple.</description> + </item> + + <item> + <title>Dialyzer</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/dialyzer/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/dialyzer/</guid> + <description>Dialyzer is a tool that will detect discrepancies in your program. It does so using a technique known as success typing analysis which has the advantage of providing no false positives. Dialyzer is able to detect type errors, dead code and more. + Erlang.mk provides a wrapper around Dialyzer. + How it works Dialyzer requires a PLT file to work. The PLT file contains the analysis information from all applications which are not expected to change, or rarely do.</description> + </item> + + <item> + <title>Xref</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/xref/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/xref/</guid> + <description>Placeholder chapter. + </description> + </item> + + <item> + <title>REST flowcharts</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/rest_flowcharts/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/rest_flowcharts/</guid> + <description>This chapter will explain the REST handler state machine through a number of different diagrams. + There are four main paths that requests may follow. One for the method OPTIONS; one for the methods GET and HEAD; one for the methods PUT, POST and PATCH; and one for the method DELETE. + All paths start with the "Start" diagram, and all paths excluding the OPTIONS path go through the "Content negotiation"</description> + </item> + + <item> + <title>External plugins</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/external_plugins/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/external_plugins/</guid> + <description>It is often convenient to be able to keep the build files used by all your projects in one place. Those files could be Makefiles, configuration files, templates and more. + Erlang.mk allows you to automatically load plugins from dependencies. Plugins can do anything, including defining new variables, defining file templates, hooking themselves inside the normal Erlang.mk processing or even adding new rules. + You can load plugins using one of two methods.</description> + </item> + + <item> + <title>Designing a resource handler</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/resource_design/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/resource_design/</guid> + <description>This chapter aims to provide you with a list of questions you must answer in order to write a good resource handler. It is meant to be usable as a step by step guide. + The service Can the service become unavailable, and when it does, can we detect it? For example, database connectivity problems may be detected early. We may also have planned outages of all or parts of the system.</description> + </item> + + <item> + <title>List of plugins</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/external_plugins_list/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/external_plugins_list/</guid> + <description>This is a non-exhaustive list of Erlang.mk plugins, sorted alphabetically. + efene.mk An Efene plugin for Erlang.mk. Efene is an alternative language for the BEAM. + elixir.mk An Elixir plugin for Erlang.mk. Elixir is an alternative language for the BEAM. + elvis.mk An Elvis plugin for Erlang.mk. Elvis is an Erlang style reviewer. + geas Geas gives aggregated information on a project and its dependencies, and is available as an Erlang.</description> + </item> + + <item> + <title>The Websocket protocol</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/ws_protocol/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/ws_protocol/</guid> + <description>This chapter explains what Websocket is and why it is a vital component of soft realtime Web applications. + Description Websocket is an extension to HTTP that emulates plain TCP connections between the client, typically a Web browser, and the server. It uses the HTTP Upgrade mechanism to establish the connection. + Websocket connections are fully asynchronous, unlike HTTP/1.1 (synchronous) and HTTP/2 (asynchronous, but the server can only initiate streams in response to requests).</description> + </item> + + <item> + <title>Why Erlang.mk</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/why/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/why/</guid> + <description>Why would you choose Erlang.mk, if not for its many features? This chapter will attempt to answer that. + Erlang.mk is fast Erlang.mk is as fast as it gets. + Erlang.mk will group the compilation of files so as to avoid running the BEAM more than necessary. This saves many seconds compared to traditional Makefiles, even on small projects. + Erlang.mk will not try to be too smart. It provides a simple solution that works for most people, and gives additional options for projects that run into edge cases, often in the form of extra variables or rules to be defined.</description> + </item> + + <item> + <title>Websocket handlers</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/ws_handlers/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/ws_handlers/</guid> + <description>Websocket handlers provide an interface for upgrading HTTP/1.1 connections to Websocket and sending or receiving frames on the Websocket connection. + As Websocket connections are established through the HTTP/1.1 upgrade mechanism, Websocket handlers need to be able to first receive the HTTP request for the upgrade, before switching to Websocket and taking over the connection. They can then receive or send Websocket frames, handle incoming Erlang messages or close the connection.</description> + </item> + + <item> + <title>Short history</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/history/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/history/</guid> + <description>This chapter aims to be a brief record of the life of the Erlang.mk project. + Before Erlang.mk Erlang.mk originates from the Cowboy project. Cowboy started as a Rebar project and I, Loïc Hoguin, was very happy with it for a couple years. Over time however I started getting annoyed and frustrated by a number of things, including bad defaults, changing defaults and overall slowness. + In particular, at the time I gave up on Rebar, the Cowboy test suite was taking about five minutes to run.</description> + </item> + + <item> + <title>Streams</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/streams/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/streams/</guid> + <description>A stream is the set of messages that form an HTTP request/response pair. + The term stream comes from HTTP/2. In Cowboy, it is also used when talking about HTTP/1.1 or HTTP/1.0. It should not be confused with streaming the request or response body. + All versions of HTTP allow clients to initiate streams. HTTP/2 is the only one also allowing servers, through its server push feature. Both client and server-initiated streams go through the same process in Cowboy.</description> + </item> + + <item> + <title>Contributing</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/contributing/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/contributing/</guid> + <description>You are welcome and encouraged to contribute. + This is how. + Priorities From the most important to the least important: + Bugs Package issues/additions Refactoring Features Bugs If you have found a bug, you should open a ticket. Include everything relevant including the command you used, output, a link to the code that triggers the issue, why you think this is a bug, etc.</description> + </item> + + <item> + <title>Middlewares</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/middlewares/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/middlewares/</guid> + <description>Cowboy delegates the request processing to middleware components. By default, two middlewares are defined, for the routing and handling of the request, as is detailed in most of this guide. + Middlewares give you complete control over how requests are to be processed. You can add your own middlewares to the mix or completely change the chain of middlewares as needed. + Cowboy will execute all middlewares in the given order, unless one of them decides to stop processing.</description> + </item> + + <item> + <title>Migrating from Cowboy 1.0 to 2.0</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/migrating_from_1.0/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/migrating_from_1.0/</guid> + <description>A lot has changed between Cowboy 1.0 and 2.0. The cowboy_req interface in particular has seen a massive revamp. Hooks are gone, their functionality can now be achieved via stream handlers. + The documentation has seen great work, in particular the manual. Each module and each function now has its own dedicated manual page with full details and examples. + Compatibility Compatibility with Erlang/OTP R16, 17 and 18 has been dropped.</description> + </item> + + <item> + <title>HTTP and other specifications</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/specs/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/specs/</guid> + <description>This chapter intends to list all the specification documents for or related to HTTP. + HTTP IANA Registries HTTP Method Registry HTTP Status Code Registry Message Headers HTTP Parameters HTTP Alt-Svc Parameter Registry HTTP Authentication Scheme Registry HTTP Cache Directive Registry HTTP Digest Algorithm Values HTTP Origin-Bound Authentication Device Identifier Types HTTP Upgrade Token Registry HTTP Warn Codes HTTP/2 Parameters WebSocket Protocol Registries Current CORS: Cross-Origin Resource Sharing CSP2: Content Security Policy Level 2 DNT: Tracking Preference Expression (DNT) eventsource: Server-Sent Events Form content types: Form content types Preload: Preload REST: Fielding&#8217;s Dissertation RFC 1945: HTTP/1.</description> + </item> <item> <title>Cowboy Function Reference</title> @@ -14,167 +843,11 @@ <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/</guid> - <description><div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy - Small, fast, modern HTTP server for Erlang/OTP</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy is an HTTP server for Erlang/OTP with support for the
-HTTP/1.1, HTTP/2 and Websocket protocols.</p></div>
-<div class="paragraph"><p>Cowboy aims to provide a complete HTTP stack. This includes
-the implementation of the HTTP RFCs but also any directly
-related standards, like Websocket or Server-Sent Events.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_modules">Modules</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Functions:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="cowboy">cowboy(3)</a> - Listener management
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_req">cowboy_req(3)</a> - Request and response
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_router">cowboy_router(3)</a> - Router
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Protocols:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="cowboy_http">cowboy_http(3)</a> - HTTP/1.1
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_http2">cowboy_http2(3)</a> - HTTP/2
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_websocket">cowboy_websocket(3)</a> - Websocket
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Handlers:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="cowboy_static">cowboy_static(3)</a> - Static file handler
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Behaviors:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="cowboy_handler">cowboy_handler(3)</a> - Plain HTTP handlers
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_loop">cowboy_loop(3)</a> - Loop handlers
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_middleware">cowboy_middleware(3)</a> - Middlewares
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_rest">cowboy_rest(3)</a> - REST handlers
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_stream">cowboy_stream(3)</a> - Stream handlers
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_websocket">cowboy_websocket(3)</a> - Websocket handlers
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Middlewares:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="cowboy_router">cowboy_router(3)</a> - Router middleware
-</p>
-</li>
-<li>
-<p>
-<a href="cowboy_handler">cowboy_handler(3)</a> - Handler middleware
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_dependencies">Dependencies</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="https://ninenines.eu/docs">ranch(7)</a> - Socket acceptor pool for TCP protocols
-</p>
-</li>
-<li>
-<p>
-<a href="https://ninenines.eu/docs">cowlib(7)</a> - Support library for manipulating Web protocols
-</p>
-</li>
-<li>
-<p>
-ssl - Secure communication over sockets
-</p>
-</li>
-<li>
-<p>
-crypto - Crypto functions
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>All these applications must be started before the <code>cowboy</code>
-application. To start Cowboy and all dependencies at once:</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: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">application:ensure_all_started</span></span>(<span style="color: #FF6600">cowboy</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_environment">Environment</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>cowboy</code> application does not define any application
-environment configuration parameters.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="https://ninenines.eu/docs">ranch(7)</a>,
-<a href="https://ninenines.eu/docs">cowlib(7)</a></p></div>
-</div>
-</div>
-</description> + <description>Name cowboy - Small, fast, modern HTTP server for Erlang/OTP + Description Cowboy is an HTTP server for Erlang/OTP with support for the HTTP/1.1, HTTP/2 and Websocket protocols. + Cowboy aims to provide a complete HTTP stack. This includes the implementation of the HTTP RFCs but also any directly related standards, like Websocket or Server-Sent Events. + Modules Functions: + cowboy(3) - Listener management cowboy_req(3) - Request and response cowboy_router(3) - Router cowboy_constraints(3) - Constraints Protocols:</description> </item> <item> @@ -183,202 +856,7 @@ environment configuration parameters.</p></div> <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/</guid> - <description><div class="sect1">
-<h2 id="_rationale">Rationale</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="modern_web/">The modern Web</a>
-</p>
-</li>
-<li>
-<p>
-<a href="erlang_web/">Erlang and the Web</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_introduction">Introduction</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="introduction/">Introduction</a>
-</p>
-</li>
-<li>
-<p>
-<a href="getting_started/">Getting started</a>
-</p>
-</li>
-<li>
-<p>
-<a href="flow_diagram/">Flow diagram</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_configuration">Configuration</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="listeners/">Listeners</a>
-</p>
-</li>
-<li>
-<p>
-<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="_handlers">Handlers</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="handlers/">Handlers</a>
-</p>
-</li>
-<li>
-<p>
-<a href="loop_handlers/">Loop handlers</a>
-</p>
-</li>
-<li>
-<p>
-<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>
-<p>
-<a href="req_body/">Reading the request body</a>
-</p>
-</li>
-<li>
-<p>
-<a href="resp/">Sending a response</a>
-</p>
-</li>
-<li>
-<p>
-<a href="cookies/">Using cookies</a>
-</p>
-</li>
-<li>
-<p>
-<a href="multipart/">Multipart</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_rest">REST</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="rest_principles/">REST principles</a>
-</p>
-</li>
-<li>
-<p>
-<a href="rest_handlers/">Handling REST requests</a>
-</p>
-</li>
-<li>
-<p>
-<a href="rest_flowcharts/">REST flowcharts</a>
-</p>
-</li>
-<li>
-<p>
-<a href="resource_design/">Designing a resource handler</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_websocket">Websocket</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="ws_protocol/">The Websocket protocol</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ws_handlers/">Websocket handlers</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_advanced">Advanced</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="streams/">Streams</a>
-</p>
-</li>
-<li>
-<p>
-<a href="middlewares/">Middlewares</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_additional_information">Additional information</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="migrating_from_1.0/">Migrating from Cowboy 1.0 to 2.0</a>
-</p>
-</li>
-</ul></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="specs/">HTTP and other specifications</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-</description> + <description>Rationale The modern Web Erlang and the Web Introduction Introduction Getting started Flow diagram Configuration Listeners Routing Constraints Handlers Handlers Loop handlers Static files Request and response Request details Reading the request body Sending a response Using cookies Multipart REST REST principles Handling REST requests REST flowcharts Designing a resource handler Websocket The Websocket protocol Websocket handlers Advanced Streams Middlewares Additional information Migrating from Cowboy 1.</description> </item> <item> @@ -387,174 +865,7 @@ environment configuration parameters.</p></div> <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/</guid> - <description><div class="ulist"><ul>
-<li>
-<p>
-<a href="installation/">Installation</a>
-</p>
-</li>
-<li>
-<p>
-<a href="getting_started/">Getting started</a>
-</p>
-</li>
-<li>
-<p>
-<a href="overview/">Overview</a>
-</p>
-</li>
-<li>
-<p>
-<a href="updating/">Updating Erlang.mk</a>
-</p>
-</li>
-<li>
-<p>
-<a href="limitations/">Limitations</a>
-</p>
-</li>
-</ul></div>
-<div class="sect1">
-<h2 id="code">Code</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="app/">Building</a>
-</p>
-</li>
-<li>
-<p>
-<a href="deps/">Packages and dependencies</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ports/">NIFs and port drivers</a>
-</p>
-</li>
-<li>
-<p>
-<a href="releases/">Releases</a>
-</p>
-</li>
-<li>
-<p>
-<a href="sfx/">Self-extracting releases</a>
-</p>
-</li>
-<li>
-<p>
-<a href="escripts/">Escripts</a>
-</p>
-</li>
-<li>
-<p>
-<a href="compat/">Compatibility with other build tools</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="docs">Documentation</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="asciidoc/">Asciidoc documentation</a>
-</p>
-</li>
-<li>
-<p>
-<a href="edoc/">EDoc comments</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="tests">Tests</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="shell/">Erlang shell</a>
-</p>
-</li>
-<li>
-<p>
-<a href="eunit/">EUnit</a>
-</p>
-</li>
-<li>
-<p>
-<a href="common_test/">Common Test</a>
-</p>
-</li>
-<li>
-<p>
-<a href="coverage/">Code coverage</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ci/">Continuous integration</a>
-</p>
-</li>
-<li>
-<p>
-<a href="dialyzer/">Dialyzer</a>
-</p>
-</li>
-<li>
-<p>
-<a href="xref/">Xref</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="plugins">Third-party plugins</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="external_plugins/">External plugins</a>
-</p>
-</li>
-<li>
-<p>
-<a href="external_plugins_list/">List of plugins</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="about">About Erlang.mk</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="why/">Why erlang.mk?</a>
-</p>
-</li>
-<li>
-<p>
-<a href="history/">Short history</a>
-</p>
-</li>
-<li>
-<p>
-<a href="contributing/">Contributing</a>
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-</description> + <description>Installation Getting started Overview Updating Erlang.mk Limitations Code Building Packages and dependencies NIFs and port drivers Releases Self-extracting releases Escripts OTP version management Compatibility with other build tools Documentation Asciidoc documentation EDoc comments Tests Erlang shell EUnit Common Test Code coverage Continuous integration Dialyzer Xref Third-party plugins External plugins List of plugins About Erlang.</description> </item> <item> @@ -563,19 +874,7 @@ environment configuration parameters.</p></div> <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> <guid>https://ninenines.eu/docs/en/gun/1.0/manual/</guid> - <description><div class="ulist"><ul>
-<li>
-<p>
-<a href="gun_app">gun(7)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="gun">gun(3)</a>
-</p>
-</li>
-</ul></div>
-</description> + <description> gun(7) gun(3) </description> </item> <item> @@ -584,39 +883,7 @@ environment configuration parameters.</p></div> <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> <guid>https://ninenines.eu/docs/en/gun/1.0/guide/</guid> - <description><div class="ulist"><ul>
-<li>
-<p>
-<a href="introduction/">Introduction</a>
-</p>
-</li>
-<li>
-<p>
-<a href="start/">Starting and stopping</a>
-</p>
-</li>
-<li>
-<p>
-<a href="protocols/">Supported protocols</a>
-</p>
-</li>
-<li>
-<p>
-<a href="connect/">Connection</a>
-</p>
-</li>
-<li>
-<p>
-<a href="http/">Using HTTP</a>
-</p>
-</li>
-<li>
-<p>
-<a href="websocket/">Using Websocket</a>
-</p>
-</li>
-</ul></div>
-</description> + <description> Introduction Starting and stopping Supported protocols Connection Using HTTP Using Websocket </description> </item> <item> @@ -625,272 +892,9 @@ environment configuration parameters.</p></div> <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/http_status_codes/</guid> - <description><div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>HTTP status codes - status codes used by Cowboy</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This chapter aims to list all HTTP status codes that Cowboy
-may return, with details on the reasons why. The list given
-here only includes the replies that Cowboy sends, not user
-replies.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_100_continue">100 Continue</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>When the client sends an <code>expect: 100-continue</code> header,
-Cowboy automatically sends a this status code before
-trying to read the request body. This behavior can be
-disabled using the appropriate body option.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_101_switching_protocols">101 Switching Protocols</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This is the status code sent when switching to the
-Websocket protocol.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_200_ok">200 OK</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_201_created">201 Created</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_202_accepted">202 Accepted</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_204_no_content">204 No Content</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent when the processing of a request
-ends without any reply having been sent. It may also be
-sent by <code>cowboy_rest</code> under normal conditions.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_300_multiple_choices">300 Multiple Choices</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_301_moved_permanently">301 Moved Permanently</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_303_see_other">303 See Other</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_304_not_modified">304 Not Modified</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_307_temporary_redirect">307 Temporary Redirect</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_400_bad_request">400 Bad Request</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy will send this status code for any of the
-following reasons:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Too many empty lines were sent before the request.
-</p>
-</li>
-<li>
-<p>
-The request-line could not be parsed.
-</p>
-</li>
-<li>
-<p>
-Too many headers were sent.
-</p>
-</li>
-<li>
-<p>
-A header name was too long.
-</p>
-</li>
-<li>
-<p>
-A header value was too long.
-</p>
-</li>
-<li>
-<p>
-The host header was missing from an HTTP/1.1 request.
-</p>
-</li>
-<li>
-<p>
-The host header could not be parsed.
-</p>
-</li>
-<li>
-<p>
-The requested host was not found.
-</p>
-</li>
-<li>
-<p>
-The requested path could not be parsed.
-</p>
-</li>
-<li>
-<p>
-The accept header could not be parsed when using REST.
-</p>
-</li>
-<li>
-<p>
-REST under normal conditions.
-</p>
-</li>
-<li>
-<p>
-A Websocket upgrade failed.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_401_unauthorized">401 Unauthorized</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_403_forbidden">403 Forbidden</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_404_not_found">404 Not Found</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent when the router successfully
-resolved the host but didn&#8217;t find a matching path for
-the request. It may also be sent by <code>cowboy_rest</code> under
-normal conditions.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_405_method_not_allowed">405 Method Not Allowed</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_406_not_acceptable">406 Not Acceptable</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_408_request_timeout">408 Request Timeout</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy will send this status code to the client if the
-client started to send a request, indicated by the
-request-line being received fully, but failed to send
-all headers in a reasonable time.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_409_conflict">409 Conflict</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_410_gone">410 Gone</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_412_precondition_failed">412 Precondition Failed</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_413_request_entity_too_large">413 Request Entity Too Large</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_414_request_uri_too_long">414 Request-URI Too Long</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy will send this status code to the client if the
-request-line is too long. It may also be sent by
-<code>cowboy_rest</code> under normal conditions.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_415_unsupported_media_type">415 Unsupported Media Type</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_500_internal_server_error">500 Internal Server Error</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent when a crash occurs in HTTP, loop
-or REST handlers, or when an invalid return value is
-returned. It may also be sent by <code>cowboy_rest</code> under
-normal conditions.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_501_not_implemented">501 Not Implemented</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_503_service_unavailable">503 Service Unavailable</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>This status code is sent by <code>cowboy_rest</code>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_505_http_version_not_supported">505 HTTP Version Not Supported</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy only supports the versions 1.0 and 1.1 of HTTP.
-In all other cases this status code is sent back to the
-client and the connection is closed.</p></div>
-</div>
-</div>
-</description> + <description>Name HTTP status codes - status codes used by Cowboy + Description This chapter aims to list all HTTP status codes that Cowboy may return, with details on the reasons why. The list given here only includes the replies that Cowboy sends, not user replies. + 100 Continue When the client sends an expect: 100-continue header, Cowboy automatically sends a this status code before trying to read the request body.</description> </item> <item> @@ -899,39 +903,7 @@ client and the connection is closed.</p></div> <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> <guid>https://ninenines.eu/docs/en/ranch/1.2/manual/</guid> - <description><div class="ulist"><ul>
-<li>
-<p>
-<a href="ranch_app">ranch(7)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch">ranch(3)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch_protocol">ranch_protocol(3)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch_ssl">ranch_ssl(3)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch_tcp">ranch_tcp(3)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch_transport">ranch_transport(3)</a>
-</p>
-</li>
-</ul></div>
-</description> + <description> ranch(7) ranch(3) ranch_protocol(3) ranch_ssl(3) ranch_tcp(3) ranch_transport(3) </description> </item> <item> @@ -940,39 +912,7 @@ client and the connection is closed.</p></div> <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> <guid>https://ninenines.eu/docs/en/ranch/1.3/manual/</guid> - <description><div class="ulist"><ul>
-<li>
-<p>
-<a href="ranch_app">ranch(7)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch">ranch(3)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch_protocol">ranch_protocol(3)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch_ssl">ranch_ssl(3)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch_tcp">ranch_tcp(3)</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ranch_transport">ranch_transport(3)</a>
-</p>
-</li>
-</ul></div>
-</description> + <description> ranch(7) ranch(3) ranch_protocol(3) ranch_ssl(3) ranch_tcp(3) ranch_transport(3) </description> </item> <item> @@ -981,49 +921,7 @@ client and the connection is closed.</p></div> <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> <guid>https://ninenines.eu/docs/en/ranch/1.2/guide/</guid> - <description><div class="ulist"><ul>
-<li>
-<p>
-<a href="introduction/">Introduction</a>
-</p>
-</li>
-<li>
-<p>
-<a href="listeners/">Listeners</a>
-</p>
-</li>
-<li>
-<p>
-<a href="transports/">Transports</a>
-</p>
-</li>
-<li>
-<p>
-<a href="protocols/">Protocols</a>
-</p>
-</li>
-<li>
-<p>
-<a href="embedded/">Embedded mode</a>
-</p>
-</li>
-<li>
-<p>
-<a href="parsers/">Writing parsers</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ssl_auth/">SSL client authentication</a>
-</p>
-</li>
-<li>
-<p>
-<a href="internals/">Internals</a>
-</p>
-</li>
-</ul></div>
-</description> + <description> Introduction Listeners Transports Protocols Embedded mode Writing parsers SSL client authentication Internals </description> </item> <item> @@ -1032,49 +930,7 @@ client and the connection is closed.</p></div> <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> <guid>https://ninenines.eu/docs/en/ranch/1.3/guide/</guid> - <description><div class="ulist"><ul>
-<li>
-<p>
-<a href="introduction/">Introduction</a>
-</p>
-</li>
-<li>
-<p>
-<a href="listeners/">Listeners</a>
-</p>
-</li>
-<li>
-<p>
-<a href="transports/">Transports</a>
-</p>
-</li>
-<li>
-<p>
-<a href="protocols/">Protocols</a>
-</p>
-</li>
-<li>
-<p>
-<a href="embedded/">Embedded mode</a>
-</p>
-</li>
-<li>
-<p>
-<a href="parsers/">Writing parsers</a>
-</p>
-</li>
-<li>
-<p>
-<a href="ssl_auth/">SSL client authentication</a>
-</p>
-</li>
-<li>
-<p>
-<a href="internals/">Internals</a>
-</p>
-</li>
-</ul></div>
-</description> + <description> Introduction Listeners Transports Protocols Embedded mode Writing parsers SSL client authentication Internals </description> </item> <item> @@ -1083,130 +939,9 @@ client and the connection is closed.</p></div> <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy/</guid> - <description><div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy - HTTP server</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The module <code>cowboy</code> provides convenience functions for
-manipulating Ranch listeners.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exports">Exports</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy.start_clear">cowboy:start_clear(3)</a> - Listen for connections using plain TCP
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy.start_tls">cowboy:start_tls(3)</a> - Listen for connections using TLS
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy.stop_listener">cowboy:stop_listener(3)</a> - Stop the given listener
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy.set_env">cowboy:set_env(3)</a> - Update a listener&#8217;s environment value
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_types">Types</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_fields">fields()</h3>
-<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">fields</span></span>() <span style="color: #990000">::</span> [<span style="color: #009900">Name</span>
- | {<span style="color: #009900">Name</span>, <span style="color: #009900">Constraints</span>}
- | {<span style="color: #009900">Name</span>, <span style="color: #009900">Constraints</span>, <span style="color: #009900">Default</span>}]
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>()
-<span style="color: #009900">Constraints</span> <span style="color: #990000">::</span> <span style="color: #009900">Constraint</span> | [<span style="color: #009900">Constraint</span>]
-<span style="color: #009900">Constraint</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_constraints:constraint</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Fields description for match operations.</p></div>
-<div class="paragraph"><p>This type is used in <a href="../cowboy_router">cowboy_router(3)</a>
-for matching bindings and in the match functions found in
-<a href="../cowboy_req">cowboy_req(3)</a>.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_http_headers">http_headers()</h3>
-<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">http_headers</span></span>() <span style="color: #990000">::</span> #{<span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="color: #990000">=&gt;</span> <span style="font-weight: bold"><span style="color: #000000">iodata</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>HTTP headers.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_http_status">http_status()</h3>
-<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">http_status</span></span>() <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>() | <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>HTTP response status.</p></div>
-<div class="paragraph"><p>A binary status can be used to set a reason phrase. Note
-however that HTTP/2 only sends the status code and drops
-the reason phrase entirely.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_http_version">http_version()</h3>
-<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">http_version</span></span>() <span style="color: #990000">::</span> <span style="color: #FF6600">'HTTP/2'</span> | <span style="color: #FF6600">'HTTP/1.1'</span> | <span style="color: #FF6600">'HTTP/1.0'</span></tt></pre></div></div>
-<div class="paragraph"><p>HTTP version.</p></div>
-<div class="paragraph"><p>Note that semantically, HTTP/1.1 and HTTP/2 are equivalent.</p></div>
-</div>
-<div class="sect2">
-<h3 id="_opts">opts()</h3>
-<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">opts</span></span>() <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">map</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Options for the HTTP/1.1, HTTP/2 and Websocket protocols.</p></div>
-<div class="paragraph"><p>The protocol options are in a map containing all the options for
-the different protocols that may be involved when connecting
-to the listener, including HTTP/1.1 and HTTP/2.</p></div>
-<div class="paragraph"><p>The HTTP/1.1 options are documented in the
-<a href="../cowboy_http">cowboy_http(3)</a> manual
-and the HTTP/2 options in
-<a href="../cowboy_http2">cowboy_http2(3)</a>.</p></div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="..">cowboy(7)</a>,
-<a href="../ranch">ranch(3)</a></p></div>
-</div>
-</div>
-</description> + <description>Name cowboy - HTTP server + Description The module cowboy provides convenience functions for manipulating Ranch listeners. + Exports cowboy:start_clear(3) - Listen for connections using plain TCP cowboy:start_tls(3) - Listen for connections using TLS cowboy:stop_listener(3) - Stop the given listener cowboy:set_env(3) - Update a listener&#8217;s environment value Types fields() fields() :: [Name | {Name, Constraints} | {Name, Constraints, Default}] Name :: atom() Constraints :: Constraint | [Constraint] Constraint :: cowboy_constraints:constraint() Default :: any() Fields description for match operations.</description> </item> <item> @@ -1215,167 +950,11 @@ and the HTTP/2 options in <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_app/</guid> - <description><div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy - Small, fast, modern HTTP server for Erlang/OTP</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Cowboy is an HTTP server for Erlang/OTP with support for the
-HTTP/1.1, HTTP/2 and Websocket protocols.</p></div>
-<div class="paragraph"><p>Cowboy aims to provide a complete HTTP stack. This includes
-the implementation of the HTTP RFCs but also any directly
-related standards, like Websocket or Server-Sent Events.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_modules">Modules</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Functions:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy">cowboy(3)</a> - Listener management
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_req">cowboy_req(3)</a> - Request and response
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_router">cowboy_router(3)</a> - Router
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Protocols:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy_http">cowboy_http(3)</a> - HTTP/1.1
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_http2">cowboy_http2(3)</a> - HTTP/2
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_websocket">cowboy_websocket(3)</a> - Websocket
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Handlers:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy_static">cowboy_static(3)</a> - Static file handler
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Behaviors:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy_handler">cowboy_handler(3)</a> - Plain HTTP handlers
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_loop">cowboy_loop(3)</a> - Loop handlers
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_middleware">cowboy_middleware(3)</a> - Middlewares
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_rest">cowboy_rest(3)</a> - REST handlers
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_stream">cowboy_stream(3)</a> - Stream handlers
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_websocket">cowboy_websocket(3)</a> - Websocket handlers
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Middlewares:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../cowboy_router">cowboy_router(3)</a> - Router middleware
-</p>
-</li>
-<li>
-<p>
-<a href="../cowboy_handler">cowboy_handler(3)</a> - Handler middleware
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_dependencies">Dependencies</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="../ranch">ranch(7)</a> - Socket acceptor pool for TCP protocols
-</p>
-</li>
-<li>
-<p>
-<a href="../cowlib">cowlib(7)</a> - Support library for manipulating Web protocols
-</p>
-</li>
-<li>
-<p>
-ssl - Secure communication over sockets
-</p>
-</li>
-<li>
-<p>
-crypto - Crypto functions
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>All these applications must be started before the <code>cowboy</code>
-application. To start Cowboy and all dependencies at once:</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: #990000">_</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">application:ensure_all_started</span></span>(<span style="color: #FF6600">cowboy</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_environment">Environment</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <code>cowboy</code> application does not define any application
-environment configuration parameters.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../ranch">ranch(7)</a>,
-<a href="../cowlib">cowlib(7)</a></p></div>
-</div>
-</div>
-</description> + <description>Name cowboy - Small, fast, modern HTTP server for Erlang/OTP + Description Cowboy is an HTTP server for Erlang/OTP with support for the HTTP/1.1, HTTP/2 and Websocket protocols. + Cowboy aims to provide a complete HTTP stack. This includes the implementation of the HTTP RFCs but also any directly related standards, like Websocket or Server-Sent Events. + Modules Functions: + cowboy(3) - Listener management cowboy_req(3) - Request and response cowboy_router(3) - Router cowboy_constraints(3) - Constraints Protocols:</description> </item> <item> @@ -1384,118 +963,11 @@ environment configuration parameters.</p></div> <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.set_env/</guid> - <description><div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy:set_env - Update a listener&#8217;s environment value</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">set_env</span></span>(<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch:ref</span></span>(),
- <span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">atom</span></span>(),
- <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>())
- <span style="color: #990000">-&gt;</span> <span style="color: #FF6600">ok</span></tt></pre></div></div>
-<div class="paragraph"><p>Set or update an environment value for a previously started
-listener.</p></div>
-<div class="paragraph"><p>This is most useful for updating the routes dynamically,
-without having to restart the listener.</p></div>
-<div class="paragraph"><p>The new value will only be available to new connections.
-Pre-existing connections will still use the old value.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name
-</dt>
-<dd>
-<p>
-The name of the listener to update.
-</p>
-<div class="paragraph"><p>The name of the listener is the first argument given to the
-<a href="../cowboy.start_clear">cowboy:start_clear(3)</a>,
-<a href="../cowboy.start_tls">cowboy:start_tls(3)</a> or
-<a href="../ranch.start_listener">ranch:start_listener(3)</a> function.</p></div>
-</dd>
-<dt class="hdlist1">
-Key
-</dt>
-<dd>
-<p>
-The key in the environment map. Common keys include <code>dispatch</code>
-and <code>middlewares</code>.
-</p>
-</dd>
-<dt class="hdlist1">
-Value
-</dt>
-<dd>
-<p>
-The new value.
-</p>
-<div class="paragraph"><p>The type of the value differs depending on the key.</p></div>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The atom <code>ok</code> is returned on success.</p></div>
-<div class="paragraph"><p>An <code>exit:badarg</code> exception is thrown when the listener does
-not exist.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Update a listener&#8217;s routes</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">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">toppage_h</span>, []},
- {<span style="color: #FF0000">"/ws"</span>, <span style="color: #FF6600">websocket_h</span>, []}
- ]}
-]),
-
-<span style="font-weight: bold"><span style="color: #000000">cowboy:set_env</span></span>(<span style="color: #FF6600">example</span>, <span style="color: #FF6600">dispatch</span>, <span style="color: #009900">Dispatch</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy">cowboy(3)</a>,
-<a href="../cowboy.start_clear">cowboy:start_clear(3)</a>,
-<a href="../cowboy.start_tls">cowboy:start_tls(3)</a>,
-<a href="../ranch.set_protocol_options">ranch:set_protocol_options(3)</a></p></div>
-</div>
-</div>
-</description> + <description>Name cowboy:set_env - Update a listener&#8217;s environment value + Description set_env(Name :: ranch:ref(), Key :: atom(), Value :: any()) -&gt; ok Set or update an environment value for a previously started listener. + This is most useful for updating the routes dynamically, without having to restart the listener. + The new value will only be available to new connections. Pre-existing connections will still use the old value. + Arguments Name The name of the listener to update.</description> </item> <item> @@ -1504,152 +976,9 @@ http://www.gnu.org/software/src-highlite --> <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.start_clear/</guid> - <description><div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy:start_clear - Listen for connections using plain TCP</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">start_clear</span></span>(<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch:ref</span></span>(),
- <span style="color: #009900">TransportOpts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch_tcp:opts</span></span>(),
- <span style="color: #009900">ProtocolOpts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">opts</span></span>())
- <span style="color: #990000">-&gt;</span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">ListenerPid</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">pid</span></span>()}
- | {<span style="color: #FF6600">error</span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>Start listening for connections over a clear TCP channel.</p></div>
-<div class="paragraph"><p>Both HTTP/1.1 and HTTP/2 are supported on this listener.
-HTTP/2 has two methods of establishing a connection over
-a clear TCP channel. Both the upgrade and the prior knowledge
-methods are supported.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name
-</dt>
-<dd>
-<p>
-The listener name is used to refer to this listener in
-future calls, for example when stopping it or when
-updating the routes defined.
-</p>
-<div class="paragraph"><p>It can be any Erlang term. An atom is generally good enough,
-for example <code>api</code>, <code>my_app_clear</code> or <code>my_app_tls</code>.</p></div>
-</dd>
-<dt class="hdlist1">
-TransportOpts
-</dt>
-<dd>
-<p>
-The transport options are where the TCP options, including
-the listener&#8217;s port number, are defined. Transport options
-are provided as a list of keys and values, for example
-<code>[{port, 8080}]</code>.
-</p>
-<div class="paragraph"><p>The available options are documented in the
-<a href="../ranch_tcp">ranch_tcp(3)</a> manual.</p></div>
-</dd>
-<dt class="hdlist1">
-ProtocolOpts
-</dt>
-<dd>
-<p>
-The protocol options are in a map containing all the options for
-the different protocols that may be involved when connecting
-to the listener, including HTTP/1.1 and HTTP/2 but also
-subprotocols like Websocket.
-</p>
-<div class="paragraph"><p>The HTTP/1.1 options are documented in the
-<a href="../cowboy_http">cowboy_http(3)</a> manual;
-the HTTP/2 options in
-<a href="../cowboy_http2">cowboy_http2(3)</a>;
-and the Websocket options in
-<a href="../cowboy_websocket">cowboy_websocket(3)</a>.</p></div>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An ok tuple is returned on success. It contains the pid of
-the top-level supervisor for the listener.</p></div>
-<div class="paragraph"><p>An error tuple is returned on error. The error reason may
-be any Erlang term.</p></div>
-<div class="paragraph"><p>A common error is <code>eaddrinuse</code>. It indicates that the port
-configured for Cowboy is already in use.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: HTTP/2 support added.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced. Replaces <code>cowboy:start_http/4</code>.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Start a listener</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">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">toppage_h</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">example</span>, [{<span style="color: #FF6600">port</span>, <span style="color: #993399">8080</span>}], #{
- <span style="color: #0000FF">env</span> <span style="color: #990000">=&gt;</span> #{<span style="color: #0000FF">dispatch</span> <span style="color: #990000">=&gt;</span> <span style="color: #009900">Dispatch</span>}
-})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Start a listener on a random port</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">Name</span> <span style="color: #990000">=</span> <span style="color: #FF6600">example</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: #009900">Name</span>, [], #{
- <span style="color: #0000FF">env</span> <span style="color: #990000">=&gt;</span> #{<span style="color: #0000FF">dispatch</span> <span style="color: #990000">=&gt;</span> <span style="color: #009900">Dispatch</span>}
-}),
-
-<span style="color: #009900">Port</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_port</span></span>(<span style="color: #009900">Name</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy">cowboy(3)</a>,
-<a href="../cowboy.start_tls">cowboy:start_tls(3)</a>,
-<a href="../cowboy.stop_listener">cowboy:stop_listener(3)</a>,
-<a href="../ranch">ranch(3)</a></p></div>
-</div>
-</div>
-</description> + <description>Name cowboy:start_clear - Listen for connections using plain TCP + Description start_clear(Name :: ranch:ref(), TransportOpts :: ranch_tcp:opts(), ProtocolOpts :: opts()) -&gt; {ok, ListenerPid :: pid()} | {error, any()} Start listening for connections over a clear TCP channel. + Both HTTP/1.1 and HTTP/2 are supported on this listener. HTTP/2 has two methods of establishing a connection over a clear TCP channel. Both the upgrade and the prior knowledge methods are supported.</description> </item> <item> @@ -1658,157 +987,857 @@ http://www.gnu.org/software/src-highlite --> <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.start_tls/</guid> - <description><div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy:start_tls - Listen for connections using TLS</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<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">start_tls</span></span>(<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch:ref</span></span>(),
- <span style="color: #009900">TransportOpts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">ranch_ssl:opts</span></span>(),
- <span style="color: #009900">ProtocolOpts</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">opts</span></span>())
- <span style="color: #990000">-&gt;</span> {<span style="color: #FF6600">ok</span>, <span style="color: #009900">ListenerPid</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">pid</span></span>()}
- | {<span style="color: #FF6600">error</span>, <span style="font-weight: bold"><span style="color: #000000">any</span></span>()}</tt></pre></div></div>
-<div class="paragraph"><p>Start listening for connections over a secure TLS channel.</p></div>
-<div class="paragraph"><p>Both HTTP/1.1 and HTTP/2 are supported on this listener.
-The ALPN TLS extension must be used to initiate an HTTP/2
-connection.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name
-</dt>
-<dd>
-<p>
-The listener name is used to refer to this listener in
-future calls, for example when stopping it or when
-updating the routes defined.
-</p>
-<div class="paragraph"><p>It can be any Erlang term. An atom is generally good enough,
-for example <code>api</code>, <code>my_app_clear</code> or <code>my_app_tls</code>.</p></div>
-</dd>
-<dt class="hdlist1">
-TransportOpts
-</dt>
-<dd>
-<p>
-The transport options are where the TCP options, including
-the listener&#8217;s port number, are defined. They also contain
-the TLS options, like the server&#8217;s certificate. Transport options
-are provided as a list of keys and values, for example
-<code>[{port, 8443}, {certfile, "path/to/cert.pem"}]</code>.
-</p>
-<div class="paragraph"><p>The available options are documented in the
-<a href="../ranch_ssl">ranch_ssl(3)</a> manual.</p></div>
-</dd>
-<dt class="hdlist1">
-ProtocolOpts
-</dt>
-<dd>
-<p>
-The protocol options are in a map containing all the options for
-the different protocols that may be involved when connecting
-to the listener, including HTTP/1.1 and HTTP/2 but also
-subprotocols like Websocket.
-</p>
-<div class="paragraph"><p>The HTTP/1.1 options are documented in the
-<a href="../cowboy_http">cowboy_http(3)</a> manual;
-the HTTP/2 options in
-<a href="../cowboy_http2">cowboy_http2(3)</a>;
-and the Websocket options in
-<a href="../cowboy_websocket">cowboy_websocket(3)</a>.</p></div>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>An ok tuple is returned on success. It contains the pid of
-the top-level supervisor for the listener.</p></div>
-<div class="paragraph"><p>An error tuple is returned on error. The error reason may
-be any Erlang term.</p></div>
-<div class="paragraph"><p>A common error is <code>eaddrinuse</code>. It indicates that the port
-configured for Cowboy is already in use.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: HTTP/2 support added.
-</p>
-</li>
-<li>
-<p>
-<strong>2.0</strong>: Function introduced. Replaces <code>cowboy:start_https/4</code>.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Start a listener</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">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">toppage_h</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_tls</span></span>(<span style="color: #FF6600">example</span>, [
- {<span style="color: #FF6600">port</span>, <span style="color: #993399">8443</span>},
- {<span style="color: #FF6600">cert</span>, <span style="color: #FF0000">"path/to/cert.pem"</span>}
-], #{
- <span style="color: #0000FF">env</span> <span style="color: #990000">=&gt;</span> #{<span style="color: #0000FF">dispatch</span> <span style="color: #990000">=&gt;</span> <span style="color: #009900">Dispatch</span>}
-})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Start a listener on a random port</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">Name</span> <span style="color: #990000">=</span> <span style="color: #FF6600">example</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_tls</span></span>(<span style="color: #009900">Name</span>, [
- {<span style="color: #FF6600">cert</span>, <span style="color: #FF0000">"path/to/cert.pem"</span>}
-], #{
- <span style="color: #0000FF">env</span> <span style="color: #990000">=&gt;</span> #{<span style="color: #0000FF">dispatch</span> <span style="color: #990000">=&gt;</span> <span style="color: #009900">Dispatch</span>}
-}),
-
-<span style="color: #009900">Port</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">ranch:get_port</span></span>(<span style="color: #009900">Name</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy">cowboy(3)</a>,
-<a href="../cowboy.start_clear">cowboy:start_clear(3)</a>,
-<a href="../cowboy.stop_listener">cowboy:stop_listener(3)</a>,
-<a href="../ranch">ranch(3)</a></p></div>
-</div>
-</div>
-</description> + <description>Name cowboy:start_tls - Listen for connections using TLS + Description start_tls(Name :: ranch:ref(), TransportOpts :: ranch_ssl:opts(), ProtocolOpts :: opts()) -&gt; {ok, ListenerPid :: pid()} | {error, any()} Start listening for connections over a secure TLS channel. + Both HTTP/1.1 and HTTP/2 are supported on this listener. The ALPN TLS extension must be used to initiate an HTTP/2 connection. + Arguments Name The listener name is used to refer to this listener in future calls, for example when stopping it or when updating the routes defined.</description> + </item> + + <item> + <title>cowboy:stop_listener(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.stop_listener/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.stop_listener/</guid> + <description>Name cowboy:stop_listener - Stop the given listener + Description stop_listener(Name :: ranch:ref()) -&gt; ok | {error, not_found}. Stop a previously started listener. + Alias of ranch:stop_listener(3). + Arguments Name The name of the listener to be stopped. The name of the listener is the first argument given to the cowboy:start_clear(3), cowboy:start_tls(3) or ranch:start_listener(3) function. + Return value The atom ok is returned on success.</description> + </item> + + <item> + <title>cowboy_constraints(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_constraints/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_constraints/</guid> + <description>Name cowboy_constraints - Constraints + Description The module cowboy_constraints defines the built-in constraints in Cowboy and provides an interface for manipulating these constraints. + Constraints are functions that define what type of input is allowed. They are used throughout Cowboy, from the router to query strings to cookies. + Exports Built-in constraints: + cowboy_constraints:int(3) - Integer constraint cowboy_constraints:nonempty(3) - Non-empty constraint Types constraint() constraint() :: int | nonempty | fun() A constraint function.</description> + </item> + + <item> + <title>cowboy_constraints:int(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_constraints.int/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_constraints.int/</guid> + <description>Name cowboy_constraints:int - Integer constraint + Description Constraint functions implement a number of different operations. + int(forward, Bin) -&gt; {ok, Int} | {error, not_an_integer} Bin :: binary() Int :: integer() Validate and convert the text representation of an integer. + int(reverse, Int) -&gt; {ok, Bin} | {error, not_an_integer} Convert an integer back to its text representation. + int(format_error, Error) -&gt; HumanReadable Error :: {not_an_integer, Bin | Int} HumanReadable :: iolist() Generate a human-readable error message.</description> + </item> + + <item> + <title>cowboy_constraints:nonempty(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_constraints.nonempty/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_constraints.nonempty/</guid> + <description>Name cowboy_constraints:nonempty - Non-empty constraint + Description Constraint functions implement a number of different operations. + nonempty(forward | reverse, &lt;&lt;&gt;&gt;) -&gt; {error, empty} Reject empty values. + nonempty(forward | reverse, Bin) -&gt; {ok, Bin} Bin :: binary() Accept any other binary values. + nonempty(format_error, Error) -&gt; HumanReadable Error :: {empty, Bin} HumanReadable :: iolist() Generate a human-readable error message. + Arguments Arguments vary depending on the operation.</description> + </item> + + <item> + <title>cowboy_handler(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_handler/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_handler/</guid> + <description>Name cowboy_handler - Plain HTTP handlers + Description The cowboy_handler middleware executes the handler selected by the router or any other preceding middleware. + This middleware takes the handler module and initial state from the handler and handler_opts environment values, respectively. On completion, it adds a result value to the middleware environment, containing the return value of the terminate/3 callback (if defined) and ok otherwise. + This module also defines a callback interface for handling HTTP requests.</description> + </item> + + <item> + <title>cowboy_handler:terminate(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_handler.terminate/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_handler.terminate/</guid> + <description>Name cowboy_handler:terminate - Terminate the handler + Description terminate(Reason, PartialReq, State, Handler) -&gt; ok Reason :: any() PartialReq :: map() State :: any() Handler :: module() Call the optional terminate callback if it is defined. + Make sure to use this function at the end of the execution of modules that implement custom handler behaviors. + Arguments Reason Reason for termination. PartialReq The Req object.</description> + </item> + + <item> + <title>cowboy_http(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_http/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_http/</guid> + <description>Name cowboy_http - HTTP/1.1 + Description The module cowboy_http implements HTTP/1.1 and HTTP/1.0 as a Ranch protocol. + Options opts() :: #{ connection_type =&gt; worker | supervisor, env =&gt; cowboy_middleware:env(), idle_timeout =&gt; timeout(), inactivity_timeout =&gt; timeout(), max_empty_lines =&gt; non_neg_integer(), max_header_name_length =&gt; non_neg_integer(), max_header_value_length =&gt; non_neg_integer(), max_headers =&gt; non_neg_integer(), max_keepalive =&gt; non_neg_integer(), max_method_length =&gt; non_neg_integer(), max_request_line_length =&gt; non_neg_integer(), middlewares =&gt; [module()], request_timeout =&gt; timeout(), shutdown_timeout =&gt; timeout(), stream_handlers =&gt; [module()] } Configuration for the HTTP/1.</description> + </item> + + <item> + <title>cowboy_http2(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_http2/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_http2/</guid> + <description>Name cowboy_http2 - HTTP/2 + Description The module cowboy_http2 implements HTTP/2 as a Ranch protocol. + Options opts() :: #{ connection_type =&gt; worker | supervisor, env =&gt; cowboy_middleware:env(), inactivity_timeout =&gt; timeout(), middlewares =&gt; [module()], preface_timeout =&gt; timeout(), shutdown_timeout =&gt; timeout(), stream_handlers =&gt; [module()] } Configuration for the HTTP/2 protocol. + This configuration is passed to Cowboy when starting listeners using cowboy:start_clear/3 or cowboy:start_tls/3 functions. + It can be updated without restarting listeners using the Ranch functions ranch:get_protocol_options/1 and ranch:set_protocol_options/2.</description> + </item> + + <item> + <title>cowboy_loop(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_loop/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_loop/</guid> + <description>Name cowboy_loop - Loop handlers + Description The module cowboy_loop defines a callback interface for long running HTTP connections. + You should switch to this behavior for long polling, server-sent events and similar long-running requests. + There are generally two usage patterns: + Loop until receiving a specific message, then send a response and stop execution (for example long polling); Or initiate a response in init/2 and stream the body in info/3 as necessary (for example server-sent events).</description> + </item> + + <item> + <title>cowboy_middleware(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_middleware/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_middleware/</guid> + <description>Name cowboy_middleware - Middlewares + Description The module cowboy_middleware defines a callback interface for Cowboy middlewares. + Middlewares process the request sequentially in the order they are configured. + Callbacks Middlewares implement the following interface: + execute(Req, Env) -&gt; {ok, Req, Env} | {suspend, module(), atom(), [any()]} | {stop, Req} Req :: cowboy_req:req() Env :: cowboy_middleware:env() The execute/2 is the only callback that needs to be implemented.</description> + </item> + + <item> + <title>cowboy_req(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req/</guid> + <description>Name cowboy_req - HTTP request and response + Description The module cowboy_req provides functions to access, manipulate and respond to requests. + There are four types of functions in this module. They can be differentiated by their name and their return type: + Type Name pattern Return type access + no verb, parse_*, match_* + Value + question</description> + </item> + + <item> + <title>cowboy_req:binding(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.binding/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.binding/</guid> + <description>Name cowboy_req:binding - Access a value bound from the route + Description binding(Name, Req) -&gt; binding(Name, Req, undefined) binding(Name, Req, Default) -&gt; any() | Default Name :: atom() Req :: cowboy_req:req() Default :: any() Return the value for the given binding. + Arguments Name Desired binding name as an atom. Req The Req object. Default Default value returned when the binding is missing.</description> + </item> + + <item> + <title>cowboy_req:bindings(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.bindings/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.bindings/</guid> + <description>Name cowboy_req:bindings - Access all values bound from the route + Description bindings(Req :: cowboy_req:req()) -&gt; cowboy_router:bindings() Return a map containing all bindings. + Arguments Req The Req object. Return value By default values are case sensitive binary strings, however constraints may change the type of this value (for example automatically converting numbers to integer). + Changelog 2.</description> + </item> + + <item> + <title>cowboy_req:body_length(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.body_length/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.body_length/</guid> + <description>Name cowboy_req:body_length - Body length + Description body_length(Req :: cowboy_req:req()) -&gt; undefined | non_neg_integer() Return the length of the request body. + The length is not always known before reading the body. In those cases Cowboy will return undefined. The body length is available after the body has been fully read. + Arguments Req The Req object. Return value The length of the request body, or undefined if it is not known.</description> + </item> + + <item> + <title>cowboy_req:delete_resp_header(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.delete_resp_header/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.delete_resp_header/</guid> + <description>Name cowboy_req:delete_resp_header - Delete a response header + Description delete_resp_header(Name, Req :: cowboy_req:req()) -&gt; Req Name :: binary() %% lowercase; case insensitive Delete the given response header. + The header name must be given as a lowercase binary string. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly. + Arguments Name Header name as a lowercase binary string.</description> + </item> + + <item> + <title>cowboy_req:has_body(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.has_body/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.has_body/</guid> + <description>Name cowboy_req:has_body - Is there a request body? + Description has_body(Req :: cowboy_req:req()) -&gt; boolean() Return whether the request has a body. + Arguments Req The Req object. Return value A boolean indicating whether the request has a body. + Changelog 1.0: Function introduced. Examples Ensure the request has a body true = cowboy_req:has_body(Req).</description> + </item> + + <item> + <title>cowboy_req:has_resp_body(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.has_resp_body/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.has_resp_body/</guid> + <description>Name cowboy_req:has_resp_body - Is there a response body? + Description has_resp_body(Req :: cowboy_req:req()) -&gt; boolean() Return whether a response body has been set. + Arguments Req The Req object. Return value A boolean indicating whether a response body has been set. + This function will return false when an empty response body has been set. + Changelog 1.</description> + </item> + + <item> + <title>cowboy_req:has_resp_header(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.has_resp_header/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.has_resp_header/</guid> + <description>Name cowboy_req:has_resp_header - Is the given response header set? + Description has_resp_header(Name, Req :: cowboy_req:req()) -&gt; boolean() Name :: binary() %% lowercase; case insensitive Return whether the given response header has been set. + The header name must be given as a lowercase binary string. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly. + Arguments Name Header name as a lowercase binary string.</description> + </item> + + <item> + <title>cowboy_req:header(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.header/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.header/</guid> + <description>Name cowboy_req:header - HTTP header + Description header(Name, Req) -&gt; header(Name, Req, undefined) header(Name, Req, Default) -&gt; binary() | Default Name :: binary() %% lowercase; case insensitive Req :: cowboy_req:req() Default :: any() Return the value for the given HTTP header. + The header name must be given as a lowercase binary string. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly.</description> + </item> + + <item> + <title>cowboy_req:headers(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.headers/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.headers/</guid> + <description>Name cowboy_req:headers - HTTP headers + Description headers(Req :: cowboy_req:req()) -&gt; cowboy:http_headers() Return all request headers. + Request headers can also be obtained using pattern matching: + #{headers := Headers} = Req. Arguments Req The Req object. Return value Headers are returned as a map with keys being lowercase binary strings, and values as binary strings. + Changelog 2.</description> + </item> + + <item> + <title>cowboy_req:host(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.host/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.host/</guid> + <description>Name cowboy_req:host - URI host name + Description host(Req :: cowboy_req:req()) -&gt; Host :: binary() Return the host name of the effective request URI. + The host name can also be obtained using pattern matching: + #{host := Host} = Req. Arguments Req The Req object. Return value The host name is returned as a lowercase binary string. It is case insensitive.</description> + </item> + + <item> + <title>cowboy_req:host_info(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.host_info/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.host_info/</guid> + <description>Name cowboy_req:host_info - Access the route&#8217;s heading host segments + Description host_info(Req :: cowboy_req:req()) -&gt; cowboy_router:tokens() Return the tokens for the heading host segments. + This is the part of the host name that was matched using the ... notation. + Arguments Req The Req object. Return value The tokens are returned as a list of case insensitive binary strings.</description> + </item> + + <item> + <title>cowboy_req:match_cookies(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.match_cookies/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.match_cookies/</guid> + <description>Name cowboy_req:match_cookies - Match cookies against constraints + Description match_cookies(Fields :: cowboy:fields(), Req :: cowboy_req:req()) -&gt; #{atom() =&gt; any()} Parse the cookies and match specific values against constraints. + Cowboy will only return the cookie values specified in the fields list, and ignore all others. Fields can be either the name of the cookie requested; the name along with a list of constraints; or the name, a list of constraints and a default value in case the cookie is missing.</description> + </item> + + <item> + <title>cowboy_req:match_qs(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.match_qs/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.match_qs/</guid> + <description>Name cowboy_req:match_qs - Match the query string against constraints + Description match_qs(Fields :: cowboy:fields(), Req :: cowboy_req:req()) -&gt; #{atom() =&gt; any()} Parse the query string and match specific values against constraints. + Cowboy will only return the query string values specified in the fields list, and ignore all others. Fields can be either the key requested; the key along with a list of constraints; or the key, a list of constraints and a default value in case the key is missing.</description> + </item> + + <item> + <title>cowboy_req:method(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.method/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.method/</guid> + <description>Name cowboy_req:method - HTTP method + Description method(Req :: cowboy_req:req()) -&gt; Method :: binary() Return the request&#8217;s HTTP method. + The method can also be obtained using pattern matching: + #{method := Method} = Req. Arguments Req The Req object. Return value The request&#8217;s HTTP method is returned as a binary string. While methods are case sensitive, standard methods are always uppercase.</description> + </item> + + <item> + <title>cowboy_req:parse_cookies(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.parse_cookies/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.parse_cookies/</guid> + <description>Name cowboy_req:parse_cookies - Parse cookie headers + Description parse_cookies(Req) -&gt; [{Name, Value}] Name :: binary() %% case sensitive Value :: binary() %% case sensitive Parse cookie headers. + Alias for cowboy_req:parse_header([cookie], Req). + When the cookie header is missing, [] is returned. + While an empty cookie header is not valid, some clients do send it. Cowboy will in this case also return []. + Arguments Req The Req object.</description> + </item> + + <item> + <title>cowboy_req:parse_header(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.parse_header/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.parse_header/</guid> + <description>Name cowboy_req:parse_header - Parse the given HTTP header + Description parse_header(Name, Req) -&gt; ParsedValue | Default parse_header(Name, Req, Default) -&gt; ParsedValue | Default Name :: binary() Req :: cowboy_req:req() ParsedValue :: any() Default :: any() Parse the given HTTP header. + The header name must be given as a lowercase binary string. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly.</description> + </item> + + <item> + <title>cowboy_req:parse_qs(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.parse_qs/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.parse_qs/</guid> + <description>Name cowboy_req:parse_qs - Parse the query string + Description parse_qs(Req :: cowboy_req:req()) -&gt; [{Key :: binary(), Value :: binary() | true}] Parse the query string as a list of key/value pairs. + Arguments Req The Req object. Return value The parsed query string is returned as a list of key/value pairs. The key is a binary string. The value is either a binary string, or the atom true.</description> + </item> + + <item> + <title>cowboy_req:path(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.path/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.path/</guid> + <description>Name cowboy_req:path - URI path + Description path(Req :: cowboy_req:req()) -&gt; Path :: binary() Return the path of the effective request URI. + The path can also be obtained using pattern matching: + #{path := Path} = Req. Arguments Req The Req object. Return value The path is returned as a binary string. It is case sensitive. + Changelog 2.</description> + </item> + + <item> + <title>cowboy_req:path_info(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.path_info/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.path_info/</guid> + <description>Name cowboy_req:path_info - Access the route&#8217;s trailing path segments + Description path_info(Req :: cowboy_req:req()) -&gt; cowboy_router:tokens() Return the tokens for the trailing path segments. + This is the part of the host name that was matched using the ... notation. + Arguments Req The Req object. Return value The tokens are returned as a list of case sensitive binary strings.</description> + </item> + + <item> + <title>cowboy_req:peer(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.peer/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.peer/</guid> + <description>Name cowboy_req:peer - Peer address and port + Description peer(Req :: cowboy_req:req()) -&gt; Peer Peer :: {inet:ip_address(), inet:port_number()} Return the peer&#8217;s IP address and port number. + The peer can also be obtained using pattern matching: + #{peer := {IP, Port}} = Req. Arguments Req The Req object. Return value The peer&#8217;s IP address and port number. + The peer is not necessarily the client&#8217;s IP address and port.</description> + </item> + + <item> + <title>cowboy_req:port(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.port/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.port/</guid> + <description>Name cowboy_req:port - URI port number + Description port(Req :: cowboy_req:req()) -&gt; Port :: inet:port_number() Return the port number of the effective request URI. + Note that the port number returned by this function is obtained by parsing the host header. It may be different from the port the peer used to connect to Cowboy. + The port number can also be obtained using pattern matching: + #{port := Port} = Req.</description> + </item> + + <item> + <title>cowboy_req:push(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.push/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.push/</guid> + <description>Name cowboy_req:push - Push a resource to the client + Description push(Path, Headers, Req :: cowboy_req:req()) -&gt; push(Path, Headers, Req, #{}) push(Path, Headers, Req :: cowboy_req:req(), Opts) -&gt; ok Path :: iodata() %% case sensitive Headers :: cowboy:http_headers() Opts :: cowboy_req:push_opts() Push a resource to the client. + Cowboy handles push requests the same way as if they came from the client, including the creation of a request handling process, routing and middlewares and so on.</description> + </item> + + <item> + <title>cowboy_req:qs(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.qs/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.qs/</guid> + <description>Name cowboy_req:qs - URI query string + Description qs(Req :: cowboy_req:req()) -&gt; Qs :: binary() Return the query string of the effective request URI. + The query string can also be obtained using pattern matching: + #{qs := Qs} = Req. Arguments Req The Req object. Return value The query string is returned as a binary string. It is case sensitive.</description> + </item> + + <item> + <title>cowboy_req:read_body(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.read_body/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.read_body/</guid> + <description>Name cowboy_req:read_body - Read the request body + Description read_body(Req :: cowboy_req:req()) -&gt; read_body(Req, #{}) read_body(Req :: cowboy_req:req(), Opts) -&gt; {ok, Data :: binary(), Req} | {more, Data :: binary(), Req} Opts :: cowboy_req:read_body_opts() Read the request body. + This function reads a chunk of the request body. A more tuple is returned when more data remains to be read. Call the function repeatedly until an ok tuple is returned to read the entire body.</description> + </item> + + <item> + <title>cowboy_req:read_part(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.read_part/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.read_part/</guid> + <description>Name cowboy_req:read_part - Read the next multipart headers + Description read_part(Req :: cowboy_req:req()) -&gt; read_part(Req, #{}) read_part(Req :: cowboy_req:req(), Opts) -&gt; {ok, Headers, Req} | {done, Req} Opts :: cowboy_req:read_body_opts() Headers :: #{binary() =&gt; binary()} Read the next part of a multipart body. + This function reads the request body and parses it as multipart. Each parts of a multipart representation have their own headers and body. This function parses and returns headers.</description> + </item> + + <item> + <title>cowboy_req:read_part_body(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.read_part_body/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.read_part_body/</guid> + <description>Name cowboy_req:read_part_body - Read the current part&#8217;s body + Description read_part_body(Req :: cowboy_req:req()) -&gt; read_part_body(Req, #{}) read_part_body(Req :: cowboy_req:req(), Opts) -&gt; {ok, Data :: binary(), Req} | {more, Data :: binary(), Req} Opts :: cowboy_req:read_body_opts() Read the body of the current part of the multipart message. + This function reads the request body and parses it as multipart. Each parts of a multipart representation have their own headers and body.</description> + </item> + + <item> + <title>cowboy_req:read_urlencoded_body(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.read_urlencoded_body/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.read_urlencoded_body/</guid> + <description>Name cowboy_req:read_urlencoded_body - Read and parse a urlencoded request body + Description read_urlencoded_body(Req :: cowboy_req:req()) -&gt; read_urlencoded_body(Req, #{}) read_urlencoded_body(Req :: cowboy_req:req(), Opts) -&gt; {ok, Body, Req} Opts :: cowboy_req:read_body_opts() Body :: [{Key :: binary(), Value :: binary() | true}] Read and parse a urlencoded request body. + This function reads the request body and parses it as application/x-www-form-urlencoded. It returns a list of key/values. + The urlencoded media type is used by Web browsers when submitting HTML forms using the POST method.</description> + </item> + + <item> + <title>cowboy_req:reply(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.reply/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.reply/</guid> + <description>Name cowboy_req:reply - Send the response + Description reply(Status, Req :: cowboy_req:req()) -&gt; reply(StatusCode, #{}, Req) reply(Status, Headers, Req :: cowboy_req:req()) -&gt; Req reply(Status, Headers, Body, Req :: cowboy_req:req()) -&gt; Req Status :: cowboy:http_status() Headers :: cowboy:http_headers() Body :: cowboy_req:resp_body() Send the response. + The header names must be given as lowercase binary strings. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly.</description> + </item> + + <item> + <title>cowboy_req:resp_header(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.resp_header/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.resp_header/</guid> + <description>Name cowboy_req:resp_header - Response header + Description resp_header(Name, Req) -&gt; resp_header(Name, Req, undefined) resp_header(Name, Req, Default) -&gt; binary() | Default Name :: binary() %% lowercase; case insensitive Req :: cowboy_req:req() Default :: any() Return the value for the given response header. + The response header must have been set previously using cowboy_req:set_resp_header(3) or cowboy_req:set_resp_headers(3). + The header name must be given as a lowercase binary string. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly.</description> + </item> + + <item> + <title>cowboy_req:resp_headers(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.resp_headers/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.resp_headers/</guid> + <description>Name cowboy_req:resp_headers - Response headers + Description resp_headers(Req :: cowboy_req:req()) -&gt; cowboy:http_headers() Return all response headers. + Arguments Req The Req object. Return value Headers are returned as a map with keys being lowercase binary strings, and values as binary strings. + Changelog 2.0: Function introduced. Examples Get all response headers Headers = cowboy_req:resp_headers(Req).</description> + </item> + + <item> + <title>cowboy_req:scheme(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.scheme/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.scheme/</guid> + <description>Name cowboy_req:scheme - URI scheme + Description scheme(Req :: cowboy_req:req()) -&gt; Scheme :: binary() Return the scheme of the effective request URI. + The scheme can also be obtained using pattern matching: + #{scheme := Scheme} = Req. Arguments Req The Req object. Return value The scheme is returned as a binary. It is case insensitive. + Cowboy will only set the scheme to &lt;&lt;"</description> + </item> + + <item> + <title>cowboy_req:set_resp_body(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_body/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_body/</guid> + <description>Name cowboy_req:set_resp_body - Set the response body + Description set_resp_body(Body, Req :: cowboy_req:req()) -&gt; Req Body :: cowboy_req:resp_body() Set the response body. + The response body will be sent when a reply is initiated. Note that the functions stream_reply/2,3 and reply/4 will override the body set by this function. + This function can also be used to remove a response body that was set previously. To do so, simply call this function with an empty body.</description> + </item> + + <item> + <title>cowboy_req:set_resp_cookie(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_cookie/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_cookie/</guid> + <description>Name cowboy_req:set_resp_cookie - Set a cookie + Description set_resp_cookie(Name, Value, Req :: cowboy_req:req()) -&gt; set_resp_cookie(Name, Value, [], Req) set_resp_cookie(Name, Value, Req :: cowboy_req:req(), Opts) -&gt; Req Name :: binary() %% case sensitive Value :: iodata() %% case sensitive Opts :: cow_cookie:cookie_opts() Set a cookie to be sent with the response. + Note that cookie names are case sensitive. + Arguments Name Cookie name.</description> + </item> + + <item> + <title>cowboy_req:set_resp_header(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_header/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_header/</guid> + <description>Name cowboy_req:set_resp_header - Set a response header + Description set_resp_header(Name, Value, Req :: cowboy_req:req()) -&gt; Req Name :: binary() %% lowercase; case insensitive Value :: iodata() %% case depends on header Set a header to be sent with the response. + The header name must be given as a lowercase binary string. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly.</description> + </item> + + <item> + <title>cowboy_req:set_resp_headers(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_headers/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_headers/</guid> + <description>Name cowboy_req:set_resp_headers - Set several response headers + Description set_resp_headers(Headers, Req :: cowboy_req:req()) -&gt; Req Headers :: cowboy:http_headers() Set several headers to be sent with the response. + The header name must be given as a lowercase binary string. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly. + Cowboy does not allow duplicate header names. Headers set by this function may be overwritten by those set from the reply functions.</description> + </item> + + <item> + <title>cowboy_req:stream_body(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.stream_body/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.stream_body/</guid> + <description>Name cowboy_req:stream_body - Stream the response body + Description stream_body(Data, IsFin, Req :: cowboy_req:req()) -&gt; ok Data :: iodata() IsFin :: fin | nofin Stream the response body. + This function may be called as many times as needed after initiating a response using the cowboy_req:stream_reply(3) function. + The second argument indicates if this call is the final call. Use the nofin value until you know no more data will be sent.</description> + </item> + + <item> + <title>cowboy_req:stream_reply(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.stream_reply/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.stream_reply/</guid> + <description>Name cowboy_req:stream_reply - Send the response headers + Description stream_reply(Status, Req :: cowboy_req:req()) -&gt; stream_reply(StatusCode, #{}, Req) stream_reply(Status, Headers, Req :: cowboy_req:req()) -&gt; Req Status :: cowboy:http_status() Headers :: cowboy:http_headers() Send the response headers. + The header names must be given as lowercase binary strings. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly. + Cowboy does not allow duplicate header names.</description> + </item> + + <item> + <title>cowboy_req:uri(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.uri/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.uri/</guid> + <description>Name cowboy_req:uri - Reconstructed URI + Description uri(Req :: cowboy_req:req()) -&gt; uri(Req, #{}) uri(Req :: cowboy_req:req(), Opts) -&gt; URI :: iodata() Opts :: #{ scheme =&gt; iodata() | undefined, host =&gt; iodata() | undefined, port =&gt; inet:port_number() | undefined, path =&gt; iodata() | undefined, qs =&gt; iodata() | undefined, fragment =&gt; iodata() | undefined } Reconstruct the effective request URI, optionally modifying components. + By default Cowboy will build a URI using the components found in the request.</description> + </item> + + <item> + <title>cowboy_req:version(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.version/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.version/</guid> + <description>Name cowboy_req:version - HTTP version + Description version(Req :: cowboy_req:req()) -&gt; Version :: cowboy:http_version() Return the HTTP version used for the request. + The version can also be obtained using pattern matching: + #{version := Version} = Req. Arguments Req The Req object. Return value The HTTP version used for the request is returned as an atom. It is provided for informative purposes only.</description> + </item> + + <item> + <title>cowboy_rest(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_rest/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_rest/</guid> + <description>Name cowboy_rest - REST handlers + Description The module cowboy_rest implements the HTTP state machine. + Implementing REST handlers is not enough to provide a REST interface; this interface must also follow the REST constraints including HATEOAS (hypermedia as the engine of application state). + Callbacks REST handlers implement the following interface: + init(Req, State) -&gt; {cowboy_rest, Req, State} Callback(Req, State) -&gt; {Result, Req, State} | {stop, Req, State} terminate(Reason, Req, State) -&gt; ok %% optional Req :: cowboy_req:req() State :: any() Reason :: normal | {crash, error | exit | throw, any()} Callback - see below Result - see below Default - see below The init/2 callback is common to all handlers.</description> + </item> + + <item> + <title>cowboy_router(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_router/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_router/</guid> + <description>Name cowboy_router - Router middleware + Description The cowboy_router middleware maps the requested host and path to the handler to be used for processing the request. + The router takes the dispatch rules as input from the middleware environment. Dispatch rules are generated by calling the cowboy_router:compile(3) function. + When a route matches, the router sets the handler and handler_opts middleware environment values containing the handler module and initial state, respectively.</description> + </item> + + <item> + <title>cowboy_router:compile(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_router.compile/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_router.compile/</guid> + <description>Name cowboy_router:compile - Compile routes to the resources + Description compile(cowboy_router:routes()) -&gt; cowboy_router:dispatch_rules() Compile routes to the resources. + Takes a human readable list of routes and transforms it into a form more efficient to process. + Arguments Routes Human readable list of routes. Return value An opaque dispatch rules value is returned. This value must be given to Cowboy as a middleware environment value.</description> + </item> + + <item> + <title>cowboy_static(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_static/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_static/</guid> + <description>Name cowboy_static - Static file handler + Description The module cowboy_static implements file serving capabilities using the REST semantics provided by cowboy_rest. + The static file handler is a pre-written handler coming with Cowboy. To serve files, use it in your routes. + Options opts() :: {priv_file, App, Path} | {priv_file, App, Path, Extra} | {file, Path} | {file, Path, Extra} | {priv_dir, App, Path} | {priv_dir, App, Path, Extra} | {dir, Path} | {dir, Path, Extra} App :: atom() Path :: binary() | string() Extra :: [Etag | Mimetypes] Etag :: {etag, module(), function()} | {etag, false} Mimetypes :: {mimetypes, module(), function()} | {mimetypes, binary() | ParsedMime} ParsedMime :: {Type :: binary(), SubType :: binary(), Params} Params :: [{Key :: binary(), Value :: binary()}] Static handler configuration.</description> + </item> + + <item> + <title>cowboy_stream(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_stream/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_stream/</guid> + <description>Name cowboy_handler - Stream handlers + Description The module cowboy_stream defines a callback interface and a protocol for handling HTTP streams. + An HTTP request and its associated response is called a stream. A connection may have many streams. In HTTP/1.1 they are executed sequentially, while in HTTP/2 they are executed concurrently. + Cowboy calls the stream handler for nearly all events related to a stream. Exceptions vary depending on the protocol.</description> + </item> + + <item> + <title>cowboy_websocket(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_websocket/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_websocket/</guid> + <description>Name cowboy_websocket - Websocket + Description The module cowboy_websocket implements Websocket as a Ranch protocol. It also defines a callback interface for handling Websocket connections. + Callbacks Websocket handlers must implement the following callback interface: + init(Req, State) -&gt; {cowboy_websocket, Req, State} | {cowboy_websocket, Req, State, Opts} websocket_init(State) -&gt; CallResult %% optional websocket_handle(InFrame, State) -&gt; CallResult websocket_info(Info, State) -&gt; CallResult terminate(Reason, PartialReq, State) -&gt; ok %% optional Req :: cowboy_req:req() PartialReq :: map() State :: any() Opts :: cowboy_websocket:opts() InFrame :: {text | binary | ping | pong, binary()} OutFrame :: cow_ws:frame() %% see types below Info :: any() CallResult :: {ok, State} | {ok, State, hibernate} | {reply, OutFrame | [OutFrame], State} | {reply, OutFrame | [OutFrame], State, hibernate} | {stop, State} Reason :: normal | stop | timeout | remote | {remote, cow_ws:close_code(), binary()} | {error, badencoding | badframe | closed | atom()} | {crash, error | exit | throw, any()} The init/2 callback is common to all handlers.</description> + </item> + + <item> + <title>gun(3)</title> + <link>https://ninenines.eu/docs/en/gun/1.0/manual/gun/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/gun/1.0/manual/gun/</guid> + <description>Name gun - asynchronous HTTP client + Description The gun module provides an asynchronous interface for connecting and communicating with Web servers over HTTP, HTTP/2 or Websocket. + Types opts() = map() Configuration for the connection. + The following keys are defined: + connect_timeout &#8658; timeout() Connection timeout. Defaults to infinity. http_opts &#8658; http_opts() Options specific to the HTTP protocol.</description> + </item> + + <item> + <title>gun(7)</title> + <link>https://ninenines.eu/docs/en/gun/1.0/manual/gun_app/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/gun/1.0/manual/gun_app/</guid> + <description>Name gun - Erlang HTTP client with support for HTTP/1.1, HTTP/2 and Websocket. + Dependencies The gun application uses the Erlang applications ranch for abstracting TCP and TLS over a common interface, and the ssl application for TLS support, required for HTTPS and secure HTTP/2 support. In addition, Gun requires the crypto application (a dependency of ssl) for Websocket. + These dependencies must be started for the gun application to work.</description> + </item> + + <item> + <title>ranch(3)</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch/</guid> + <description>Name ranch - socket acceptor pool + Description The ranch module provides functions for starting and manipulating Ranch listeners. + Types max_conns() = non_neg_integer() | infinity Maximum number of connections allowed on this listener. + This is a soft limit. The actual number of connections might be slightly above the limit due to concurrency when accepting new connections. Some connections may also be removed from this count explicitly by the user code.</description> + </item> + + <item> + <title>ranch(3)</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch/</guid> + <description>Name ranch - socket acceptor pool + Description The ranch module provides functions for starting and manipulating Ranch listeners. + Types max_conns() = non_neg_integer() | infinity Maximum number of connections allowed on this listener. + This is a soft limit. The actual number of connections might be slightly above the limit due to concurrency when accepting new connections. Some connections may also be removed from this count explicitly by the user code.</description> + </item> + + <item> + <title>ranch(7)</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_app/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_app/</guid> + <description>Name ranch - Socket acceptor pool for TCP protocols. + Dependencies The ranch application has no particular dependency required to start. + It has optional dependencies that are only required when listening for SSL connections. The dependencies are crypto, asn1, public_key and ssl. They are started automatically if they weren&#8217;t before. + Environment The ranch application defines one application environment configuration parameter. + profile (false) When enabled, Ranch will start eprof profiling automatically.</description> + </item> + + <item> + <title>ranch(7)</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_app/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_app/</guid> + <description>Name ranch - Socket acceptor pool for TCP protocols. + Dependencies The ranch application depends on the ssl application to start. It is used for handling secure connections, when the transport is ranch_ssl. It can be disabled if SSL is not used. + Environment The ranch application defines one application environment configuration parameter. + profile (false) When enabled, Ranch will start eprof profiling automatically.</description> + </item> + + <item> + <title>ranch_protocol(3)</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_protocol/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_protocol/</guid> + <description>Name ranch_protocol - behaviour for protocol modules + Description The ranch_protocol behaviour defines the interface used by Ranch protocols. + Types None. + Callbacks start_link(Ref, Socket, Transport, ProtoOpts) &#8594; {ok, pid()} | {ok, pid(), pid()} Ref = ranch:ref() Listener name. Socket = any() Socket for this connection. Transport = module() Transport module for this socket.</description> + </item> + + <item> + <title>ranch_protocol(3)</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_protocol/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_protocol/</guid> + <description>Name ranch_protocol - behaviour for protocol modules + Description The ranch_protocol behaviour defines the interface used by Ranch protocols. + Types None. + Callbacks start_link(Ref, Socket, Transport, ProtoOpts) &#8594; {ok, pid()} | {ok, pid(), pid()} Ref = ranch:ref() Listener name. Socket = any() Socket for this connection. Transport = module() Transport module for this socket.</description> + </item> + + <item> + <title>ranch_ssl(3)</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_ssl/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_ssl/</guid> + <description>Name ranch_ssl - SSL transport module + Description The ranch_ssl module implements an SSL Ranch transport. + Types ssl_opt() ssl_opt() = {alpn_preferred_protocols, [binary()]} | {cacertfile, string()} | {cacerts, [public_key:der_encoded()]} | {cert, public_key:der_encoded()} | {certfile, string()} | {ciphers, [ssl:erl_cipher_suite()] | string()} | {client_renegotiation, boolean()} | {crl_cache, {module(), {internal | any(), list()}}} | {crl_check, boolean() | peer | best_effort} | {depth, 0..255} | {dh, public_key:der_encoded()} | {dhfile, string()} | {fail_if_no_peer_cert, boolean()} | {hibernate_after, integer() | undefined} | {honor_cipher_order, boolean()} | {key, {'RSAPrivateKey' | 'DSAPrivateKey' | 'PrivateKeyInfo', public_key:der_encoded()}} | {keyfile, string()} | {log_alert, boolean()} | {next_protocols_advertised, [binary()]} | {partial_chain, fun(([public_key:der_encoded()]) -&gt; {trusted_ca, public_key:der_encoded()} | unknown_ca)} | {password, string()} | {psk_identity, string()} | {reuse_session, fun()} | {reuse_sessions, boolean()} | {secure_renegotiate, boolean()} | {sni_fun, fun()} | {sni_hosts, [{string(), ssl_opt()}]} | {user_lookup_fun, {fun(), any()}} | {verify, ssl:verify_type()} | {verify_fun, {fun(), any()}} | {versions, [atom()]}.</description> + </item> + + <item> + <title>ranch_ssl(3)</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_ssl/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_ssl/</guid> + <description>Name ranch_ssl - SSL transport module + Description The ranch_ssl module implements an SSL Ranch transport. + Types ssl_opt() ssl_opt() = {alpn_preferred_protocols, [binary()]} | {beast_mitigation, one_n_minus_one | zero_n | disabled} | {cacertfile, string()} | {cacerts, [public_key:der_encoded()]} | {cert, public_key:der_encoded()} | {certfile, string()} | {ciphers, [ssl:erl_cipher_suite()] | string()} | {client_renegotiation, boolean()} | {crl_cache, {module(), {internal | any(), list()}}} | {crl_check, boolean() | peer | best_effort} | {depth, 0.</description> + </item> + + <item> + <title>ranch_tcp(3)</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_tcp/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_tcp/</guid> + <description>Name ranch_tcp - TCP transport module + Description The ranch_tcp module implements a TCP Ranch transport. + Note that due to bugs in OTP up to at least R16B02, it is recommended to disable async threads when using the sendfile function of this transport, as it can make the threads stuck indefinitely. + Types opt() opt() = {backlog, non_neg_integer()} | {buffer, non_neg_integer()} | {delay_send, boolean()} | {dontroute, boolean()} | {exit_on_close, boolean()} | {fd, non_neg_integer()} | {high_msgq_watermark, non_neg_integer()} | {high_watermark, non_neg_integer()} | inet | inet6 | {ip, inet:ip_address()} | {keepalive, boolean()} | {linger, {boolean(), non_neg_integer()}} | {low_msgq_watermark, non_neg_integer()} | {low_watermark, non_neg_integer()} | {nodelay, boolean()} | {port, inet:port_number()} | {priority, integer()} | {raw, non_neg_integer(), non_neg_integer(), binary()} | {recbuf, non_neg_integer()} | {send_timeout, timeout()} | {send_timeout_close, boolean()} | {sndbuf, non_neg_integer()} | {tos, integer()} Listen options.</description> + </item> + + <item> + <title>ranch_tcp(3)</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_tcp/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_tcp/</guid> + <description>Name ranch_tcp - TCP transport module + Description The ranch_tcp module implements a TCP Ranch transport. + Note that due to bugs in OTP up to at least R16B02, it is recommended to disable async threads when using the sendfile function of this transport, as it can make the threads stuck indefinitely. + Types opt() opt() = {backlog, non_neg_integer()} | {buffer, non_neg_integer()} | {delay_send, boolean()} | {dontroute, boolean()} | {exit_on_close, boolean()} | {fd, non_neg_integer()} | {high_msgq_watermark, non_neg_integer()} | {high_watermark, non_neg_integer()} | inet | inet6 | {ip, inet:ip_address()} | {ipv6_v6only, boolean()} | {keepalive, boolean()} | {linger, {boolean(), non_neg_integer()}} | {low_msgq_watermark, non_neg_integer()} | {low_watermark, non_neg_integer()} | {nodelay, boolean()} | {port, inet:port_number()} | {priority, integer()} | {raw, non_neg_integer(), non_neg_integer(), binary()} | {recbuf, non_neg_integer()} | {send_timeout, timeout()} | {send_timeout_close, boolean()} | {sndbuf, non_neg_integer()} | {tos, integer()} Listen options.</description> + </item> + + <item> + <title>ranch_transport(3)</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_transport/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_transport/</guid> + <description>Name ranch_transport - behaviour for transport modules + Description The ranch_transport behaviour defines the interface used by Ranch transports. + Types sendfile_opts() = [{chunk_size, non_neg_integer()}] Options used by the sendfile function and callbacks. + Allows configuring the chunk size, in bytes. Defaults to 8191 bytes. + Callbacks accept(LSocket, Timeout) &#8594; {ok, CSocket} | {error, closed | timeout | atom()} LSocket = CSocket = any() Listening socket.</description> + </item> + + <item> + <title>ranch_transport(3)</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_transport/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_transport/</guid> + <description>Name ranch_transport - behaviour for transport modules + Description The ranch_transport behaviour defines the interface used by Ranch transports. + Types sendfile_opts() = [{chunk_size, non_neg_integer()}] Options used by the sendfile function and callbacks. + Allows configuring the chunk size, in bytes. Defaults to 8191 bytes. + Callbacks accept(LSocket, Timeout) &#8594; {ok, CSocket} | {error, closed | timeout | atom()} LSocket = CSocket = any() Listening socket.</description> </item> </channel> diff --git a/donate/index.html b/donate/index.html index 4a427be0..28aaacce 100644 --- a/donate/index.html +++ b/donate/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Donate</title> @@ -67,22 +67,22 @@ <h1 class="lined-header"><span>Services</span></h1> -<div class="sect2">
-<h3 id="_like_my_work_donate">Like my work? Donate!</h3>
-<div class="paragraph"><p>Donate to Loïc Hoguin because his work on Cowboy
-and Erlang.mk is fantastic:</p></div>
-<form action="https://www.paypal.com/cgi-bin/webscr" method="post" style="display:inline">
-<input type="hidden" name="cmd" value="_donations">
-<input type="hidden" name="business" value="[email protected]">
-<input type="hidden" name="lc" value="FR">
-<input type="hidden" name="item_name" value="Loic Hoguin">
-<input type="hidden" name="item_number" value="99s">
-<input type="hidden" name="currency_code" value="EUR">
-<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHosted">
-<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
-<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1">
-</form>
-</div>
+<div class="sect2"> +<h3 id="_like_my_work_donate">Like my work? Donate!</h3> +<div class="paragraph"><p>Donate to Loïc Hoguin because his work on Cowboy +and Erlang.mk is fantastic:</p></div> +<form action="https://www.paypal.com/cgi-bin/webscr" method="post" style="display:inline"> +<input type="hidden" name="cmd" value="_donations"> +<input type="hidden" name="business" value="[email protected]"> +<input type="hidden" name="lc" value="FR"> +<input type="hidden" name="item_name" value="Loic Hoguin"> +<input type="hidden" name="item_number" value="99s"> +<input type="hidden" name="currency_code" value="EUR"> +<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHosted"> +<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!"> +<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1"> +</form> +</div> </div> @@ -111,22 +111,6 @@ and Erlang.mk is fantastic:</p></div> - <div class="sect2">
-<h3 id="_like_my_work_donate">Like my work? Donate!</h3>
-<div class="paragraph"><p>Donate to Loïc Hoguin because his work on Cowboy
-and Erlang.mk is fantastic:</p></div>
-<form action="https://www.paypal.com/cgi-bin/webscr" method="post" style="display:inline">
-<input type="hidden" name="cmd" value="_donations">
-<input type="hidden" name="business" value="[email protected]">
-<input type="hidden" name="lc" value="FR">
-<input type="hidden" name="item_name" value="Loic Hoguin">
-<input type="hidden" name="item_number" value="99s">
-<input type="hidden" name="currency_code" value="EUR">
-<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHosted">
-<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
-<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1">
-</form>
-</div>
@@ -277,6 +261,40 @@ and Erlang.mk is fantastic:</p></div> + <div class="sect2"> +<h3 id="_like_my_work_donate">Like my work? Donate!</h3> +<div class="paragraph"><p>Donate to Loïc Hoguin because his work on Cowboy +and Erlang.mk is fantastic:</p></div> +<form action="https://www.paypal.com/cgi-bin/webscr" method="post" style="display:inline"> +<input type="hidden" name="cmd" value="_donations"> +<input type="hidden" name="business" value="[email protected]"> +<input type="hidden" name="lc" value="FR"> +<input type="hidden" name="item_name" value="Loic Hoguin"> +<input type="hidden" name="item_number" value="99s"> +<input type="hidden" name="currency_code" value="EUR"> +<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHosted"> +<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!"> +<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1"> +</form> +</div> + + + + + + + + + + + + + + + + + + @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines</title> @@ -270,10 +270,15 @@ - <div class="paragraph"><p>Feeling generous? Love reading?<br />
-<a href="https://salt.bountysource.com/teams/ninenines">Crowdfund my salary</a>
-or buy <a href="/articles/erlanger-playbook">The Erlanger Playbook</a></p></div>
- + + + + + + + + + @@ -415,6 +420,19 @@ or buy <a href="/articles/erlanger-playbook">The Erlanger Playbook</a></p></div> + <div class="paragraph"><p>Feeling generous? Love reading?<br /> +<a href="https://salt.bountysource.com/teams/ninenines">Crowdfund my salary</a> +or buy <a href="/articles/erlanger-playbook">The Erlanger Playbook</a></p></div> + + + + + + + + + + @@ -2,12 +2,841 @@ <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"> <channel> <title>Nine Nines</title> - <link>https://ninenines.eu/index.xml</link> + <link>https://ninenines.eu/</link> <description>Recent content on Nine Nines</description> <generator>Hugo -- gohugo.io</generator> <language>en-us</language> <lastBuildDate>Wed, 23 Aug 2017 18:00:00 +0100</lastBuildDate> - <atom:link href="https://ninenines.eu/index.xml" rel="self" type="application/rss+xml" /> + + <atom:link href="https://ninenines.eu/index.xml" rel="self" type="application/rss+xml" /> + + + <item> + <title>Installation</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/installation/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/installation/</guid> + <description>On Unix Erlang.mk requires GNU Make to be installed. While it will currently work with GNU Make 3.81, support for this version is deprecated and will be removed in 2017. We recommend GNU Make 4.1 or later. + Git and Erlang/OTP must also be installed. + Some functionality requires that Autoconf 2.59 or later be installed, in order to compile Erlang/OTP. Erlang/OTP may have further requirements depending on your needs.</description> + </item> + + <item> + <title>Introduction</title> + <link>https://ninenines.eu/docs/en/gun/1.0/guide/introduction/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/gun/1.0/guide/introduction/</guid> + <description>Gun is an Erlang HTTP client with support for HTTP/1.1, HTTP/2 and Websocket. + Prerequisites Knowledge of Erlang, but also of the HTTP/1.1, HTTP/2 and Websocket protocols is required in order to read this guide. + Supported platforms Gun is tested and supported on Linux. + Gun is developed for Erlang 18+. + Gun may be compiled on earlier Erlang versions with small source code modifications but there is no guarantee that it will work as intended.</description> + </item> + + <item> + <title>Introduction</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/guide/introduction/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/guide/introduction/</guid> + <description>Ranch is a socket acceptor pool for TCP protocols. + Ranch aims to provide everything you need to accept TCP connections with a small code base and low latency while being easy to use directly as an application or to embed into your own. + Prerequisites It is assumed the developer already knows Erlang and has some experience with socket programming and TCP protocols. + Supported platforms Ranch is tested and supported on Linux.</description> + </item> + + <item> + <title>Introduction</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/guide/introduction/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/guide/introduction/</guid> + <description>Ranch is a socket acceptor pool for TCP protocols. + Ranch aims to provide everything you need to accept TCP connections with a small code base and low latency while being easy to use directly as an application or to embed into your own. + Prerequisites It is assumed the developer already knows Erlang and has some experience with socket programming and TCP protocols. + Supported platforms Ranch is tested and supported on Linux, FreeBSD, OSX and Windows.</description> + </item> + + <item> + <title>The modern Web</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/modern_web/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/modern_web/</guid> + <description>Cowboy is a server for the modern Web. This chapter explains what it means and details all the standards involved. + Cowboy supports all the standards listed in this document. + HTTP/2 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.</description> + </item> + + <item> + <title>Erlang and the Web</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/erlang_web/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/erlang_web/</guid> + <description>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 involved. A few connections are opened and requests are sent through these connections. Then the web page is displayed on your screen. Your browser will only open up to 4 or 8 connections to the server, depending on your settings.</description> + </item> + + <item> + <title>Getting started</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/getting_started/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/getting_started/</guid> + <description>This chapter explains how to get started using Erlang.mk. + Creating a folder for your project The first step is always to create a new folder that will contain your project. + $ mkdir hello_joe $ cd hello_joe Most people tend to put all their projects side by side in a common folder. We recommend keeping an organization similar to your remote repositories. For example, for GitHub users, put all your projects in a common folder with the same name as your username.</description> + </item> + + <item> + <title>Listeners</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/guide/listeners/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/guide/listeners/</guid> + <description>A listener is a set of processes whose role is to listen on a port for new connections. It manages a pool of acceptor processes, each of them indefinitely accepting connections. When it does, it starts a new process executing the protocol handler code. All the socket programming is abstracted through the user of transport handlers. + The listener takes care of supervising all the acceptor and connection processes, allowing developers to focus on building their application.</description> + </item> + + <item> + <title>Listeners</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/guide/listeners/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/guide/listeners/</guid> + <description>A listener is a set of processes whose role is to listen on a port for new connections. It manages a pool of acceptor processes, each of them indefinitely accepting connections. When it does, it starts a new process executing the protocol handler code. All the socket programming is abstracted through the use of transport handlers. + The listener takes care of supervising all the acceptor and connection processes, allowing developers to focus on building their application.</description> + </item> + + <item> + <title>Starting and stopping</title> + <link>https://ninenines.eu/docs/en/gun/1.0/guide/start/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/gun/1.0/guide/start/</guid> + <description>This chapter describes how to start and stop the Gun application. + Setting up Before Gun can be used it needs to be in Erlang&#8217;s ERL_LIBS path variable. If you use erlang.mk or a similar build tool, you only need to specify Gun as a dependency to your application and the tool will take care of downloading Gun and setting up paths. + With erlang.mk this is done by adding gun to the DEPS variable in your Makefile.</description> + </item> + + <item> + <title>Supported protocols</title> + <link>https://ninenines.eu/docs/en/gun/1.0/guide/protocols/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/gun/1.0/guide/protocols/</guid> + <description>This chapter describes the protocols supported and the operations available to them. + HTTP/1.1 HTTP/1.1 is a text request-response protocol. The client sends a request, the server sends back a response. + Gun provides convenience functions for performing GET, HEAD, OPTIONS, POST, PATCH, PUT, and DELETE requests. All these functions are aliases of gun:request/{4,5,6} for each respective methods. Gun also provides a gun:data/4 function for streaming the request body. + Gun will send a gun_response message for every response received, followed by zero or more gun_data messages for the response body.</description> + </item> + + <item> + <title>Introduction</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/introduction/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/introduction/</guid> + <description>Cowboy is a small, fast and modern HTTP server for Erlang/OTP. + Cowboy aims to provide a complete 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 in another application.</description> + </item> + + <item> + <title>Transports</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/guide/transports/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/guide/transports/</guid> + <description>A transport defines the interface to interact with a socket. + Transports can be used for connecting, listening and accepting connections, but also for receiving and sending data. Both passive and active mode are supported, although all sockets are initialized as passive. + TCP transport The TCP transport is a thin wrapper around gen_tcp. + SSL transport The SSL transport is a thin wrapper around ssl. It requires the crypto, asn1, public_key and ssl applications to be started.</description> + </item> + + <item> + <title>Transports</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/guide/transports/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/guide/transports/</guid> + <description>A transport defines the interface to interact with a socket. + Transports can be used for connecting, listening and accepting connections, but also for receiving and sending data. Both passive and active mode are supported, although all sockets are initialized as passive. + TCP transport The TCP transport is a thin wrapper around gen_tcp. + SSL transport The SSL transport is a thin wrapper around ssl. + Ranch depends on ssl by default so any necessary dependencies will start when Ranch is started.</description> + </item> + + <item> + <title>Overview</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/overview/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/overview/</guid> + <description>Now that you know how to get started, let&#8217;s take a look at what Erlang.mk can do for you. + Building your project Erlang.mk is first and foremost a build tool. It is especially tailored for Erlang developers and follows widely accepted practices in the Erlang community. + Erlang.mk will happily build all Erlang-specific files you throw at it. Other kinds of files too, like C or C++ code when you are working on a NIF or a port driver.</description> + </item> + + <item> + <title>Connection</title> + <link>https://ninenines.eu/docs/en/gun/1.0/guide/connect/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/gun/1.0/guide/connect/</guid> + <description>This chapter describes how to open, monitor and close a connection using the Gun client. + Gun connections Gun is designed with the HTTP/2 and Websocket protocols in mind. They are built for long-running connections that allow concurrent exchange of data, either in the form of request/responses for HTTP/2 or in the form of messages for Websocket. + A Gun connection is an Erlang process that manages a socket to a remote endpoint.</description> + </item> + + <item> + <title>Protocols</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/guide/protocols/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/guide/protocols/</guid> + <description>A protocol handler starts a connection process and defines the protocol logic executed in this process. + Writing a protocol handler All protocol handlers must implement the ranch_protocol behavior which defines a single callback, start_link/4. This callback is responsible for spawning a new process for handling the connection. It receives four arguments: the name of the listener, the socket, the transport handler being used and the protocol options defined in the call to ranch:start_listener/6.</description> + </item> + + <item> + <title>Protocols</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/guide/protocols/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/guide/protocols/</guid> + <description>A protocol handler starts a connection process and defines the protocol logic executed in this process. + Writing a protocol handler All protocol handlers must implement the ranch_protocol behavior which defines a single callback, start_link/4. This callback is responsible for spawning a new process for handling the connection. It receives four arguments: the name of the listener, the socket, the transport handler being used and the protocol options defined in the call to ranch:start_listener/5.</description> + </item> + + <item> + <title>Getting started</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/getting_started/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/getting_started/</guid> + <description>Erlang is more than a language, it is also an operating system for your applications. Erlang developers rarely write standalone modules, they write libraries or applications, and then bundle those into what is called a release. A release contains the Erlang VM plus all applications required to run the node, so it can be pushed to production directly. + This chapter walks you through all the steps of setting up Cowboy, writing your first application and generating your first release.</description> + </item> + + <item> + <title>Updating Erlang.mk</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/updating/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/updating/</guid> + <description>This chapter describes how to update the erlang.mk file in your repository. + Initial bootstrap The first time you use Erlang.mk, it will bootstrap itself. It always uses the most recent version for this, so you don&#8217;t have to update after creating your project. + Updating Later on though, updating becomes a necessity. Erlang.mk developers and contributors relentlessly improve the project and add new features; it would be a waste not to benefit from this.</description> + </item> + + <item> + <title>HTTP</title> + <link>https://ninenines.eu/docs/en/gun/1.0/guide/http/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/gun/1.0/guide/http/</guid> + <description>This chapter describes how to use the Gun client for communicating with an HTTP/1.1 or HTTP/2 server. + Streams Every time a request is initiated, Gun creates a stream. A stream reference uniquely identifies a set of request and response(s) and must be used to perform additional operations with a stream or to identify its messages. + Stream references use the Erlang reference data type and are therefore unique. + Streams can be canceled at any time.</description> + </item> + + <item> + <title>Embedded mode</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/guide/embedded/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/guide/embedded/</guid> + <description>Embedded mode allows you to insert Ranch listeners directly in your supervision tree. This allows for greater fault tolerance control by permitting the shutdown of a listener due to the failure of another part of the application and vice versa. + Embedding To embed Ranch in your application you can simply add the child specs to your supervision tree. This can all be done in the init/1 function of one of your application supervisors.</description> + </item> + + <item> + <title>Embedded mode</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/guide/embedded/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/guide/embedded/</guid> + <description>Embedded mode allows you to insert Ranch listeners directly in your supervision tree. This allows for greater fault tolerance control by permitting the shutdown of a listener due to the failure of another part of the application and vice versa. + Embedding To embed Ranch in your application you can simply add the child specs to your supervision tree. This can all be done in the init/1 function of one of your application supervisors.</description> + </item> + + <item> + <title>Limitations</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/limitations/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/limitations/</guid> + <description>No software is perfect. + It&#8217;s very important, when evaluating and when using a tool, to understand its limitations, so as to avoid making mistakes and wasting valuable time. + This chapter lists all known limitations of Erlang.mk. + Erlang must be available Currently Erlang.mk requires you to install Erlang beforehand. Installing Erlang is not always easy, particularly if you need a specific version of Erlang for a specific project.</description> + </item> + + <item> + <title>Flow diagram</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/flow_diagram/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/flow_diagram/</guid> + <description>Cowboy is a lightweight HTTP server with support for HTTP/1.1, HTTP/2 and Websocket. + It is built on top of Ranch. Please see the Ranch guide for more information about how the network connections are handled. + Overview As you can see on the diagram, the client begins by connecting to the server. This step is handled by a Ranch acceptor, which is a process dedicated to accepting new connections.</description> + </item> + + <item> + <title>Websocket</title> + <link>https://ninenines.eu/docs/en/gun/1.0/guide/websocket/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/gun/1.0/guide/websocket/</guid> + <description>This chapter describes how to use the Gun client for communicating with a Websocket server. + @todo recovering from connection failure reconnecting to Websocket etc. + HTTP upgrade Websocket is a protocol built on top of HTTP. To use Websocket, you must first request for the connection to be upgraded. Only HTTP/1.1 connections can be upgraded to Websocket, so you might need to restrict the protocol to HTTP/1.1 if you are planning to use Websocket over TLS.</description> + </item> + + <item> + <title>Writing parsers</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/guide/parsers/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/guide/parsers/</guid> + <description>There are three kinds of protocols: + Text protocols Schema-less binary protocols Schema-based binary protocols This chapter introduces the first two kinds. It will not cover more advanced topics such as continuations or parser generators. + This chapter isn&#8217;t specifically about Ranch, we assume here that you know how to read data from the socket. The data you read and the data that hasn&#8217;t been parsed is saved in a buffer.</description> + </item> + + <item> + <title>Writing parsers</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/guide/parsers/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/guide/parsers/</guid> + <description>There are three kinds of protocols: + Text protocols Schema-less binary protocols Schema-based binary protocols This chapter introduces the first two kinds. It will not cover more advanced topics such as continuations or parser generators. + This chapter isn&#8217;t specifically about Ranch, we assume here that you know how to read data from the socket. The data you read and the data that hasn&#8217;t been parsed is saved in a buffer.</description> + </item> + + <item> + <title>Building</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/app/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/app/</guid> + <description>Erlang.mk can do a lot of things, but it is, first and foremost, a build tool. In this chapter we will cover the basics of building a project with Erlang.mk. + For most of this chapter, we will assume that you are using a project generated by Erlang.mk. + How to build To build a project, all you have to do is type make: + $ make It will work regardless of your project: OTP applications, library applications, NIFs, port drivers or even releases.</description> + </item> + + <item> + <title>Listeners</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/listeners/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/listeners/</guid> + <description>A listener is a set of processes that listens on a port for new connections. Incoming connections get handled by Cowboy. Depending on the connection handshake, one or another protocol may be used. + This chapter is specific to Cowboy. Please refer to the Ranch User Guide for more information about listeners. + Cowboy provides two types of listeners: one listening for clear TCP connections, and one listening for secure TLS connections.</description> + </item> + + <item> + <title>SSL client authentication</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/guide/ssl_auth/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/guide/ssl_auth/</guid> + <description>Purpose SSL client authentication is a mechanism allowing applications to identify certificates. This allows your application to make sure that the client is an authorized certificate, but makes no claim about whether the user can be trusted. This can be combined with a password based authentication to attain greater security. + The server only needs to retain the certificate serial number and the certificate issuer to authenticate the certificate. Together, they can be used to uniquely identify a certicate.</description> + </item> + + <item> + <title>SSL client authentication</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/guide/ssl_auth/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/guide/ssl_auth/</guid> + <description>Purpose SSL client authentication is a mechanism allowing applications to identify certificates. This allows your application to make sure that the client is an authorized certificate, but makes no claim about whether the user can be trusted. This can be combined with a password based authentication to attain greater security. + The server only needs to retain the certificate serial number and the certificate issuer to authenticate the certificate. Together, they can be used to uniquely identify a certicate.</description> + </item> + + <item> + <title>Packages and dependencies</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/deps/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/deps/</guid> + <description>Erlang.mk can fetch and compile the dependencies that your project requires. Erlang.mk improves upon the concepts introduced by Rebar, so they should be familiar to many seasoned Erlang developers. + Erlang.mk is not a package manager, nor is it trying to be, but it does include an index of Erlang packages to make discovering useful projects easier. + This chapter will explain how to use packages, add dependencies to your project or bundle them directly in a single repository.</description> + </item> + + <item> + <title>Routing</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/routing/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/routing/</guid> + <description>Cowboy does nothing by default. + To make Cowboy useful, you need to map URIs to Erlang modules that will handle the requests. This is called routing. + When Cowboy receives a request, it tries to match the requested host and path to the configured routes. When there&#8217;s a match, the route&#8217;s associated handler is executed. + Routes need to be compiled before they can be used by Cowboy. The result of the compilation is the dispatch rules.</description> + </item> + + <item> + <title>NIFs and port drivers</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/ports/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/ports/</guid> + <description>Erlang.mk can not only build Erlang projects, but also the C code that some projects come with, like NIFs and port drivers. + There are two ways to build the C code: using a custom Makefile, or making Erlang.mk do it directly. The C code will be built as needed when you run make. + C source code location and Erlang environment The C source code should be located in the $(C_SRC_DIR) directory.</description> + </item> + + <item> + <title>Internals</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/guide/internals/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/guide/internals/</guid> + <description>This chapter may not apply to embedded Ranch as embedding allows you to use an architecture specific to your application, which may or may not be compatible with the description of the Ranch application. + Note that for everything related to efficiency and performance, you should perform the benchmarks yourself to get the numbers that matter to you. Generic benchmarks found on the web may or may not be of use to you, you can never know until you benchmark your own system.</description> + </item> + + <item> + <title>Internals</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/guide/internals/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/guide/internals/</guid> + <description>This chapter may not apply to embedded Ranch as embedding allows you to use an architecture specific to your application, which may or may not be compatible with the description of the Ranch application. + Note that for everything related to efficiency and performance, you should perform the benchmarks yourself to get the numbers that matter to you. Generic benchmarks found on the web may or may not be of use to you, you can never know until you benchmark your own system.</description> + </item> + + <item> + <title>Constraints</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/constraints/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/constraints/</guid> + <description>Constraints are validation and conversion functions applied to user input. + They are used in various places in Cowboy, including the router and the cowboy_req match functions. + Syntax Constraints are provided as a list of fields. For each field in the list, specific constraints can be applied, as well as a default value if the field is missing. + A field can take the form of an atom field, a tuple with constraints {field, Constraints} or a tuple with constraints and a default value {field, Constraints, Default}.</description> + </item> + + <item> + <title>Releases</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/releases/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/releases/</guid> + <description>Erlang.mk relies on Relx for generating releases. This chapter covers the Erlang.mk-specific bits. Consult the Relx website for more information. + Setup Erlang.mk will create a release if it detects a Relx configuration file in the $(RELX_CONFIG) location. This defaults to $(CURDIR)/relx.config. You can override it by defining the variable before including Erlang.mk: + RELX_CONFIG = $(CURDIR)/webchat.config Relx does not need to be installed. Erlang.mk will download and build it automatically.</description> + </item> + + <item> + <title>Self-extracting releases</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/sfx/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/sfx/</guid> + <description>Erlang.mk allows you to package Relx releases as self-extracting archives. These archives contain all the files in the release and come in the form of a script that will extract and run the release automatically. + This allows you to package the release as a single file that can then be executed. + This feature is currently experimental. Feedback is much appreciated. + Generating the self-extracting archive To generate a self-extracting release, all you need to do is pass the SFX=1 variable to Make when you build the release:</description> + </item> + + <item> + <title>Handlers</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/handlers/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/handlers/</guid> + <description>Handlers are Erlang modules that handle HTTP requests. + Plain HTTP handlers 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 Req object and the initial state defined in the router configuration. + A handler that does nothing would look like this: + init(Req, State) -&gt; {ok, Req, State}. 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.</description> + </item> + + <item> + <title>Escripts</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/escripts/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/escripts/</guid> + <description>Escripts are an alternative to release. They are meant to be used for small command line executables written in Erlang. + They are not self-contained, unlike releases. Erlang must be installed for them to run. This however means that they are fairly small compared to releases. + For self-contained executables, check self-extracting releases. + Requirements Erlang.mk uses p7zip by default to generate the escript archive. Make sure it is installed. On most systems the package is named p7zip; on Ubuntu you need p7zip-full.</description> + </item> + + <item> + <title>Loop handlers</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/loop_handlers/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/loop_handlers/</guid> + <description>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 a response. + Loop handlers are used for requests where a response might not be immediately available, but where you would like to keep the connection open for a while in case the response arrives. The most known example of such practice is known as long polling.</description> + </item> + + <item> + <title>OTP version management</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/kerl/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/kerl/</guid> + <description>Erlang.mk comes with integrated support for Kerl, a shell script that automates the downloading, building and installing of Erlang/OTP. It can be used to easily build a specific Erlang/OTP version (with or without custom build options) or maintain different versions side by side. + Erlang versions Erlang.mk uses the Git tags from Erlang/OTP to identify OTP versions. The most recent tag at the time of writing is OTP-20.0.4, which is a patch release of OTP-20.</description> + </item> + + <item> + <title>Static files</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/static_files/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/static_files/</guid> + <description>Cowboy comes with a ready to use handler for serving static files. It is provided as a convenience for serving files during development. + For systems in production, consider using one of the many Content Distribution Network (CDN) available on the market, as they are the best solution for serving files. + The static handler can serve either one file or all files from a given directory. The etag generation and mime types can be configured.</description> + </item> + + <item> + <title>Compatibility with other build tools</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/compat/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/compat/</guid> + <description>Erlang.mk tries its best to be compatible with the other Erlang build tools. It can use dependencies written with other build tools in mind, and can also make your projects usable by those build tools as well. Erlang.mk is like the cool kid that gets along with everybody. + In this chapter I will use the term Rebar project to refer to a project built using Rebar 2, Rebar 3 or Mad.</description> + </item> + + <item> + <title>AsciiDoc documentation</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/asciidoc/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/asciidoc/</guid> + <description>Erlang.mk provides rules for generating documentation from AsciiDoc files. It can automatically build a user guide PDF, chunked HTML documentation and Unix manual pages. + Requirements It is necessary to have AsciiDoc, xsltproc and dblatex installed on your system for Erlang.mk to generate documentation from AsciiDoc sources. + Writing AsciiDoc documentation AsciiDoc is a text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages, man pages and blogs.</description> + </item> + + <item> + <title>The Req object</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/req/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/req/</guid> + <description>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.</description> + </item> + + <item> + <title>Reading the request body</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/req_body/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/req_body/</guid> + <description>The request body can be read using the Req object. + 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 cache the body, it is therefore only possible to read it once. + 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.</description> + </item> + + <item> + <title>EDoc comments</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/edoc/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/edoc/</guid> + <description>Erlang.mk provides a thin wrapper on top of EDoc, an application that generates documentation based on comments found in modules. + Writing EDoc comments The EDoc user guide explains everything you need to know about EDoc comments. + Configuration The EDOC_OPTS variable allows you to specify additional EDoc options. Options are documented in the EDoc manual. + A common use for this variable is to enable Markdown in doc comments, using the edown application:</description> + </item> + + <item> + <title>Erlang shell</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/shell/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/shell/</guid> + <description>Erlang.mk provides a convenient target for starting a shell with all the paths set properly to experiment with your code. + Configuration The SHELL_DEPS variable can be used to define dependencies that are only to be used when the make shell command is called. For example, if you want to use kjell as your shell: + SHELL_DEPS = kjell Dependencies are downloaded and compiled the first time you run the make shell command.</description> + </item> + + <item> + <title>Sending a response</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/resp/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/resp/</guid> + <description>The response must be sent using the Req object. + Cowboy provides two different ways of sending responses: either directly or by streaming the body. Response headers and body may be set in advance. The response is sent as soon as one of the reply or stream reply function is called. + Cowboy also provides a simplified interface for sending files. It can also send only specific parts of a file.</description> + </item> + + <item> + <title>EUnit</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/eunit/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/eunit/</guid> + <description>EUnit is the tool of choice for unit testing. Erlang.mk automates a few things on top of EUnit, including the discovery and running of unit tests. + Writing tests The EUnit user guide is the best place to learn how to write tests. Of note is that all functions ending with _test or _test_ will be picked up as EUnit test cases. + Erlang.mk will automatically pick up tests found in any of the Erlang modules of your application.</description> + </item> + + <item> + <title>Using cookies</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/cookies/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/cookies/</guid> + <description>Cookies are a mechanism allowing applications to maintain state on top of the stateless HTTP protocol. + Cookies are a name/value store where the names and values are stored in plain text. They expire either after a delay or when the browser closes. They can be configured on a specific domain name or path, and restricted to secure resources (sent or downloaded over HTTPS), or restricted to the server (disallowing access from client-side scripts).</description> + </item> + + <item> + <title>Common Test</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/common_test/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/common_test/</guid> + <description>Common Test is Erlang&#8217;s functional testing framework. Erlang.mk automates the discovery and running of Common Test suites. + Writing tests The Common Test user guide is the best place to learn how to write tests. Erlang.mk requires that file names for test suites end with _SUITE.erl and that the files be located in the $(TEST_DIR) directory. This defaults to test/. + Configuration The CT_OPTS variable allows you to set extra Common Test options.</description> + </item> + + <item> + <title>Multipart requests</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/multipart/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/multipart/</guid> + <description>Multipart originates from MIME, an Internet standard that extends the format of emails. + A multipart message is a list of parts. A part contains headers and a body. The body of the parts may be of any media type, and contain text or binary data. It is possible for parts to contain a multipart media type. + In the context of HTTP, multipart is most often used with the multipart/form-data media type.</description> + </item> + + <item> + <title>Code coverage</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/coverage/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/coverage/</guid> + <description>Placeholder chapter. + </description> + </item> + + <item> + <title>REST principles</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/rest_principles/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/rest_principles/</guid> + <description>This chapter will attempt to define the concepts behind REST and explain what makes a service RESTful. + REST is often confused with performing a distinct operation depending on the HTTP method, while using more than the GET and POST methods. That&#8217;s highly misguided at best. + We will first attempt to define REST and will look at what it means in the context of HTTP and the Web. For a more in-depth explanation of REST, you can read Roy T.</description> + </item> + + <item> + <title>Continuous integration</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/ci/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/ci/</guid> + <description>Erlang.mk comes with some support for continuous integration, aimed at open source projects that need to support more than one specific Erlang/OTP release. (If you target one specific release, check the OTP version pinning section of the OTP version management chapter.) + Configuring Erlang/OTP versions to test To use the CI plugin you must first configure which versions of Erlang/OTP will be used. Erlang.mk provides three separate configuration variables depending on whether you need a normal OTP release, a HiPE-enabled release or an ErLLVM-enabled release.</description> + </item> + + <item> + <title>REST handlers</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/rest_handlers/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/rest_handlers/</guid> + <description>REST is implemented in Cowboy as a sub protocol. The request is handled as a state machine with many optional callbacks describing the resource and modifying the machine&#8217;s behavior. + The REST handler is the recommended way to handle HTTP requests. + Initialization First, the init/2 callback is called. This callback is common to all handlers. To use REST for the current request, this function must return a cowboy_rest tuple.</description> + </item> + + <item> + <title>Dialyzer</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/dialyzer/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/dialyzer/</guid> + <description>Dialyzer is a tool that will detect discrepancies in your program. It does so using a technique known as success typing analysis which has the advantage of providing no false positives. Dialyzer is able to detect type errors, dead code and more. + Erlang.mk provides a wrapper around Dialyzer. + How it works Dialyzer requires a PLT file to work. The PLT file contains the analysis information from all applications which are not expected to change, or rarely do.</description> + </item> + + <item> + <title>Xref</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/xref/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/xref/</guid> + <description>Placeholder chapter. + </description> + </item> + + <item> + <title>REST flowcharts</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/rest_flowcharts/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/rest_flowcharts/</guid> + <description>This chapter will explain the REST handler state machine through a number of different diagrams. + There are four main paths that requests may follow. One for the method OPTIONS; one for the methods GET and HEAD; one for the methods PUT, POST and PATCH; and one for the method DELETE. + All paths start with the "Start" diagram, and all paths excluding the OPTIONS path go through the "Content negotiation"</description> + </item> + + <item> + <title>External plugins</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/external_plugins/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/external_plugins/</guid> + <description>It is often convenient to be able to keep the build files used by all your projects in one place. Those files could be Makefiles, configuration files, templates and more. + Erlang.mk allows you to automatically load plugins from dependencies. Plugins can do anything, including defining new variables, defining file templates, hooking themselves inside the normal Erlang.mk processing or even adding new rules. + You can load plugins using one of two methods.</description> + </item> + + <item> + <title>Designing a resource handler</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/resource_design/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/resource_design/</guid> + <description>This chapter aims to provide you with a list of questions you must answer in order to write a good resource handler. It is meant to be usable as a step by step guide. + The service Can the service become unavailable, and when it does, can we detect it? For example, database connectivity problems may be detected early. We may also have planned outages of all or parts of the system.</description> + </item> + + <item> + <title>List of plugins</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/external_plugins_list/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/external_plugins_list/</guid> + <description>This is a non-exhaustive list of Erlang.mk plugins, sorted alphabetically. + efene.mk An Efene plugin for Erlang.mk. Efene is an alternative language for the BEAM. + elixir.mk An Elixir plugin for Erlang.mk. Elixir is an alternative language for the BEAM. + elvis.mk An Elvis plugin for Erlang.mk. Elvis is an Erlang style reviewer. + geas Geas gives aggregated information on a project and its dependencies, and is available as an Erlang.</description> + </item> + + <item> + <title>The Websocket protocol</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/ws_protocol/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/ws_protocol/</guid> + <description>This chapter explains what Websocket is and why it is a vital component of soft realtime Web applications. + Description Websocket is an extension to HTTP that emulates plain TCP connections between the client, typically a Web browser, and the server. It uses the HTTP Upgrade mechanism to establish the connection. + Websocket connections are fully asynchronous, unlike HTTP/1.1 (synchronous) and HTTP/2 (asynchronous, but the server can only initiate streams in response to requests).</description> + </item> + + <item> + <title>Why Erlang.mk</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/why/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/why/</guid> + <description>Why would you choose Erlang.mk, if not for its many features? This chapter will attempt to answer that. + Erlang.mk is fast Erlang.mk is as fast as it gets. + Erlang.mk will group the compilation of files so as to avoid running the BEAM more than necessary. This saves many seconds compared to traditional Makefiles, even on small projects. + Erlang.mk will not try to be too smart. It provides a simple solution that works for most people, and gives additional options for projects that run into edge cases, often in the form of extra variables or rules to be defined.</description> + </item> + + <item> + <title>Websocket handlers</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/ws_handlers/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/ws_handlers/</guid> + <description>Websocket handlers provide an interface for upgrading HTTP/1.1 connections to Websocket and sending or receiving frames on the Websocket connection. + As Websocket connections are established through the HTTP/1.1 upgrade mechanism, Websocket handlers need to be able to first receive the HTTP request for the upgrade, before switching to Websocket and taking over the connection. They can then receive or send Websocket frames, handle incoming Erlang messages or close the connection.</description> + </item> + + <item> + <title>Short history</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/history/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/history/</guid> + <description>This chapter aims to be a brief record of the life of the Erlang.mk project. + Before Erlang.mk Erlang.mk originates from the Cowboy project. Cowboy started as a Rebar project and I, Loïc Hoguin, was very happy with it for a couple years. Over time however I started getting annoyed and frustrated by a number of things, including bad defaults, changing defaults and overall slowness. + In particular, at the time I gave up on Rebar, the Cowboy test suite was taking about five minutes to run.</description> + </item> + + <item> + <title>Streams</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/streams/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/streams/</guid> + <description>A stream is the set of messages that form an HTTP request/response pair. + The term stream comes from HTTP/2. In Cowboy, it is also used when talking about HTTP/1.1 or HTTP/1.0. It should not be confused with streaming the request or response body. + All versions of HTTP allow clients to initiate streams. HTTP/2 is the only one also allowing servers, through its server push feature. Both client and server-initiated streams go through the same process in Cowboy.</description> + </item> + + <item> + <title>Contributing</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/contributing/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/contributing/</guid> + <description>You are welcome and encouraged to contribute. + This is how. + Priorities From the most important to the least important: + Bugs Package issues/additions Refactoring Features Bugs If you have found a bug, you should open a ticket. Include everything relevant including the command you used, output, a link to the code that triggers the issue, why you think this is a bug, etc.</description> + </item> + + <item> + <title>Middlewares</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/middlewares/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/middlewares/</guid> + <description>Cowboy delegates the request processing to middleware components. By default, two middlewares are defined, for the routing and handling of the request, as is detailed in most of this guide. + Middlewares give you complete control over how requests are to be processed. You can add your own middlewares to the mix or completely change the chain of middlewares as needed. + Cowboy will execute all middlewares in the given order, unless one of them decides to stop processing.</description> + </item> + + <item> + <title>Migrating from Cowboy 1.0 to 2.0</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/migrating_from_1.0/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/migrating_from_1.0/</guid> + <description>A lot has changed between Cowboy 1.0 and 2.0. The cowboy_req interface in particular has seen a massive revamp. Hooks are gone, their functionality can now be achieved via stream handlers. + The documentation has seen great work, in particular the manual. Each module and each function now has its own dedicated manual page with full details and examples. + Compatibility Compatibility with Erlang/OTP R16, 17 and 18 has been dropped.</description> + </item> + + <item> + <title>HTTP and other specifications</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/specs/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/specs/</guid> + <description>This chapter intends to list all the specification documents for or related to HTTP. + HTTP IANA Registries HTTP Method Registry HTTP Status Code Registry Message Headers HTTP Parameters HTTP Alt-Svc Parameter Registry HTTP Authentication Scheme Registry HTTP Cache Directive Registry HTTP Digest Algorithm Values HTTP Origin-Bound Authentication Device Identifier Types HTTP Upgrade Token Registry HTTP Warn Codes HTTP/2 Parameters WebSocket Protocol Registries Current CORS: Cross-Origin Resource Sharing CSP2: Content Security Policy Level 2 DNT: Tracking Preference Expression (DNT) eventsource: Server-Sent Events Form content types: Form content types Preload: Preload REST: Fielding&#8217;s Dissertation RFC 1945: HTTP/1.</description> + </item> <item> <title>Cowboy 2.0 release candidate 2</title> @@ -15,42 +844,10 @@ <pubDate>Wed, 23 Aug 2017 18:00:00 +0100</pubDate> <guid>https://ninenines.eu/articles/cowboy-2.0.0-rc.2/</guid> - <description><div class="paragraph"><p>Cowboy <code>2.0.0-rc.2</code> has been released!</p></div>
-<div class="paragraph"><p>This is the new recommended version of Cowboy.
-Its API should not change before release. While
-you probably should not use it in production yet,
-many do successfully. Use at your own risk.</p></div>
-<div class="paragraph"><p>This new version contains fixes for the following
-issues:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-HTTP/2 server push was using the wrong header
- compression context.
-</p>
-</li>
-<li>
-<p>
-HTTP/2 flow control could end up queueing data
- in the wrong order when resuming the sending of
- data.
-</p>
-</li>
-<li>
-<p>
-The <code>shutdown</code> timeout was not implemented
- and request processes could be killed too quickly.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>What else is new in Cowboy 2.0? Check the
-<a href="https://ninenines.eu/articles/cowboy-2.0.0-rc.1">rc.1 announcement</a>.</p></div>
-<div class="paragraph"><p>Please test this new release candidate and provide
-feedback! The best place to provide feedback is via
-tickets. Do not hesitate to open a ticket or bring
-an existing ticket to my attention to get it resolved
-before 2.0.</p></div>
-</description> + <description>Cowboy 2.0.0-rc.2 has been released! + This is the new recommended version of Cowboy. Its API should not change before release. While you probably should not use it in production yet, many do successfully. Use at your own risk. + This new version contains fixes for the following issues: + HTTP/2 server push was using the wrong header compression context. HTTP/2 flow control could end up queueing data in the wrong order when resuming the sending of data.</description> </item> <item> @@ -59,63 +856,9 @@ before 2.0.</p></div> <pubDate>Mon, 24 Jul 2017 18:00:00 +0100</pubDate> <guid>https://ninenines.eu/articles/cowboy-2.0.0-rc.1/</guid> - <description><div class="paragraph"><p>Cowboy <code>2.0.0-rc.1</code> has been released!</p></div>
-<div class="paragraph"><p>This is the new recommended version of Cowboy.
-Its API should not change before release. While
-you probably should not use it in production yet,
-many do successfully. Use at your own risk.</p></div>
-<div class="paragraph"><p>The plan is to have a new RC version every couple
-weeks until the summer ends or later if there are
-still blocking issues open. Only issues that can&#8217;t
-be fixed without making breaking changes to the
-interface may block the release.</p></div>
-<div class="paragraph"><p>Numerous changes were made since Cowboy 1.0. The
-one most people care about is probably HTTP/2, but
-it&#8217;s most likely not the only one worthwhile. The
-full list of changes (excluding types) can be found
-in the user guide chapter
-<a href="https://ninenines.eu/docs/en/cowboy/2.0/guide/migrating_from_1.0/">Migrating from Cowboy 1.0 to 2.0</a>.</p></div>
-<div class="paragraph"><p>As this is not the full release just yet, please pay
-extra attention to details and report anything
-suspicious you find.</p></div>
-<div class="paragraph"><p>There are still some tests failing. Most of those are
-related to standards that are not being followed perfectly
-just yet. Some of those will probably not be fixed before
-Cowboy 2.0 is released. They are edge cases and should not
-prevent interoperability.</p></div>
-<div class="paragraph"><p>The manual received a lot of love. It now has one page per
-function with a detailed description, arguments list, return
-value, changelog and examples. It also links to the other
-relevant manual pages: <a href="https://ninenines.eu/docs/en/cowboy/2.0/manual/">https://ninenines.eu/docs/en/cowboy/2.0/manual/</a></p></div>
-<div class="paragraph"><p>Cowboy is now tested and supported with Erlang/OTP 19.0 or above
-on Arch Linux, FreeBSD, OSX, Ubuntu and Windows 7. Contact me
-if you can provide permanent access to another platform for the
-purposes of testing.</p></div>
-<div class="paragraph"><p>Cowboy is now available from four locations:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="https://git.ninenines.eu/cowboy.git">https://git.ninenines.eu/cowboy.git</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://github.com/ninenines/cowboy.git">https://github.com/ninenines/cowboy.git</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://bitbucket.org/ninenines/cowboy.git">https://bitbucket.org/ninenines/cowboy.git</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://gitlab.com/ninenines/cowboy.git">https://gitlab.com/ninenines/cowboy.git</a>
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>They are updated at the same time so there is no real difference.</p></div>
-</description> + <description>Cowboy 2.0.0-rc.1 has been released! + This is the new recommended version of Cowboy. Its API should not change before release. While you probably should not use it in production yet, many do successfully. Use at your own risk. + The plan is to have a new RC version every couple weeks until the summer ends or later if there are still blocking issues open. Only issues that can&#8217;t be fixed without making breaking changes to the interface may block the release.</description> </item> <item> @@ -124,140 +867,8 @@ purposes of testing.</p></div> <pubDate>Sun, 26 Mar 2017 00:00:00 +0100</pubDate> <guid>https://ninenines.eu/articles/the-elephant-in-the-room/</guid> - <description><div class="paragraph"><p>Have you ever tried telling someone why they should use
-Erlang? You boast the smaller code size, the auto healing
-mechanisms, the distribution and they seem really excited.
-They wonder why they never heard about Erlang before. And
-then you show them what the code looks like. All excitement
-goes away. The smiles disappear. Their face starts
-becoming really serious.</p></div>
-<div class="paragraph"><p>You lost them. You know you lost them. They comment on the
-syntax, or perhaps you do, already admitting defeat. It&#8217;s
-unlike anything they have ever used before. And they will
-most likely end up not using it.</p></div>
-<div class="paragraph"><p>What about people who already know what the syntax looks
-like? As soon as you mention Erlang, the topic of the syntax
-comes in. It&#8217;s like nothing else matters.</p></div>
-<div class="paragraph"><p>Perhaps the topic of syntax didn&#8217;t come up. But they&#8217;re
-still not going to try Erlang because of it.</p></div>
-<div class="paragraph"><p>You&#8217;re probably not having these kinds of interactions at
-Erlang conferences. This doesn&#8217;t happen with people who are
-already somewhat interested in, or need, the features that
-Erlang provides. With them the syntax is at worst a minor
-inconvenience.</p></div>
-<div class="paragraph"><p>This happens because most developers are familiar with
-syntaxes that look nothing like Erlang. To be clear, I
-include language features and other concepts like objects
-as part of "syntax" here. Familiarity is a very important
-factor to drive adoption.</p></div>
-<div class="paragraph"><p>You can see an example of that in the Elixir world, where
-the majority of people come from Ruby or already knew and
-liked Ruby. The 2016 survey tells us that 59% of Elixir
-developers were using Ruby primarily before. That&#8217;s in
-large part because of the syntax. They will deny it of
-course and find other reasons. And yet, we don&#8217;t see such
-a strong adoption of Erlang from Ruby developers, before
-or after Elixir appeared.</p></div>
-<div class="paragraph"><p>Side note: have you ever wondered why the Elixir community
-is, I quote, much friendlier than the Ruby community?
-Despite having much of the same people?</p></div>
-<div class="paragraph"><p>Before we continue, let me be clear. I love the Erlang
-syntax. It is simple and explicit. It is powerful, especially
-when dealing with binary data. It has very few quirks.
-It has little to no ambiguity. It&#8217;s great. Except for
-persuading people to use it.</p></div>
-<div class="paragraph"><p>Over the years I have been writing Erlang, I have seen
-very few people point out that the syntax slows down
-adoption. We have no problem with it, so why would others?
-At the same time, people coming to Erlang come to solve
-a real problem they&#8217;re having, so the syntax is fairly
-secondary. Even if they hate it at first, they know they
-can solve their problems despite the syntax.</p></div>
-<div class="paragraph"><p>You don&#8217;t build a popular product or language by solving
-people&#8217;s problems though. In general you end up solving
-some problems and creating new problems. No, you build
-a popular product by <strong>convincing people to use it</strong>. And
-you make them stay with your product by making them
-<strong>commit</strong> to using it.</p></div>
-<div class="paragraph"><p>Take MongoDB for example. It didn&#8217;t become popular by
-working, or even by being practical. It wasn&#8217;t performing
-its primary function and was losing people&#8217;s data. That
-didn&#8217;t stop it from becoming popular. Smart people would
-knowingly use a database that was losing data. Think about
-that for a minute.</p></div>
-<div class="paragraph"><p>MongoDB of course had a huge marketing machine, and they
-focused on that. They helped organize many meetups all
-over the world, complete with various swag items given
-for free, including a small handbook about MongoDB. All
-people had to do was show up.</p></div>
-<div class="paragraph"><p>They didn&#8217;t go tell people to look at all the weaknesses
-their product had. They focused on the strengths. On
-what would convince people to try it. They would go
-to meetups, discuss with others, commit to try it (or
-try it at meetups directly), and by doing so sell MongoDB
-to themselves.</p></div>
-<div class="paragraph"><p>How do we get people to meetups though? That&#8217;d be the
-first step: you need to <strong>catch their attention</strong>.
-I believe MongoDB did this using benchmark results.
-Ironic isn&#8217;t it? MongoDB gets fast benchmark results
-because they lose data, and this gets everyone to buy
-into the product.</p></div>
-<div class="paragraph"><p>The key points to remember about this are:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-catch people&#8217;s attention
-</p>
-</li>
-<li>
-<p>
-show your product&#8217;s strengths
-</p>
-</li>
-<li>
-<p>
-make people take a commitment
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Once they commit to something, you win. Everyone will not
-end up ultimately using your product of course, but it&#8217;s
-at the very least become a consideration. It&#8217;s on their
-mind. Their resolve will be stronger when they ultimately
-try it and inevitably run into issues.</p></div>
-<div class="paragraph"><p>Erlang&#8217;s syntax is a weakness. Almost nobody looks at the
-Erlang syntax and falls in love with it at first sight.
-No, it takes time to learn it and understand how good it
-is. You need to sell Erlang to people without showing
-the Erlang syntax. If you do show it, then you need to
-hide the parts that feel alien. Function calls are OK.
-Recursion, not so much. Maps are OK. Records, not.</p></div>
-<div class="paragraph"><p>Avoiding code is not always possible when you try
-to sell it, especially to developers. You can however
-prepare them to accept the alien syntax by admitting
-that the syntax is not perfect before you show it.
-You can do this while praising it at the same time.
-For example, "the syntax is a little out there, but
-it matches the concepts perfectly, it will all make
-sense when you start learning".</p></div>
-<div class="paragraph"><p>This might not be the best introduction. Someone will
-need to A/B test it to find the one that gives the
-best results. But that should give you ideas.</p></div>
-<div class="paragraph"><p>When something terrible happens, mentioning that this
-isn&#8217;t the end of the world <strong>before</strong> you tell others what
-happened will soften their reaction. When someone
-breaks your favorite item and cries over it calling
-themselves stupid, it&#8217;s harder to get mad at them,
-compared to the same event with no emotional reaction.</p></div>
-<div class="paragraph"><p>Our behavior is largely dependent on what&#8217;s at the
-top of our mind, so it&#8217;s up to you to take advantage
-of this to make your case in the best conditions.</p></div>
-<div class="paragraph"><p>Next time you try to make someone use Erlang, remember
-that you should aim for getting a spoken commitment
-out of them, if possible before you show the syntax.
-If that&#8217;s not possible, then prepare them to accept
-the flaws or the weirdness before they see them.</p></div>
-</description> + <description>Have you ever tried telling someone why they should use Erlang? You boast the smaller code size, the auto healing mechanisms, the distribution and they seem really excited. They wonder why they never heard about Erlang before. And then you show them what the code looks like. All excitement goes away. The smiles disappear. Their face starts becoming really serious. + You lost them. You know you lost them. They comment on the syntax, or perhaps you do, already admitting defeat.</description> </item> <item> @@ -266,119 +877,8 @@ the flaws or the weirdness before they see them.</p></div> <pubDate>Sun, 22 Jan 2017 00:00:00 +0100</pubDate> <guid>https://ninenines.eu/articles/dont-let-it-crash/</guid> - <description><div class="paragraph"><p>We have a specific mindset when writing Erlang
-programs. We focus on the normal execution of the
-program and don&#8217;t handle most of the errors that may
-occur. We sometimes call this normal execution the
-<em>happy path</em>.</p></div>
-<div class="paragraph"><p>The general pattern behind writing only for the
-<em>happy path</em>, letting the VM catch errors (writing
-them to a log for future consumption) and then
-having a supervisor restart the processes that
-failed from a clean state, has a name. We call it
-<em>let it crash</em>; and it drives many of our design
-decisions.</p></div>
-<div class="paragraph"><p>It&#8217;s a really great way to program and the results
-are fantastic compared to most other programming
-languages. And yet, <em>let it crash</em> barely convinced
-anyone that they should use Erlang. Why would that
-be?</p></div>
-<div class="paragraph"><p>You may already know that Cowboy is capable of
-handling at least 2 million Websocket connections
-on a single server. This is in large part thanks
-to the capabilities of the VM. Still, 2 million
-is good, much better than most other servers can
-do.</p></div>
-<div class="paragraph"><p>Cowboy is not just a Websocket server; it&#8217;s also
-an HTTP and HTTP/2 server, and it handles many
-related features like long polling or the parsing
-of most request headers.</p></div>
-<div class="paragraph"><p>Can you guess how large the Cowboy codebase is,
-without looking at the source?</p></div>
-<div class="paragraph"><p>Do make sure you have a clear answer in your mind
-before you go check.</p></div>
-<div class="paragraph"><p>Good, you are back. Now what were the results? If
-I am correct, you overestimated the size of Cowboy.
-Cowboy is in fact about five thousand lines of code.
-You probably thought it was at least ten thousand.
-About eighty percent of readers will have
-overestimated the size of Cowboy. And you did only
-because I mentioned it can handle millions of
-Websocket connections.</p></div>
-<div class="paragraph"><p>Numerous studies show this effect. Just mentioning
-the large number already prepared your mind to think
-in that direction. Repeating the number made you
-focus even more on it. Then the question asked for
-a number, which ended up larger than the reality.</p></div>
-<div class="paragraph"><p>The same effect can be applied to negotiation for
-example. You generally want to start by giving your
-offer (and not let the other party initiate) and
-you want to give a really large number first. You
-can also prepare your customer by mentioning an even
-larger number in the previous discussion.</p></div>
-<div class="paragraph"><p>And it&#8217;s not just numbers either. An experiment
-showed that just by looking at an image of clouds,
-customers of a pillow store were buying pillows
-more comfortable (and more expensive) than those
-who didn&#8217;t see that image.</p></div>
-<div class="paragraph"><p>This is the power of associations. It is covered in
-much larger detail in the books
-<a href="https://www.amazon.com/Influence-Psychology-Persuasion-Robert-Cialdini/dp/006124189X">Influence</a>
-and
-<a href="https://www.amazon.com/Pre-Suasion-Revolutionary-Way-Influence-Persuade/dp/1501109790">Pre-suasion</a>.
-I highly recommend reading those and applying what
-you learn to your daily life. I&#8217;m definitely not
-a professional psychologist so take this post with
-a grain of salt.</p></div>
-<div class="paragraph"><p>When selling Erlang, whether we are selling it to
-a customer or trying to convince a developer friend
-to start using it, we often talk about how Erlang
-<em>lets you sleep at night</em>, that it is auto healing
-and always gets fantastic uptimes.</p></div>
-<div class="paragraph"><p>And then we talk about <em>let it crash</em>.</p></div>
-<div class="paragraph"><p>And we describe what it means.</p></div>
-<div class="paragraph"><p>We might as well just say that Erlang crashes a lot
-and then take the door. It would have the same effect.
-It doesn&#8217;t even stop at programs crashing. You know
-what else crashes? Cars, planes, trains. Often with
-disastrous consequences. Is that really the message
-we want to convey?</p></div>
-<div class="paragraph"><p>They even <a href="https://img.youtube.com/vi/oEUBW2lCkIk/0.jpg">printed it on a t-shirt</a>!
-Keep calm and let it crash. It&#8217;s the kind of t-shirt
-you probably shouldn&#8217;t wear in an airport, and for good
-reasons. A few people did, then realized what they were
-wearing and were not too smug about it.</p></div>
-<div class="paragraph"><p>And yet this is how we sell Erlang.</p></div>
-<div class="paragraph"><p>A better way would be to focus on the positives, of
-course, but also to make sure that those positives
-are phrased in a way that prevents bad associations
-to be formed in people&#8217;s minds.</p></div>
-<div class="paragraph"><p>Instead of <em>let it crash</em>, you can say that Erlang
-has <em>auto healing mechanisms</em>. Healing is a good
-thing and accurately describes what happens in the
-system.</p></div>
-<div class="paragraph"><p>Should you need to go into more details, you will
-probably want to avoid <em>recover from crashes</em> and
-instead say <em>recover from exceptions</em>. Exceptions
-are a pretty neutral word and, should you explain
-what you mean by that, you can talk about exceptions
-that occur for reasons unrelated to Erlang, like
-hardware failure or network instability.</p></div>
-<div class="paragraph"><p>The trick is to always use positive words and
-phrases to describe Erlang, and to use external
-factors to explain how Erlang deals with failures.
-Never mention the failures internal to Erlang
-systems unless you are asked specifically, in
-which case you can say that the auto healing
-applies to all exceptions.</p></div>
-<div class="paragraph"><p>The <em>let it crash</em> philosophy is great when
-learning Erlang or when writing fault-tolerant
-systems. But it&#8217;s not going to convince anyone
-to use it unless they were already looking for
-it.</p></div>
-<div class="paragraph"><p>Do you like this post? Tell me on Twitter. I might
-make more.</p></div>
-</description> + <description>We have a specific mindset when writing Erlang programs. We focus on the normal execution of the program and don&#8217;t handle most of the errors that may occur. We sometimes call this normal execution the happy path. + The general pattern behind writing only for the happy path, letting the VM catch errors (writing them to a log for future consumption) and then having a supervisor restart the processes that failed from a clean state, has a name.</description> </item> <item> @@ -387,117 +887,10 @@ make more.</p></div> <pubDate>Tue, 03 Jan 2017 00:00:00 +0100</pubDate> <guid>https://ninenines.eu/articles/cowboy-2.0.0-pre.4/</guid> - <description><div class="paragraph"><p>Cowboy <code>2.0.0-pre.4</code> has been released!</p></div>
-<div class="paragraph"><p>This is the new recommended version of Cowboy.
-While I would not recommend putting it in production
-just yet, I do recommend you start writing new
-applications with this Cowboy version.</p></div>
-<div class="paragraph"><p>The most significant changes in the pre-release are:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-A new architecture: there now is one process per
- connection and one process per request. This was
- done because HTTP/2 allows running requests concurrently.
-</p>
-</li>
-<li>
-<p>
-Stream handlers. Every request, response and data goes
- through stream handlers. They are meant to replace hooks
- and more. They will be documented in a future pre-release.
- Check <code>cowboy_stream</code> and <code>cowboy_stream_h</code> if interested.
-</p>
-</li>
-<li>
-<p>
-Numerous changes to the <code>cowboy_req</code> interface. This
- is very close to final. Check the manual for what changed.
-</p>
-</li>
-<li>
-<p>
-The Req object is no longer passed in Websocket callbacks.
-</p>
-</li>
-<li>
-<p>
-It is now possible to send frames directly from <code>websocket_init/1</code>.
-</p>
-</li>
-<li>
-<p>
-SPDY support was removed, now that we have HTTP/2.
-</p>
-</li>
-<li>
-<p>
-Update Ranch to 1.3. We still depend on Cowlib master
- for the time being.
-</p>
-</li>
-<li>
-<p>
-A much improved manual.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>The manual received a lot of love. It now has one page per
-function with a detailed description, arguments list, return
-value, changelog and examples. It also links to the other
-relevant manual pages: <a href="https://ninenines.eu/docs/en/cowboy/2.0/manual/">https://ninenines.eu/docs/en/cowboy/2.0/manual/</a></p></div>
-<div class="paragraph"><p>I am quite proud of the manual right now. While more
-improvements can be made, what we have now is way better
-than before. Feedback for further improvements is welcome!</p></div>
-<div class="paragraph"><p>This is a significant step toward Cowboy 2.0. Almost all
-the breaking changes are in. A few more pre-releases are
-planned and will be released on a weekly basis (with exceptions).</p></div>
-<div class="paragraph"><p>Cowboy is now tested and supported with Erlang/OTP 18.0 or above
-on Arch Linux, FreeBSD, OSX, Ubuntu and Windows 7. Contact me
-if you can provide permanent access to another platform for the
-purposes of testing.</p></div>
-<div class="paragraph"><p>Cowboy is now available from four locations:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="https://git.ninenines.eu/cowboy.git">https://git.ninenines.eu/cowboy.git</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://github.com/ninenines/cowboy.git">https://github.com/ninenines/cowboy.git</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://bitbucket.org/ninenines/cowboy.git">https://bitbucket.org/ninenines/cowboy.git</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://gitlab.com/ninenines/cowboy.git">https://gitlab.com/ninenines/cowboy.git</a>
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>They are updated at the same time so there is no real difference.</p></div>
-<div class="paragraph"><p>Cowboy 2.0 will be released once all the breaking changes
-are completed and the temporarily removed features are
-added back.</p></div>
-<div class="paragraph"><p>Thanks for your patience. I know it took a long time.</p></div>
-<hr/>
-<div class="paragraph"><p>Half-price on all donations because I need a new hat:</p></div>
-<form action="https://www.paypal.com/cgi-bin/webscr" method="post" style="display:inline">
-<input type="hidden" name="cmd" value="_donations">
-<input type="hidden" name="business" value="[email protected]">
-<input type="hidden" name="lc" value="FR">
-<input type="hidden" name="item_name" value="Loic Hoguin">
-<input type="hidden" name="item_number" value="99s">
-<input type="hidden" name="currency_code" value="EUR">
-<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHosted">
-<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
-<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1">
-</form>
-</description> + <description>Cowboy 2.0.0-pre.4 has been released! + This is the new recommended version of Cowboy. While I would not recommend putting it in production just yet, I do recommend you start writing new applications with this Cowboy version. + The most significant changes in the pre-release are: + A new architecture: there now is one process per connection and one process per request. This was done because HTTP/2 allows running requests concurrently.</description> </item> <item> @@ -506,89 +899,9 @@ added back.</p></div> <pubDate>Mon, 28 Nov 2016 00:00:00 +0100</pubDate> <guid>https://ninenines.eu/articles/ranch-1.3/</guid> - <description><div class="paragraph"><p>Ranch <code>1.3.0</code> has been released!</p></div>
-<div class="paragraph"><p>This release fixes a number of long standing issues and adds
-a small number of features:</p></div>
-<div class="paragraph"><p>The <code>ssl</code> application has been added to the list of dependencies.
-If you don&#8217;t need it, you can remove it automatically when fetching
-Ranch or when building the release. If you do need it, you will no
-longer have issues shutting down a node because of Ranch.</p></div>
-<div class="paragraph"><p>The <code>ranch:info/0</code> and <code>ranch:procs/2</code> can be used to retrieve
-information about Ranch&#8217;s state. Use it for diagnostic and
-discovery purposes.</p></div>
-<div class="paragraph"><p>SSL listeners can now be configured without a certificate, for setups
-that make use of the SNI extension.</p></div>
-<div class="paragraph"><p>Transport options are now a blacklist, meaning all unknown options
-will be accepted. However Dialyzer will warn if said option is not
-defined in Ranch&#8217;s type specifications. Please send a patch when that
-happens!</p></div>
-<div class="paragraph"><p>Various bugs have been fixed, including the bug where the
-number of active connections could become negative. Common
-errors at listener startup should be easier to read (for
-example when the port is already in use).</p></div>
-<div class="paragraph"><p>See the <a href="https://git.ninenines.eu/ranch.git/plain/CHANGELOG.asciidoc">CHANGELOG</a>
-for more details.</p></div>
-<div class="paragraph"><p>Ranch is now tested and supported with Erlang/OTP R16B or above
-on Arch Linux, FreeBSD, OSX, Ubuntu and Windows 7. Contact me
-if you can provide permanent access to another platform for the
-purposes of testing.</p></div>
-<div class="paragraph"><p>Ranch is now available from four locations:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-<a href="https://git.ninenines.eu/ranch.git">https://git.ninenines.eu/ranch.git</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://github.com/ninenines/ranch.git">https://github.com/ninenines/ranch.git</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://bitbucket.org/ninenines/ranch.git">https://bitbucket.org/ninenines/ranch.git</a>
-</p>
-</li>
-<li>
-<p>
-<a href="https://gitlab.com/ninenines/ranch.git">https://gitlab.com/ninenines/ranch.git</a>
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>They are updated at the same time so there is no real difference.</p></div>
-<div class="paragraph"><p>The most recent Ranch commit is now always signed. You can import the
-<a href="https://pgp.mit.edu/pks/lookup?op=vindex&amp;fingerprint=on&amp;exact=on&amp;search=0xF19F189CECC7439699CEDD7A6EF7A77066CCCC8A">signing key for Loïc Hoguin</a> with:</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>$ gpg --keyserver hkp<span style="color: #990000">:</span>//keys<span style="color: #990000">.</span>gnupg<span style="color: #990000">.</span>net --recv-key 66CCCC8A</tt></pre></div></div>
-<div class="paragraph"><p>The primary key fingerprint is <code>F19F 189C ECC7 4396 99CE DD7A 6EF7 A770 66CC CC8A</code>.</p></div>
-<div class="paragraph"><p>When verifying signatures in git, the following should appear:</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>gpg<span style="color: #990000">:</span> Signature made Sat <span style="color: #993399">26</span> Nov <span style="color: #993399">2016</span> <span style="color: #993399">12</span><span style="color: #990000">:</span><span style="color: #993399">58</span><span style="color: #990000">:</span><span style="color: #993399">35</span> PM CET
-gpg<span style="color: #990000">:</span> using RSA key 71366FF21851DF03
-gpg<span style="color: #990000">:</span> Good signature from <span style="color: #FF0000">"Loïc Hoguin &lt;[email protected]&gt;"</span> <span style="color: #990000">[</span>unknown<span style="color: #990000">]</span>
-gpg<span style="color: #990000">:</span> WARNING<span style="color: #990000">:</span> This key is not certified with a trusted signature<span style="color: #990000">!</span>
-gpg<span style="color: #990000">:</span> There is no indication that the signature belongs to the owner<span style="color: #990000">.</span>
-Primary key fingerprint<span style="color: #990000">:</span> F19F 189C ECC7 <span style="color: #993399">4396</span> 99CE DD7A 6EF7 A770 66CC CC8A
- Subkey fingerprint<span style="color: #990000">:</span> FEDA <span style="color: #993399">6E41</span> B390 F745 A385 5CDC <span style="color: #993399">7136</span> 6FF2 <span style="color: #993399">1851</span> DF03</tt></pre></div></div>
-<div class="paragraph"><p>You can safely ignore the warning if you don&#8217;t know what it
-means, as long as everything else is correct.</p></div>
-<div class="paragraph"><p>Mirrors and signature verification will soon be implemented
-directly in Erlang.mk. In the meantime, you will need to
-set them up manually.</p></div>
-<div class="paragraph"><p>Most of this work was done to fix issues in RabbitMQ. Paid
-customers get priority; contact me if you have some issues
-that need fixing sooner rather than later.</p></div>
-<div class="paragraph"><p>Expect future releases to be announced in this space.</p></div>
-<div class="paragraph"><p>Thanks for reading!</p></div>
-</description> + <description>Ranch 1.3.0 has been released! + This release fixes a number of long standing issues and adds a small number of features: + The ssl application has been added to the list of dependencies. If you don&#8217;t need it, you can remove it automatically when fetching Ranch or when building the release. If you do need it, you will no longer have issues shutting down a node because of Ranch.</description> </item> <item> @@ -597,17 +910,10 @@ that need fixing sooner rather than later.</p></div> <pubDate>Mon, 29 Aug 2016 00:00:00 +0100</pubDate> <guid>https://ninenines.eu/articles/ml-archives/</guid> - <description><div class="paragraph"><p>The <a href="https://ninenines.eu/archives/extend">old mailing list archives</a> have been
-added to the site, mainly for referencing purposes.</p></div>
-<div class="paragraph"><p>The mailing list has been shut down and all personal information
-has been deleted.</p></div>
-<div class="paragraph"><p>If you need help with a project, consider either opening a ticket
-on that project&#8217;s issues tracker or going through the community
-channels (erlang-questions, #ninenines or #erlang on Freenode).</p></div>
-<div class="paragraph"><p>Prefer tickets; often when people have issues it highlights an
-underlying problem in the project or its documentation.</p></div>
-<div class="paragraph"><p>Thanks.</p></div>
-</description> + <description>The old mailing list archives have been added to the site, mainly for referencing purposes. + The mailing list has been shut down and all personal information has been deleted. + If you need help with a project, consider either opening a ticket on that project&#8217;s issues tracker or going through the community channels (erlang-questions, #ninenines or #erlang on Freenode). + Prefer tickets; often when people have issues it highlights an underlying problem in the project or its documentation.</description> </item> <item> @@ -616,64 +922,9 @@ underlying problem in the project or its documentation.</p></div> <pubDate>Sat, 02 Apr 2016 00:00:00 +0100</pubDate> <guid>https://ninenines.eu/articles/website-update/</guid> - <description><div class="paragraph"><p>Last week-end I updated the Nine Nines website.</p></div>
-<div class="paragraph"><p>I switched to <a href="http://gohugo.io/">Hugo</a>. The site is
-now built from <a href="http://asciidoc.org/">Asciidoc</a>
-documents. You probably saw me switch to Asciidoc
-for documentation this past year. This is the
-natural conclusion to that story. The great thing
-is that with a little bit of Makefile magic I can
-just copy the documentation files into Hugo and
-poof, they appear on the website.</p></div>
-<div class="paragraph"><p>I am very happy with that new setup. I can now
-post my thoughts again. Woo! Expect regular posts
-from now on. I will try to replace my long series
-of tweets with posts.</p></div>
-<div class="paragraph"><p>The sections have been rearranged. There used to
-be a separate training section; now
-<a href="https://ninenines.eu/services">all my services</a> are described in
-one page. I have also clarified my areas of
-expertise. There used to be confusion in the past,
-so now it should be clearer that I am not a
-distributed systems expert.</p></div>
-<div class="paragraph"><p>On that note, if you are looking for my
-services right now, I&#8217;m not available. I&#8217;ll have
-to work 7 days a week for a while. Try again in a
-couple months. More on that in a future post.</p></div>
-<div class="paragraph"><p>The <a href="https://ninenines.eu/docs">documentation</a> becomes a first class
-citizen. Bullet and Cowlib don&#8217;t have proper
-documentation&#8230; yet. I have started working on the
-Cowlib documentation, and Bullet shouldn&#8217;t take too
-long. All these projects will be documented when
-Cowboy gets to 2.0, and will all be supported
-equally. Note that the Cowboy 1.0 documentation
-still has the old website templates and links.
-Don&#8217;t worry about it.</p></div>
-<div class="paragraph"><p>The mailing lists link has been removed. I did
-announce a few months back that mailing lists were
-going to go. They&#8217;re still up right now, but not
-for long. I am planning to put the archives
-read-only, link to them from a future post and
-be done with it. If you have a question, open a
-ticket on Github. Then I can just decide to leave
-the ticket open if I want to do improvements based
-on your feedback.</p></div>
-<div class="paragraph"><p>I have replaced most of the "we" by "I". I am
-a one-man company right now. Have been for a while.
-Doesn&#8217;t make sense to keep a facade. I want to be
-close to users, not put a barrier between us.</p></div>
-<div class="paragraph"><p>The RSS changed. The old link doesn&#8217;t work anymore.
-The new link is at <a href="https://ninenines.eu/index.xml">/index.xml</a>,
-or <a href="https://ninenines.eu/articles/index.xml">/articles/index.xml</a>
-if you only care about my posts. I guess that&#8217;s the
-one most people want.</p></div>
-<div class="paragraph"><p>I still have some tweaks to do, but it will take a
-while. My long term plan is to remove Bootstrap, use
-vanilla CSS and as little JS as possible. The reason
-for that is that it&#8217;s cheaper than upgrading libraries
-every few years. Life is too short to spend it
-upgrading JS libraries.</p></div>
-</description> + <description>Last week-end I updated the Nine Nines website. + I switched to Hugo. The site is now built from Asciidoc documents. You probably saw me switch to Asciidoc for documentation this past year. This is the natural conclusion to that story. The great thing is that with a little bit of Makefile magic I can just copy the documentation files into Hugo and poof, they appear on the website. + I am very happy with that new setup.</description> </item> <item> @@ -682,20 +933,10 @@ upgrading JS libraries.</p></div> <pubDate>Wed, 02 Sep 2015 00:00:00 +0100</pubDate> <guid>https://ninenines.eu/articles/erlanger-playbook-september-2015-update/</guid> - <description><div class="paragraph"><p>An update to The Erlanger Playbook is now available!</p></div>
-<div class="paragraph"><p>The Erlanger Playbook is a book about software development using
-Erlang. It currently covers all areas from the conception, design,
-the writing of code, documentation and tests.</p></div>
-<div class="paragraph"><p>The book is still a work in progress. Future topics will include
-refactoring, debugging and tracing, benchmarking, releases, community
-management (for open source projects).</p></div>
-<div class="paragraph"><p>This update fixes a number of things and adds two chapters: IOlists
-and Erlang building blocks.</p></div>
-<div class="paragraph"><p>Learn more about <a href="https://ninenines.eu/articles/erlanger-playbook">The Erlanger Playbook</a>!</p></div>
-<div class="paragraph"><p>This is a self-published ebook. The base price is 50€. All proceeds
-will be used to allow me to work on open source full time.</p></div>
-<div class="paragraph"><p>Thank you for helping me helping you help us all!</p></div>
-</description> + <description>An update to The Erlanger Playbook is now available! + The Erlanger Playbook is a book about software development using Erlang. It currently covers all areas from the conception, design, the writing of code, documentation and tests. + The book is still a work in progress. Future topics will include refactoring, debugging and tracing, benchmarking, releases, community management (for open source projects). + This update fixes a number of things and adds two chapters: IOlists and Erlang building blocks.</description> </item> <item> @@ -704,108 +945,11 @@ will be used to allow me to work on open source full time.</p></div> <pubDate>Wed, 01 Jul 2015 00:00:00 +0100</pubDate> <guid>https://ninenines.eu/services/</guid> - <description><div class="paragraph"><p>If you are interested by any of these opportunities,
-<a href="mailto:[email protected]">send me an email</a>.</p></div>
-<div class="sect1">
-<h2 id="_consulting">Consulting</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can get me, Loïc Hoguin, author of Cowboy, to help you
-solve a problem or work on a particular project.</p></div>
-<div class="paragraph"><p>My area of expertise is Erlang; HTTP, Websocket and REST APIs;
-design and implementation of protocols; and messaging systems.</p></div>
-<div class="paragraph"><p>I can also be helpful with testing or code reviews.</p></div>
-<div class="paragraph"><p>I offer both hourly and daily rates:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-200€ hourly rate (remote)
-</p>
-</li>
-<li>
-<p>
-1000€ daily rate (remote and on-site)
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>For remote consulting, the work can be done by phone, email,
-IRC, GitHub and/or any other platform for collaborative work.</p></div>
-<div class="paragraph"><p>For on-site consulting, the travel expenses and
-accomodations are to be paid by the customer. I will also
-ask for a higher rate if forced to stay on-site for more
-than a week.</p></div>
-<div class="paragraph"><p>Note that my expertise does not cover all areas where
-Erlang is used. My help will be limited in the areas of
-distributed databases, or large distributed systems.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_sponsoring">Sponsoring</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can sponsor one of my projects.</p></div>
-<div class="paragraph"><p>Sponsoring gives you:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-a direct, private line of communication
-</p>
-</li>
-<li>
-<p>
-the power to make me maintain older versions of my projects
- (as long as they are sponsoring)
-</p>
-</li>
-<li>
-<p>
-priority when adding features or fixing bugs
-</p>
-</li>
-<li>
-<p>
-advertisement space on this website and in the README file
- of the project of your choice
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Sponsors may choose to benefit from any of these perks.</p></div>
-<div class="paragraph"><p>In exchange sponsors must contribute financially. A minimum
-of 200€ per month is required. Sponsors may give as much as
-they want. Payment can be monthly or one-time. Invoices are
-of course provided.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_erlang_beginner_training">Erlang beginner training</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>I would be happy to introduce more people to Erlang. I have
-a 1-day Erlang training readily available for consumption.
-The goal of this training is to teach the basics of Erlang
-systems and programming. It&#8217;s a kind of "Getting started"
-for Erlang.</p></div>
-<div class="paragraph"><p>You can review the <a href="https://ninenines.eu/talks/thinking-in-erlang/thinking-in-erlang.html">training slides</a>.</p></div>
-<div class="paragraph"><p>This training is meant to be given to a large number of
-people interested in Erlang, as part of a public event,
-where anyone interested can come.</p></div>
-<div class="paragraph"><p>Another important aspect of this training is that it is
-meant to be affordable. We want the most people to learn
-Erlang as possible.</p></div>
-<div class="paragraph"><p>If you have room, think you can gather 20+ people and
-are interested in sponsoring a training session, then
-we should talk.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_custom_training">Custom training</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>I can also provide custom training, tailored to your level
-and your needs. It can take the form of a class, Q&amp;A or a
-code review/writing session. I need to know your expectations
-to prepare an appropriate training.</p></div>
-<div class="paragraph"><p>Custom training rates are the same as consulting rates and
-the same restrictions apply.</p></div>
-</div>
-</div>
-</description> + <description>If you are interested by any of these opportunities, send me an email. + Consulting You can get me, Loïc Hoguin, author of Cowboy, to help you solve a problem or work on a particular project. + My area of expertise is Erlang; HTTP, Websocket and REST APIs; design and implementation of protocols; and messaging systems. + I can also be helpful with testing or code reviews. + I offer both hourly and daily rates:</description> </item> <item> @@ -814,13 +958,9 @@ the same restrictions apply.</p></div> <pubDate>Wed, 01 Jul 2015 00:00:00 +0100</pubDate> <guid>https://ninenines.eu/docs/</guid> - <description><div class="sect2">
-<h3 id="_contribute">Contribute</h3>
-<div class="paragraph"><p>Do you have examples, tutorials, videos about one or more
-of my projects? I would happily include them on this page.</p></div>
-<div class="paragraph"><p><a href="mailto:[email protected]">Send me an email with the details</a>.</p></div>
-</div>
-</description> + <description>Contribute Do you have examples, tutorials, videos about one or more of my projects? I would happily include them on this page. + Send me an email with the details. + </description> </item> <item> @@ -829,23 +969,8 @@ of my projects? I would happily include them on this page.</p></div> <pubDate>Wed, 01 Jul 2015 00:00:00 +0100</pubDate> <guid>https://ninenines.eu/donate/</guid> - <description><div class="sect2">
-<h3 id="_like_my_work_donate">Like my work? Donate!</h3>
-<div class="paragraph"><p>Donate to Loïc Hoguin because his work on Cowboy
-and Erlang.mk is fantastic:</p></div>
-<form action="https://www.paypal.com/cgi-bin/webscr" method="post" style="display:inline">
-<input type="hidden" name="cmd" value="_donations">
-<input type="hidden" name="business" value="[email protected]">
-<input type="hidden" name="lc" value="FR">
-<input type="hidden" name="item_name" value="Loic Hoguin">
-<input type="hidden" name="item_number" value="99s">
-<input type="hidden" name="currency_code" value="EUR">
-<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHosted">
-<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
-<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1">
-</form>
-</div>
-</description> + <description>Like my work? Donate! Donate to Loïc Hoguin because his work on Cowboy and Erlang.mk is fantastic: + </description> </item> <item> @@ -854,15 +979,9 @@ and Erlang.mk is fantastic:</p></div> <pubDate>Wed, 01 Jul 2015 00:00:00 +0100</pubDate> <guid>https://ninenines.eu/talks/</guid> - <description><div class="sect2">
-<h3 id="_talk_requests">Talk requests</h3>
-<div class="paragraph"><p>Organizing a conference and in need of a speaker for a talk
-about Erlang and the Web? Need an introduction to Erlang/OTP
-for your company? Looking for a cool subject for a user group
-meeting?</p></div>
-<div class="paragraph"><p><a href="mailto:[email protected]">Send me an email with the details</a>.</p></div>
-</div>
-</description> + <description>Talk requests Organizing a conference and in need of a speaker for a talk about Erlang and the Web? Need an introduction to Erlang/OTP for your company? Looking for a cool subject for a user group meeting? + Send me an email with the details. + </description> </item> <item> @@ -871,10 +990,9 @@ meeting?</p></div> <pubDate>Wed, 01 Jul 2015 00:00:00 +0100</pubDate> <guid>https://ninenines.eu/slogan/</guid> - <description><div class="paragraph"><p>Feeling generous? Love reading?<br />
-<a href="https://salt.bountysource.com/teams/ninenines">Crowdfund my salary</a>
-or buy <a href="https://ninenines.eu/articles/erlanger-playbook">The Erlanger Playbook</a></p></div>
-</description> + <description>Feeling generous? Love reading? +Crowdfund my salary or buy The Erlanger Playbook + </description> </item> <item> @@ -883,88 +1001,1175 @@ or buy <a href="https://ninenines.eu/articles/erlanger-playbook">T <pubDate>Thu, 18 Jun 2015 00:00:00 +0100</pubDate> <guid>https://ninenines.eu/articles/erlanger-playbook/</guid> - <description><div class="paragraph"><p>I am proud to announce the pre-release of The Erlanger Playbook.</p></div>
-<div class="paragraph"><p>The Erlanger Playbook is a book about software development using
-Erlang. It currently covers all areas from the conception, design,
-the writing of code, documentation and tests.</p></div>
-<div class="paragraph"><p>The book is still a work in progress. Future topics will include
-refactoring, debugging and tracing, benchmarking, releases, community
-management (for open source projects).</p></div>
-<div class="paragraph"><p>The following sections are currently available:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-About this book; Changelog; Future additions
-</p>
-</li>
-<li>
-<p>
-<em>Erlang:</em> Building blocks; Patterns
-</p>
-</li>
-<li>
-<p>
-<em>Workflow:</em> Think; Write; Stay productive
-</p>
-</li>
-<li>
-<p>
-<em>Documentation:</em> On documentation; Tutorials; User guide; Manual; README files
-</p>
-</li>
-<li>
-<p>
-<em>Design:</em> RESTful APIs; Lessons learned
-</p>
-</li>
-<li>
-<p>
-<em>Code:</em> Starting a project; Version control; Project structure; Code style; Best practices; Special processes; IOLists; The process dictionary
-</p>
-</li>
-<li>
-<p>
-<em>Tests:</em> On testing; Success typing analysis; Manual testing; Unit testing; Functional testing
-</p>
-</li>
-<li>
-<p>
-<em>Selling Erlang:</em> On persuasion; Don&#8217;t let it crash
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Read a preview: <a href="https://ninenines.eu/res/erlanger-preview.pdf">Special processes</a></p></div>
-<div class="paragraph"><p>The book is currently 180 pages long. The final version
-of the book is planned to be between 200 and 250 pages.
-A print version of the book will be considered once the final
-version gets released. The printed book is <strong>not</strong> included
-in the price.</p></div>
-<div class="paragraph"><p>This is a self-published book. The base price is 50€. All proceeds
-will be used to allow me to work on open source full time.</p></div>
-<form action="https://www.paypal.com/cgi-bin/webscr" method="post" target="_top">
-<input type="hidden" name="cmd" value="_s-xclick">
-<input type="hidden" name="hosted_button_id" value="9M44HJCGX3GVN">
-<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_buynowCC_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
-<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1">
-</form>
-<div class="paragraph"><p>You are more than welcome to pay extra by using this second button.
-It allows you to set the price you want. Make sure to set it to at least
-50€ to receive the book.</p></div>
-<form action="https://www.paypal.com/cgi-bin/webscr" method="post" target="_top">
-<input type="hidden" name="cmd" value="_s-xclick">
-<input type="hidden" name="hosted_button_id" value="BBW9TR9LBK8C2">
-<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_buynowCC_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
-<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1">
-</form>
-<div class="paragraph"><p>Make sure to provide a valid email address.</p></div>
-<div class="paragraph"><p>There will be a <strong>delay</strong> between payment and sending of the book.
-This process is currently manual.</p></div>
-<div class="paragraph"><p>As the book is a pre-release, feedback is more than welcome. You can
-send your comments to erlanger@ this website.</p></div>
-<div class="paragraph"><p>The plan is to add content regularly until I run out of things to say.
-You will receive updates to the book for free as soon as they are available.</p></div>
-<div class="paragraph"><p>Huge thanks for your interest in buying this book!</p></div>
-</description> + <description>I am proud to announce the pre-release of The Erlanger Playbook. + The Erlanger Playbook is a book about software development using Erlang. It currently covers all areas from the conception, design, the writing of code, documentation and tests. + The book is still a work in progress. Future topics will include refactoring, debugging and tracing, benchmarking, releases, community management (for open source projects). + The following sections are currently available:</description> + </item> + + <item> + <title>Validating UTF-8 binaries with Erlang</title> + <link>https://ninenines.eu/articles/erlang-validate-utf8/</link> + <pubDate>Fri, 06 Mar 2015 00:00:00 +0100</pubDate> + + <guid>https://ninenines.eu/articles/erlang-validate-utf8/</guid> + <description>Yesterday I pushed Websocket permessage-deflate to Cowboy master. I also pushed a change in the way the code validates UTF-8 data (required for text and close frames as per the spec). + When looking into why the permessage-deflate tests in autobahntestsuite were taking such a long time, I found that autobahn is using an adaptation of the algorithm named Flexible and Economical UTF-8 Decoder. This is the C99 implementation: + // Copyright (c) 2008-2009 Bjoern Hoehrmann &lt;bjoern@hoehrmann.</description> + </item> + + <item> + <title>On open source</title> + <link>https://ninenines.eu/articles/on-open-source/</link> + <pubDate>Fri, 05 Sep 2014 00:00:00 +0100</pubDate> + + <guid>https://ninenines.eu/articles/on-open-source/</guid> + <description>Last week I read a great article on contributing to open source by Alvaro Videla. He makes many great points and I am in agreement with most of it. This made me want to properly explain my point of view with regard to open source and contributions. Unlike most open source evangelism articles I will not talk about ideals or any of that crap, but rather my personal feelings and experience.</description> + </item> + + <item> + <title>The story so far</title> + <link>https://ninenines.eu/articles/the-story-so-far/</link> + <pubDate>Sat, 23 Aug 2014 00:00:00 +0100</pubDate> + + <guid>https://ninenines.eu/articles/the-story-so-far/</guid> + <description>As I am away from home with little to do (some call this a vacation) I wanted to reflect a little on the story so far, or how I arrived to Erlang and got to where I am now. The raw personal experience. It&#8217;ll be an article that&#8217;s more about social aspect, communities and marketing a project than technical considerations. As a period piece, it will also allow me to reflect on the evolution of Erlang in recent years.</description> + </item> + + <item> + <title>Cowboy 2.0 and query strings</title> + <link>https://ninenines.eu/articles/cowboy2-qs/</link> + <pubDate>Wed, 20 Aug 2014 00:00:00 +0100</pubDate> + + <guid>https://ninenines.eu/articles/cowboy2-qs/</guid> + <description>Now that Cowboy 1.0 is out, I can spend some of my time thinking about Cowboy 2.0 that will be released soon after Erlang/OTP 18.0. This entry discusses the proposed changes to query string handling in Cowboy. + Cowboy 2.0 will respond to user wishes by simplifying the interface of the cowboy_req module. Users want two things: less juggling with the Req variable, and more maps. Maps is the only dynamic key/value data structure in Erlang that we can match directly to extract values, allowing users to greatly simplify their code as they don&#8217;t need to call functions to do everything anymore.</description> + </item> + + <item> + <title>January 2014 status</title> + <link>https://ninenines.eu/articles/january-2014-status/</link> + <pubDate>Tue, 07 Jan 2014 00:00:00 +0100</pubDate> + + <guid>https://ninenines.eu/articles/january-2014-status/</guid> + <description>I will now be regularly writing posts about project status, plans and hopes for the future. + Before that though, there&#8217;s one important news to share. + Until a year ago all development was financed through consulting and development services. This worked alright but too much time was spent doing things that didn&#8217;t benefit the open source projects. And that didn&#8217;t make me happy at all. Because I like being happy I stopped that for the most part and spent the year figuring things out, experimenting and discussing with people about it.</description> + </item> + + <item> + <title>Farwest got funded!</title> + <link>https://ninenines.eu/articles/farwest-funded/</link> + <pubDate>Thu, 27 Jun 2013 00:00:00 +0100</pubDate> + + <guid>https://ninenines.eu/articles/farwest-funded/</guid> + <description>This was a triumph! I&#8217;m making a note here: HUGE SUCCESS!! + It&#8217;s hard to overstate my satisfaction. Thanks to everyone who made this possible. + If you have backed this fundraiser, and haven&#8217;t provided your personal details yet, please do so quickly so that your rewards can be sent! + I am hoping that we will be able to make good use of all that money. The details of the expenses will be published regularly on the 2013 Fundraiser wiki page, giving you full disclosure as to how your money is used.</description> + </item> + + <item> + <title>Build Erlang releases with Erlang.mk and Relx</title> + <link>https://ninenines.eu/articles/erlang.mk-and-relx/</link> + <pubDate>Tue, 28 May 2013 00:00:00 +0100</pubDate> + + <guid>https://ninenines.eu/articles/erlang.mk-and-relx/</guid> + <description>Building OTP releases has always been a difficult task. Tools like Reltool or Rebar have made this simpler, but it&#8217;s no panacea. This article will show you an alternative and hopefully much simpler solution. + There is two steps to building a release. First you need to build the various OTP applications you want to include in the release. Once done, you need to create the release itself, by including the Erlang runtime system alongside the applications, a boot script to start the node and all its applications, and some configuration files.</description> + </item> + + <item> + <title>Xerl: intermediate module</title> + <link>https://ninenines.eu/articles/xerl-0.5-intermediate-module/</link> + <pubDate>Mon, 25 Mar 2013 00:00:00 +0100</pubDate> + + <guid>https://ninenines.eu/articles/xerl-0.5-intermediate-module/</guid> + <description>Today we will start the work on the intermediate module that will be used to run the code for the expressions found in our file&#8217;s body, replacing our interpreter. + This is what we want to have when all the work is done: + xerl -&gt; tokens -&gt; AST -&gt; intermediate -&gt; cerl Today we will perform this work only on the atomic integer expression however, so we will not build any module at the end.</description> + </item> + + <item> + <title>Xerl: expression separator</title> + <link>https://ninenines.eu/articles/xerl-0.4-expression-separator/</link> + <pubDate>Fri, 01 Mar 2013 00:00:00 +0100</pubDate> + + <guid>https://ninenines.eu/articles/xerl-0.4-expression-separator/</guid> + <description>As promised we are adding an expression separator this time. This will be short and easy. + In the tokenizer we only need to add a line recognizing the comma as a valid token. + , : {token, {',', TokenLine}}. Then we need to change the following lines in the parser: + exprs -&gt; expr : ['$1']. exprs -&gt; expr exprs : ['$1' | '$2']. And add a comma between the expressions on the second line:</description> + </item> + + <item> + <title>Erlang Scalability</title> + <link>https://ninenines.eu/articles/erlang-scalability/</link> + <pubDate>Mon, 18 Feb 2013 00:00:00 +0100</pubDate> + + <guid>https://ninenines.eu/articles/erlang-scalability/</guid> + <description>I would like to share some experience and theories on Erlang scalability. + This will be in the form of a series of hints, which may or may not be accompanied with explanations as to why things are this way, or how they improve or reduce the scalability of a system. I will try to do my best to avoid giving falsehoods, even if that means a few things won&#8217;t be explained.</description> + </item> + + <item> + <title>Xerl: atomic expressions</title> + <link>https://ninenines.eu/articles/xerl-0.3-atomic-expressions/</link> + <pubDate>Mon, 18 Feb 2013 00:00:00 +0100</pubDate> + + <guid>https://ninenines.eu/articles/xerl-0.3-atomic-expressions/</guid> + <description>We will be adding atomic integer expressions to our language. These look as follow in Erlang: + 42. And the result of this expression is of course 42. + We will be running this expression at compile time, since we don&#8217;t have the means to run code at runtime yet. This will of course result in no module being compiled, but that&#8217;s OK, it will allow us to discuss a few important things we&#8217;ll have to plan for later on.</description> + </item> + + <item> + <title>Xerl: two modules</title> + <link>https://ninenines.eu/articles/xerl-0.2-two-modules/</link> + <pubDate>Sun, 03 Feb 2013 00:00:00 +0100</pubDate> + + <guid>https://ninenines.eu/articles/xerl-0.2-two-modules/</guid> + <description>Everything is an expression. + This sentence carries profound meaning. We will invoke it many times over the course of these articles. + If everything is an expression, then the language shouldn&#8217;t have any problem with me defining two modules in the same source file. + mod first_module begin end mod second_module begin end Likewise, it shouldn&#8217;t have any problem with me defining a module inside another module. + mod out_module begin mod in_module begin end end Of course, in the context of the Erlang VM, these two snippets are equivalent; there is nothing preventing you from calling the in_module module from any other module.</description> + </item> + + <item> + <title>Xerl: empty modules</title> + <link>https://ninenines.eu/articles/xerl-0.1-empty-modules/</link> + <pubDate>Wed, 30 Jan 2013 00:00:00 +0100</pubDate> + + <guid>https://ninenines.eu/articles/xerl-0.1-empty-modules/</guid> + <description>Let&#8217;s build a programming language. I call it Xerl: eXtended ERLang. It&#8217;ll be an occasion for us to learn a few things, especially me. + Unlike in Erlang, in this language, everything is an expression. This means that modules and functions are expression, and indeed that you can have more than one module per file. + We are just starting, so let&#8217;s no go ahead of ourselves here. We&#8217;ll begin with writing the code allowing us to compile an empty module.</description> + </item> + + <item> + <title>Build an FTP Server with Ranch in 30 Minutes</title> + <link>https://ninenines.eu/articles/ranch-ftp/</link> + <pubDate>Wed, 14 Nov 2012 00:00:00 +0100</pubDate> + + <guid>https://ninenines.eu/articles/ranch-ftp/</guid> + <description>Last week I was speaking at the London Erlang Factory Lite where I presented a live demonstration of building an FTP server using Ranch. As there was no slide, you should use this article as a reference instead. + The goal of this article is to showcase how to use Ranch for writing a network protocol implementation, how Ranch gets out of the way to let you write the code that matters, and the common techniques used when writing servers.</description> + </item> + + <item> + <title>Erlang Tic Tac Toe</title> + <link>https://ninenines.eu/articles/tictactoe/</link> + <pubDate>Wed, 17 Oct 2012 00:00:00 +0100</pubDate> + + <guid>https://ninenines.eu/articles/tictactoe/</guid> + <description>Everyone knows Tic Tac Toe, right? + Players choose either to be the Xs or the Os, then place their symbol on a 3x3 board one after another, trying to create a line of 3 of them. + Writing an algorithm to check for victory sounds easy, right? It&#8217;s easily tested, considering there&#8217;s only 8 possible winning rows (3 horizontal, 3 vertical and 2 diagonal). + In Erlang though, you probably wouldn&#8217;t want an algorithm.</description> + </item> + + <item> + <title>Cowboy Function Reference</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/</guid> + <description>Name cowboy - Small, fast, modern HTTP server for Erlang/OTP + Description Cowboy is an HTTP server for Erlang/OTP with support for the HTTP/1.1, HTTP/2 and Websocket protocols. + Cowboy aims to provide a complete HTTP stack. This includes the implementation of the HTTP RFCs but also any directly related standards, like Websocket or Server-Sent Events. + Modules Functions: + cowboy(3) - Listener management cowboy_req(3) - Request and response cowboy_router(3) - Router cowboy_constraints(3) - Constraints Protocols:</description> + </item> + + <item> + <title>Cowboy User Guide</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/guide/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/guide/</guid> + <description>Rationale The modern Web Erlang and the Web Introduction Introduction Getting started Flow diagram Configuration Listeners Routing Constraints Handlers Handlers Loop handlers Static files Request and response Request details Reading the request body Sending a response Using cookies Multipart REST REST principles Handling REST requests REST flowcharts Designing a resource handler Websocket The Websocket protocol Websocket handlers Advanced Streams Middlewares Additional information Migrating from Cowboy 1.</description> + </item> + + <item> + <title>Erlang.mk User Guide</title> + <link>https://ninenines.eu/docs/en/erlang.mk/1/guide/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/erlang.mk/1/guide/</guid> + <description>Installation Getting started Overview Updating Erlang.mk Limitations Code Building Packages and dependencies NIFs and port drivers Releases Self-extracting releases Escripts OTP version management Compatibility with other build tools Documentation Asciidoc documentation EDoc comments Tests Erlang shell EUnit Common Test Code coverage Continuous integration Dialyzer Xref Third-party plugins External plugins List of plugins About Erlang.</description> + </item> + + <item> + <title>Gun Function Reference</title> + <link>https://ninenines.eu/docs/en/gun/1.0/manual/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/gun/1.0/manual/</guid> + <description> gun(7) gun(3) </description> + </item> + + <item> + <title>Gun User Guide</title> + <link>https://ninenines.eu/docs/en/gun/1.0/guide/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/gun/1.0/guide/</guid> + <description> Introduction Starting and stopping Supported protocols Connection Using HTTP Using Websocket </description> + </item> + + <item> + <title>HTTP status codes(7)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/http_status_codes/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/http_status_codes/</guid> + <description>Name HTTP status codes - status codes used by Cowboy + Description This chapter aims to list all HTTP status codes that Cowboy may return, with details on the reasons why. The list given here only includes the replies that Cowboy sends, not user replies. + 100 Continue When the client sends an expect: 100-continue header, Cowboy automatically sends a this status code before trying to read the request body.</description> + </item> + + <item> + <title>Ranch Function Reference</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/manual/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/manual/</guid> + <description> ranch(7) ranch(3) ranch_protocol(3) ranch_ssl(3) ranch_tcp(3) ranch_transport(3) </description> + </item> + + <item> + <title>Ranch Function Reference</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/manual/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/manual/</guid> + <description> ranch(7) ranch(3) ranch_protocol(3) ranch_ssl(3) ranch_tcp(3) ranch_transport(3) </description> + </item> + + <item> + <title>Ranch User Guide</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/guide/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/guide/</guid> + <description> Introduction Listeners Transports Protocols Embedded mode Writing parsers SSL client authentication Internals </description> + </item> + + <item> + <title>Ranch User Guide</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/guide/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/guide/</guid> + <description> Introduction Listeners Transports Protocols Embedded mode Writing parsers SSL client authentication Internals </description> + </item> + + <item> + <title>cowboy(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy/</guid> + <description>Name cowboy - HTTP server + Description The module cowboy provides convenience functions for manipulating Ranch listeners. + Exports cowboy:start_clear(3) - Listen for connections using plain TCP cowboy:start_tls(3) - Listen for connections using TLS cowboy:stop_listener(3) - Stop the given listener cowboy:set_env(3) - Update a listener&#8217;s environment value Types fields() fields() :: [Name | {Name, Constraints} | {Name, Constraints, Default}] Name :: atom() Constraints :: Constraint | [Constraint] Constraint :: cowboy_constraints:constraint() Default :: any() Fields description for match operations.</description> + </item> + + <item> + <title>cowboy(7)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_app/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_app/</guid> + <description>Name cowboy - Small, fast, modern HTTP server for Erlang/OTP + Description Cowboy is an HTTP server for Erlang/OTP with support for the HTTP/1.1, HTTP/2 and Websocket protocols. + Cowboy aims to provide a complete HTTP stack. This includes the implementation of the HTTP RFCs but also any directly related standards, like Websocket or Server-Sent Events. + Modules Functions: + cowboy(3) - Listener management cowboy_req(3) - Request and response cowboy_router(3) - Router cowboy_constraints(3) - Constraints Protocols:</description> + </item> + + <item> + <title>cowboy:set_env(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.set_env/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.set_env/</guid> + <description>Name cowboy:set_env - Update a listener&#8217;s environment value + Description set_env(Name :: ranch:ref(), Key :: atom(), Value :: any()) -&gt; ok Set or update an environment value for a previously started listener. + This is most useful for updating the routes dynamically, without having to restart the listener. + The new value will only be available to new connections. Pre-existing connections will still use the old value. + Arguments Name The name of the listener to update.</description> + </item> + + <item> + <title>cowboy:start_clear(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.start_clear/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.start_clear/</guid> + <description>Name cowboy:start_clear - Listen for connections using plain TCP + Description start_clear(Name :: ranch:ref(), TransportOpts :: ranch_tcp:opts(), ProtocolOpts :: opts()) -&gt; {ok, ListenerPid :: pid()} | {error, any()} Start listening for connections over a clear TCP channel. + Both HTTP/1.1 and HTTP/2 are supported on this listener. HTTP/2 has two methods of establishing a connection over a clear TCP channel. Both the upgrade and the prior knowledge methods are supported.</description> + </item> + + <item> + <title>cowboy:start_tls(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.start_tls/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.start_tls/</guid> + <description>Name cowboy:start_tls - Listen for connections using TLS + Description start_tls(Name :: ranch:ref(), TransportOpts :: ranch_ssl:opts(), ProtocolOpts :: opts()) -&gt; {ok, ListenerPid :: pid()} | {error, any()} Start listening for connections over a secure TLS channel. + Both HTTP/1.1 and HTTP/2 are supported on this listener. The ALPN TLS extension must be used to initiate an HTTP/2 connection. + Arguments Name The listener name is used to refer to this listener in future calls, for example when stopping it or when updating the routes defined.</description> + </item> + + <item> + <title>cowboy:stop_listener(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.stop_listener/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.stop_listener/</guid> + <description>Name cowboy:stop_listener - Stop the given listener + Description stop_listener(Name :: ranch:ref()) -&gt; ok | {error, not_found}. Stop a previously started listener. + Alias of ranch:stop_listener(3). + Arguments Name The name of the listener to be stopped. The name of the listener is the first argument given to the cowboy:start_clear(3), cowboy:start_tls(3) or ranch:start_listener(3) function. + Return value The atom ok is returned on success.</description> + </item> + + <item> + <title>cowboy_constraints(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_constraints/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_constraints/</guid> + <description>Name cowboy_constraints - Constraints + Description The module cowboy_constraints defines the built-in constraints in Cowboy and provides an interface for manipulating these constraints. + Constraints are functions that define what type of input is allowed. They are used throughout Cowboy, from the router to query strings to cookies. + Exports Built-in constraints: + cowboy_constraints:int(3) - Integer constraint cowboy_constraints:nonempty(3) - Non-empty constraint Types constraint() constraint() :: int | nonempty | fun() A constraint function.</description> + </item> + + <item> + <title>cowboy_constraints:int(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_constraints.int/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_constraints.int/</guid> + <description>Name cowboy_constraints:int - Integer constraint + Description Constraint functions implement a number of different operations. + int(forward, Bin) -&gt; {ok, Int} | {error, not_an_integer} Bin :: binary() Int :: integer() Validate and convert the text representation of an integer. + int(reverse, Int) -&gt; {ok, Bin} | {error, not_an_integer} Convert an integer back to its text representation. + int(format_error, Error) -&gt; HumanReadable Error :: {not_an_integer, Bin | Int} HumanReadable :: iolist() Generate a human-readable error message.</description> + </item> + + <item> + <title>cowboy_constraints:nonempty(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_constraints.nonempty/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_constraints.nonempty/</guid> + <description>Name cowboy_constraints:nonempty - Non-empty constraint + Description Constraint functions implement a number of different operations. + nonempty(forward | reverse, &lt;&lt;&gt;&gt;) -&gt; {error, empty} Reject empty values. + nonempty(forward | reverse, Bin) -&gt; {ok, Bin} Bin :: binary() Accept any other binary values. + nonempty(format_error, Error) -&gt; HumanReadable Error :: {empty, Bin} HumanReadable :: iolist() Generate a human-readable error message. + Arguments Arguments vary depending on the operation.</description> + </item> + + <item> + <title>cowboy_handler(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_handler/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_handler/</guid> + <description>Name cowboy_handler - Plain HTTP handlers + Description The cowboy_handler middleware executes the handler selected by the router or any other preceding middleware. + This middleware takes the handler module and initial state from the handler and handler_opts environment values, respectively. On completion, it adds a result value to the middleware environment, containing the return value of the terminate/3 callback (if defined) and ok otherwise. + This module also defines a callback interface for handling HTTP requests.</description> + </item> + + <item> + <title>cowboy_handler:terminate(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_handler.terminate/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_handler.terminate/</guid> + <description>Name cowboy_handler:terminate - Terminate the handler + Description terminate(Reason, PartialReq, State, Handler) -&gt; ok Reason :: any() PartialReq :: map() State :: any() Handler :: module() Call the optional terminate callback if it is defined. + Make sure to use this function at the end of the execution of modules that implement custom handler behaviors. + Arguments Reason Reason for termination. PartialReq The Req object.</description> + </item> + + <item> + <title>cowboy_http(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_http/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_http/</guid> + <description>Name cowboy_http - HTTP/1.1 + Description The module cowboy_http implements HTTP/1.1 and HTTP/1.0 as a Ranch protocol. + Options opts() :: #{ connection_type =&gt; worker | supervisor, env =&gt; cowboy_middleware:env(), idle_timeout =&gt; timeout(), inactivity_timeout =&gt; timeout(), max_empty_lines =&gt; non_neg_integer(), max_header_name_length =&gt; non_neg_integer(), max_header_value_length =&gt; non_neg_integer(), max_headers =&gt; non_neg_integer(), max_keepalive =&gt; non_neg_integer(), max_method_length =&gt; non_neg_integer(), max_request_line_length =&gt; non_neg_integer(), middlewares =&gt; [module()], request_timeout =&gt; timeout(), shutdown_timeout =&gt; timeout(), stream_handlers =&gt; [module()] } Configuration for the HTTP/1.</description> + </item> + + <item> + <title>cowboy_http2(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_http2/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_http2/</guid> + <description>Name cowboy_http2 - HTTP/2 + Description The module cowboy_http2 implements HTTP/2 as a Ranch protocol. + Options opts() :: #{ connection_type =&gt; worker | supervisor, env =&gt; cowboy_middleware:env(), inactivity_timeout =&gt; timeout(), middlewares =&gt; [module()], preface_timeout =&gt; timeout(), shutdown_timeout =&gt; timeout(), stream_handlers =&gt; [module()] } Configuration for the HTTP/2 protocol. + This configuration is passed to Cowboy when starting listeners using cowboy:start_clear/3 or cowboy:start_tls/3 functions. + It can be updated without restarting listeners using the Ranch functions ranch:get_protocol_options/1 and ranch:set_protocol_options/2.</description> + </item> + + <item> + <title>cowboy_loop(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_loop/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_loop/</guid> + <description>Name cowboy_loop - Loop handlers + Description The module cowboy_loop defines a callback interface for long running HTTP connections. + You should switch to this behavior for long polling, server-sent events and similar long-running requests. + There are generally two usage patterns: + Loop until receiving a specific message, then send a response and stop execution (for example long polling); Or initiate a response in init/2 and stream the body in info/3 as necessary (for example server-sent events).</description> + </item> + + <item> + <title>cowboy_middleware(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_middleware/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_middleware/</guid> + <description>Name cowboy_middleware - Middlewares + Description The module cowboy_middleware defines a callback interface for Cowboy middlewares. + Middlewares process the request sequentially in the order they are configured. + Callbacks Middlewares implement the following interface: + execute(Req, Env) -&gt; {ok, Req, Env} | {suspend, module(), atom(), [any()]} | {stop, Req} Req :: cowboy_req:req() Env :: cowboy_middleware:env() The execute/2 is the only callback that needs to be implemented.</description> + </item> + + <item> + <title>cowboy_req(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req/</guid> + <description>Name cowboy_req - HTTP request and response + Description The module cowboy_req provides functions to access, manipulate and respond to requests. + There are four types of functions in this module. They can be differentiated by their name and their return type: + Type Name pattern Return type access + no verb, parse_*, match_* + Value + question</description> + </item> + + <item> + <title>cowboy_req:binding(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.binding/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.binding/</guid> + <description>Name cowboy_req:binding - Access a value bound from the route + Description binding(Name, Req) -&gt; binding(Name, Req, undefined) binding(Name, Req, Default) -&gt; any() | Default Name :: atom() Req :: cowboy_req:req() Default :: any() Return the value for the given binding. + Arguments Name Desired binding name as an atom. Req The Req object. Default Default value returned when the binding is missing.</description> + </item> + + <item> + <title>cowboy_req:bindings(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.bindings/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.bindings/</guid> + <description>Name cowboy_req:bindings - Access all values bound from the route + Description bindings(Req :: cowboy_req:req()) -&gt; cowboy_router:bindings() Return a map containing all bindings. + Arguments Req The Req object. Return value By default values are case sensitive binary strings, however constraints may change the type of this value (for example automatically converting numbers to integer). + Changelog 2.</description> + </item> + + <item> + <title>cowboy_req:body_length(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.body_length/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.body_length/</guid> + <description>Name cowboy_req:body_length - Body length + Description body_length(Req :: cowboy_req:req()) -&gt; undefined | non_neg_integer() Return the length of the request body. + The length is not always known before reading the body. In those cases Cowboy will return undefined. The body length is available after the body has been fully read. + Arguments Req The Req object. Return value The length of the request body, or undefined if it is not known.</description> + </item> + + <item> + <title>cowboy_req:delete_resp_header(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.delete_resp_header/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.delete_resp_header/</guid> + <description>Name cowboy_req:delete_resp_header - Delete a response header + Description delete_resp_header(Name, Req :: cowboy_req:req()) -&gt; Req Name :: binary() %% lowercase; case insensitive Delete the given response header. + The header name must be given as a lowercase binary string. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly. + Arguments Name Header name as a lowercase binary string.</description> + </item> + + <item> + <title>cowboy_req:has_body(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.has_body/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.has_body/</guid> + <description>Name cowboy_req:has_body - Is there a request body? + Description has_body(Req :: cowboy_req:req()) -&gt; boolean() Return whether the request has a body. + Arguments Req The Req object. Return value A boolean indicating whether the request has a body. + Changelog 1.0: Function introduced. Examples Ensure the request has a body true = cowboy_req:has_body(Req).</description> + </item> + + <item> + <title>cowboy_req:has_resp_body(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.has_resp_body/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.has_resp_body/</guid> + <description>Name cowboy_req:has_resp_body - Is there a response body? + Description has_resp_body(Req :: cowboy_req:req()) -&gt; boolean() Return whether a response body has been set. + Arguments Req The Req object. Return value A boolean indicating whether a response body has been set. + This function will return false when an empty response body has been set. + Changelog 1.</description> + </item> + + <item> + <title>cowboy_req:has_resp_header(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.has_resp_header/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.has_resp_header/</guid> + <description>Name cowboy_req:has_resp_header - Is the given response header set? + Description has_resp_header(Name, Req :: cowboy_req:req()) -&gt; boolean() Name :: binary() %% lowercase; case insensitive Return whether the given response header has been set. + The header name must be given as a lowercase binary string. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly. + Arguments Name Header name as a lowercase binary string.</description> + </item> + + <item> + <title>cowboy_req:header(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.header/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.header/</guid> + <description>Name cowboy_req:header - HTTP header + Description header(Name, Req) -&gt; header(Name, Req, undefined) header(Name, Req, Default) -&gt; binary() | Default Name :: binary() %% lowercase; case insensitive Req :: cowboy_req:req() Default :: any() Return the value for the given HTTP header. + The header name must be given as a lowercase binary string. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly.</description> + </item> + + <item> + <title>cowboy_req:headers(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.headers/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.headers/</guid> + <description>Name cowboy_req:headers - HTTP headers + Description headers(Req :: cowboy_req:req()) -&gt; cowboy:http_headers() Return all request headers. + Request headers can also be obtained using pattern matching: + #{headers := Headers} = Req. Arguments Req The Req object. Return value Headers are returned as a map with keys being lowercase binary strings, and values as binary strings. + Changelog 2.</description> + </item> + + <item> + <title>cowboy_req:host(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.host/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.host/</guid> + <description>Name cowboy_req:host - URI host name + Description host(Req :: cowboy_req:req()) -&gt; Host :: binary() Return the host name of the effective request URI. + The host name can also be obtained using pattern matching: + #{host := Host} = Req. Arguments Req The Req object. Return value The host name is returned as a lowercase binary string. It is case insensitive.</description> + </item> + + <item> + <title>cowboy_req:host_info(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.host_info/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.host_info/</guid> + <description>Name cowboy_req:host_info - Access the route&#8217;s heading host segments + Description host_info(Req :: cowboy_req:req()) -&gt; cowboy_router:tokens() Return the tokens for the heading host segments. + This is the part of the host name that was matched using the ... notation. + Arguments Req The Req object. Return value The tokens are returned as a list of case insensitive binary strings.</description> + </item> + + <item> + <title>cowboy_req:match_cookies(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.match_cookies/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.match_cookies/</guid> + <description>Name cowboy_req:match_cookies - Match cookies against constraints + Description match_cookies(Fields :: cowboy:fields(), Req :: cowboy_req:req()) -&gt; #{atom() =&gt; any()} Parse the cookies and match specific values against constraints. + Cowboy will only return the cookie values specified in the fields list, and ignore all others. Fields can be either the name of the cookie requested; the name along with a list of constraints; or the name, a list of constraints and a default value in case the cookie is missing.</description> + </item> + + <item> + <title>cowboy_req:match_qs(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.match_qs/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.match_qs/</guid> + <description>Name cowboy_req:match_qs - Match the query string against constraints + Description match_qs(Fields :: cowboy:fields(), Req :: cowboy_req:req()) -&gt; #{atom() =&gt; any()} Parse the query string and match specific values against constraints. + Cowboy will only return the query string values specified in the fields list, and ignore all others. Fields can be either the key requested; the key along with a list of constraints; or the key, a list of constraints and a default value in case the key is missing.</description> + </item> + + <item> + <title>cowboy_req:method(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.method/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.method/</guid> + <description>Name cowboy_req:method - HTTP method + Description method(Req :: cowboy_req:req()) -&gt; Method :: binary() Return the request&#8217;s HTTP method. + The method can also be obtained using pattern matching: + #{method := Method} = Req. Arguments Req The Req object. Return value The request&#8217;s HTTP method is returned as a binary string. While methods are case sensitive, standard methods are always uppercase.</description> + </item> + + <item> + <title>cowboy_req:parse_cookies(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.parse_cookies/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.parse_cookies/</guid> + <description>Name cowboy_req:parse_cookies - Parse cookie headers + Description parse_cookies(Req) -&gt; [{Name, Value}] Name :: binary() %% case sensitive Value :: binary() %% case sensitive Parse cookie headers. + Alias for cowboy_req:parse_header([cookie], Req). + When the cookie header is missing, [] is returned. + While an empty cookie header is not valid, some clients do send it. Cowboy will in this case also return []. + Arguments Req The Req object.</description> + </item> + + <item> + <title>cowboy_req:parse_header(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.parse_header/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.parse_header/</guid> + <description>Name cowboy_req:parse_header - Parse the given HTTP header + Description parse_header(Name, Req) -&gt; ParsedValue | Default parse_header(Name, Req, Default) -&gt; ParsedValue | Default Name :: binary() Req :: cowboy_req:req() ParsedValue :: any() Default :: any() Parse the given HTTP header. + The header name must be given as a lowercase binary string. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly.</description> + </item> + + <item> + <title>cowboy_req:parse_qs(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.parse_qs/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.parse_qs/</guid> + <description>Name cowboy_req:parse_qs - Parse the query string + Description parse_qs(Req :: cowboy_req:req()) -&gt; [{Key :: binary(), Value :: binary() | true}] Parse the query string as a list of key/value pairs. + Arguments Req The Req object. Return value The parsed query string is returned as a list of key/value pairs. The key is a binary string. The value is either a binary string, or the atom true.</description> + </item> + + <item> + <title>cowboy_req:path(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.path/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.path/</guid> + <description>Name cowboy_req:path - URI path + Description path(Req :: cowboy_req:req()) -&gt; Path :: binary() Return the path of the effective request URI. + The path can also be obtained using pattern matching: + #{path := Path} = Req. Arguments Req The Req object. Return value The path is returned as a binary string. It is case sensitive. + Changelog 2.</description> + </item> + + <item> + <title>cowboy_req:path_info(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.path_info/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.path_info/</guid> + <description>Name cowboy_req:path_info - Access the route&#8217;s trailing path segments + Description path_info(Req :: cowboy_req:req()) -&gt; cowboy_router:tokens() Return the tokens for the trailing path segments. + This is the part of the host name that was matched using the ... notation. + Arguments Req The Req object. Return value The tokens are returned as a list of case sensitive binary strings.</description> + </item> + + <item> + <title>cowboy_req:peer(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.peer/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.peer/</guid> + <description>Name cowboy_req:peer - Peer address and port + Description peer(Req :: cowboy_req:req()) -&gt; Peer Peer :: {inet:ip_address(), inet:port_number()} Return the peer&#8217;s IP address and port number. + The peer can also be obtained using pattern matching: + #{peer := {IP, Port}} = Req. Arguments Req The Req object. Return value The peer&#8217;s IP address and port number. + The peer is not necessarily the client&#8217;s IP address and port.</description> + </item> + + <item> + <title>cowboy_req:port(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.port/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.port/</guid> + <description>Name cowboy_req:port - URI port number + Description port(Req :: cowboy_req:req()) -&gt; Port :: inet:port_number() Return the port number of the effective request URI. + Note that the port number returned by this function is obtained by parsing the host header. It may be different from the port the peer used to connect to Cowboy. + The port number can also be obtained using pattern matching: + #{port := Port} = Req.</description> + </item> + + <item> + <title>cowboy_req:push(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.push/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.push/</guid> + <description>Name cowboy_req:push - Push a resource to the client + Description push(Path, Headers, Req :: cowboy_req:req()) -&gt; push(Path, Headers, Req, #{}) push(Path, Headers, Req :: cowboy_req:req(), Opts) -&gt; ok Path :: iodata() %% case sensitive Headers :: cowboy:http_headers() Opts :: cowboy_req:push_opts() Push a resource to the client. + Cowboy handles push requests the same way as if they came from the client, including the creation of a request handling process, routing and middlewares and so on.</description> + </item> + + <item> + <title>cowboy_req:qs(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.qs/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.qs/</guid> + <description>Name cowboy_req:qs - URI query string + Description qs(Req :: cowboy_req:req()) -&gt; Qs :: binary() Return the query string of the effective request URI. + The query string can also be obtained using pattern matching: + #{qs := Qs} = Req. Arguments Req The Req object. Return value The query string is returned as a binary string. It is case sensitive.</description> + </item> + + <item> + <title>cowboy_req:read_body(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.read_body/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.read_body/</guid> + <description>Name cowboy_req:read_body - Read the request body + Description read_body(Req :: cowboy_req:req()) -&gt; read_body(Req, #{}) read_body(Req :: cowboy_req:req(), Opts) -&gt; {ok, Data :: binary(), Req} | {more, Data :: binary(), Req} Opts :: cowboy_req:read_body_opts() Read the request body. + This function reads a chunk of the request body. A more tuple is returned when more data remains to be read. Call the function repeatedly until an ok tuple is returned to read the entire body.</description> + </item> + + <item> + <title>cowboy_req:read_part(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.read_part/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.read_part/</guid> + <description>Name cowboy_req:read_part - Read the next multipart headers + Description read_part(Req :: cowboy_req:req()) -&gt; read_part(Req, #{}) read_part(Req :: cowboy_req:req(), Opts) -&gt; {ok, Headers, Req} | {done, Req} Opts :: cowboy_req:read_body_opts() Headers :: #{binary() =&gt; binary()} Read the next part of a multipart body. + This function reads the request body and parses it as multipart. Each parts of a multipart representation have their own headers and body. This function parses and returns headers.</description> + </item> + + <item> + <title>cowboy_req:read_part_body(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.read_part_body/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.read_part_body/</guid> + <description>Name cowboy_req:read_part_body - Read the current part&#8217;s body + Description read_part_body(Req :: cowboy_req:req()) -&gt; read_part_body(Req, #{}) read_part_body(Req :: cowboy_req:req(), Opts) -&gt; {ok, Data :: binary(), Req} | {more, Data :: binary(), Req} Opts :: cowboy_req:read_body_opts() Read the body of the current part of the multipart message. + This function reads the request body and parses it as multipart. Each parts of a multipart representation have their own headers and body.</description> + </item> + + <item> + <title>cowboy_req:read_urlencoded_body(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.read_urlencoded_body/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.read_urlencoded_body/</guid> + <description>Name cowboy_req:read_urlencoded_body - Read and parse a urlencoded request body + Description read_urlencoded_body(Req :: cowboy_req:req()) -&gt; read_urlencoded_body(Req, #{}) read_urlencoded_body(Req :: cowboy_req:req(), Opts) -&gt; {ok, Body, Req} Opts :: cowboy_req:read_body_opts() Body :: [{Key :: binary(), Value :: binary() | true}] Read and parse a urlencoded request body. + This function reads the request body and parses it as application/x-www-form-urlencoded. It returns a list of key/values. + The urlencoded media type is used by Web browsers when submitting HTML forms using the POST method.</description> + </item> + + <item> + <title>cowboy_req:reply(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.reply/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.reply/</guid> + <description>Name cowboy_req:reply - Send the response + Description reply(Status, Req :: cowboy_req:req()) -&gt; reply(StatusCode, #{}, Req) reply(Status, Headers, Req :: cowboy_req:req()) -&gt; Req reply(Status, Headers, Body, Req :: cowboy_req:req()) -&gt; Req Status :: cowboy:http_status() Headers :: cowboy:http_headers() Body :: cowboy_req:resp_body() Send the response. + The header names must be given as lowercase binary strings. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly.</description> + </item> + + <item> + <title>cowboy_req:resp_header(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.resp_header/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.resp_header/</guid> + <description>Name cowboy_req:resp_header - Response header + Description resp_header(Name, Req) -&gt; resp_header(Name, Req, undefined) resp_header(Name, Req, Default) -&gt; binary() | Default Name :: binary() %% lowercase; case insensitive Req :: cowboy_req:req() Default :: any() Return the value for the given response header. + The response header must have been set previously using cowboy_req:set_resp_header(3) or cowboy_req:set_resp_headers(3). + The header name must be given as a lowercase binary string. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly.</description> + </item> + + <item> + <title>cowboy_req:resp_headers(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.resp_headers/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.resp_headers/</guid> + <description>Name cowboy_req:resp_headers - Response headers + Description resp_headers(Req :: cowboy_req:req()) -&gt; cowboy:http_headers() Return all response headers. + Arguments Req The Req object. Return value Headers are returned as a map with keys being lowercase binary strings, and values as binary strings. + Changelog 2.0: Function introduced. Examples Get all response headers Headers = cowboy_req:resp_headers(Req).</description> + </item> + + <item> + <title>cowboy_req:scheme(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.scheme/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.scheme/</guid> + <description>Name cowboy_req:scheme - URI scheme + Description scheme(Req :: cowboy_req:req()) -&gt; Scheme :: binary() Return the scheme of the effective request URI. + The scheme can also be obtained using pattern matching: + #{scheme := Scheme} = Req. Arguments Req The Req object. Return value The scheme is returned as a binary. It is case insensitive. + Cowboy will only set the scheme to &lt;&lt;"</description> + </item> + + <item> + <title>cowboy_req:set_resp_body(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_body/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_body/</guid> + <description>Name cowboy_req:set_resp_body - Set the response body + Description set_resp_body(Body, Req :: cowboy_req:req()) -&gt; Req Body :: cowboy_req:resp_body() Set the response body. + The response body will be sent when a reply is initiated. Note that the functions stream_reply/2,3 and reply/4 will override the body set by this function. + This function can also be used to remove a response body that was set previously. To do so, simply call this function with an empty body.</description> + </item> + + <item> + <title>cowboy_req:set_resp_cookie(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_cookie/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_cookie/</guid> + <description>Name cowboy_req:set_resp_cookie - Set a cookie + Description set_resp_cookie(Name, Value, Req :: cowboy_req:req()) -&gt; set_resp_cookie(Name, Value, [], Req) set_resp_cookie(Name, Value, Req :: cowboy_req:req(), Opts) -&gt; Req Name :: binary() %% case sensitive Value :: iodata() %% case sensitive Opts :: cow_cookie:cookie_opts() Set a cookie to be sent with the response. + Note that cookie names are case sensitive. + Arguments Name Cookie name.</description> + </item> + + <item> + <title>cowboy_req:set_resp_header(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_header/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_header/</guid> + <description>Name cowboy_req:set_resp_header - Set a response header + Description set_resp_header(Name, Value, Req :: cowboy_req:req()) -&gt; Req Name :: binary() %% lowercase; case insensitive Value :: iodata() %% case depends on header Set a header to be sent with the response. + The header name must be given as a lowercase binary string. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly.</description> + </item> + + <item> + <title>cowboy_req:set_resp_headers(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_headers/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_headers/</guid> + <description>Name cowboy_req:set_resp_headers - Set several response headers + Description set_resp_headers(Headers, Req :: cowboy_req:req()) -&gt; Req Headers :: cowboy:http_headers() Set several headers to be sent with the response. + The header name must be given as a lowercase binary string. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly. + Cowboy does not allow duplicate header names. Headers set by this function may be overwritten by those set from the reply functions.</description> + </item> + + <item> + <title>cowboy_req:stream_body(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.stream_body/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.stream_body/</guid> + <description>Name cowboy_req:stream_body - Stream the response body + Description stream_body(Data, IsFin, Req :: cowboy_req:req()) -&gt; ok Data :: iodata() IsFin :: fin | nofin Stream the response body. + This function may be called as many times as needed after initiating a response using the cowboy_req:stream_reply(3) function. + The second argument indicates if this call is the final call. Use the nofin value until you know no more data will be sent.</description> + </item> + + <item> + <title>cowboy_req:stream_reply(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.stream_reply/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.stream_reply/</guid> + <description>Name cowboy_req:stream_reply - Send the response headers + Description stream_reply(Status, Req :: cowboy_req:req()) -&gt; stream_reply(StatusCode, #{}, Req) stream_reply(Status, Headers, Req :: cowboy_req:req()) -&gt; Req Status :: cowboy:http_status() Headers :: cowboy:http_headers() Send the response headers. + The header names must be given as lowercase binary strings. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly. + Cowboy does not allow duplicate header names.</description> + </item> + + <item> + <title>cowboy_req:uri(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.uri/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.uri/</guid> + <description>Name cowboy_req:uri - Reconstructed URI + Description uri(Req :: cowboy_req:req()) -&gt; uri(Req, #{}) uri(Req :: cowboy_req:req(), Opts) -&gt; URI :: iodata() Opts :: #{ scheme =&gt; iodata() | undefined, host =&gt; iodata() | undefined, port =&gt; inet:port_number() | undefined, path =&gt; iodata() | undefined, qs =&gt; iodata() | undefined, fragment =&gt; iodata() | undefined } Reconstruct the effective request URI, optionally modifying components. + By default Cowboy will build a URI using the components found in the request.</description> + </item> + + <item> + <title>cowboy_req:version(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.version/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.version/</guid> + <description>Name cowboy_req:version - HTTP version + Description version(Req :: cowboy_req:req()) -&gt; Version :: cowboy:http_version() Return the HTTP version used for the request. + The version can also be obtained using pattern matching: + #{version := Version} = Req. Arguments Req The Req object. Return value The HTTP version used for the request is returned as an atom. It is provided for informative purposes only.</description> + </item> + + <item> + <title>cowboy_rest(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_rest/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_rest/</guid> + <description>Name cowboy_rest - REST handlers + Description The module cowboy_rest implements the HTTP state machine. + Implementing REST handlers is not enough to provide a REST interface; this interface must also follow the REST constraints including HATEOAS (hypermedia as the engine of application state). + Callbacks REST handlers implement the following interface: + init(Req, State) -&gt; {cowboy_rest, Req, State} Callback(Req, State) -&gt; {Result, Req, State} | {stop, Req, State} terminate(Reason, Req, State) -&gt; ok %% optional Req :: cowboy_req:req() State :: any() Reason :: normal | {crash, error | exit | throw, any()} Callback - see below Result - see below Default - see below The init/2 callback is common to all handlers.</description> + </item> + + <item> + <title>cowboy_router(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_router/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_router/</guid> + <description>Name cowboy_router - Router middleware + Description The cowboy_router middleware maps the requested host and path to the handler to be used for processing the request. + The router takes the dispatch rules as input from the middleware environment. Dispatch rules are generated by calling the cowboy_router:compile(3) function. + When a route matches, the router sets the handler and handler_opts middleware environment values containing the handler module and initial state, respectively.</description> + </item> + + <item> + <title>cowboy_router:compile(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_router.compile/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_router.compile/</guid> + <description>Name cowboy_router:compile - Compile routes to the resources + Description compile(cowboy_router:routes()) -&gt; cowboy_router:dispatch_rules() Compile routes to the resources. + Takes a human readable list of routes and transforms it into a form more efficient to process. + Arguments Routes Human readable list of routes. Return value An opaque dispatch rules value is returned. This value must be given to Cowboy as a middleware environment value.</description> + </item> + + <item> + <title>cowboy_static(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_static/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_static/</guid> + <description>Name cowboy_static - Static file handler + Description The module cowboy_static implements file serving capabilities using the REST semantics provided by cowboy_rest. + The static file handler is a pre-written handler coming with Cowboy. To serve files, use it in your routes. + Options opts() :: {priv_file, App, Path} | {priv_file, App, Path, Extra} | {file, Path} | {file, Path, Extra} | {priv_dir, App, Path} | {priv_dir, App, Path, Extra} | {dir, Path} | {dir, Path, Extra} App :: atom() Path :: binary() | string() Extra :: [Etag | Mimetypes] Etag :: {etag, module(), function()} | {etag, false} Mimetypes :: {mimetypes, module(), function()} | {mimetypes, binary() | ParsedMime} ParsedMime :: {Type :: binary(), SubType :: binary(), Params} Params :: [{Key :: binary(), Value :: binary()}] Static handler configuration.</description> + </item> + + <item> + <title>cowboy_stream(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_stream/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_stream/</guid> + <description>Name cowboy_handler - Stream handlers + Description The module cowboy_stream defines a callback interface and a protocol for handling HTTP streams. + An HTTP request and its associated response is called a stream. A connection may have many streams. In HTTP/1.1 they are executed sequentially, while in HTTP/2 they are executed concurrently. + Cowboy calls the stream handler for nearly all events related to a stream. Exceptions vary depending on the protocol.</description> + </item> + + <item> + <title>cowboy_websocket(3)</title> + <link>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_websocket/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_websocket/</guid> + <description>Name cowboy_websocket - Websocket + Description The module cowboy_websocket implements Websocket as a Ranch protocol. It also defines a callback interface for handling Websocket connections. + Callbacks Websocket handlers must implement the following callback interface: + init(Req, State) -&gt; {cowboy_websocket, Req, State} | {cowboy_websocket, Req, State, Opts} websocket_init(State) -&gt; CallResult %% optional websocket_handle(InFrame, State) -&gt; CallResult websocket_info(Info, State) -&gt; CallResult terminate(Reason, PartialReq, State) -&gt; ok %% optional Req :: cowboy_req:req() PartialReq :: map() State :: any() Opts :: cowboy_websocket:opts() InFrame :: {text | binary | ping | pong, binary()} OutFrame :: cow_ws:frame() %% see types below Info :: any() CallResult :: {ok, State} | {ok, State, hibernate} | {reply, OutFrame | [OutFrame], State} | {reply, OutFrame | [OutFrame], State, hibernate} | {stop, State} Reason :: normal | stop | timeout | remote | {remote, cow_ws:close_code(), binary()} | {error, badencoding | badframe | closed | atom()} | {crash, error | exit | throw, any()} The init/2 callback is common to all handlers.</description> + </item> + + <item> + <title>gun(3)</title> + <link>https://ninenines.eu/docs/en/gun/1.0/manual/gun/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/gun/1.0/manual/gun/</guid> + <description>Name gun - asynchronous HTTP client + Description The gun module provides an asynchronous interface for connecting and communicating with Web servers over HTTP, HTTP/2 or Websocket. + Types opts() = map() Configuration for the connection. + The following keys are defined: + connect_timeout &#8658; timeout() Connection timeout. Defaults to infinity. http_opts &#8658; http_opts() Options specific to the HTTP protocol.</description> + </item> + + <item> + <title>gun(7)</title> + <link>https://ninenines.eu/docs/en/gun/1.0/manual/gun_app/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/gun/1.0/manual/gun_app/</guid> + <description>Name gun - Erlang HTTP client with support for HTTP/1.1, HTTP/2 and Websocket. + Dependencies The gun application uses the Erlang applications ranch for abstracting TCP and TLS over a common interface, and the ssl application for TLS support, required for HTTPS and secure HTTP/2 support. In addition, Gun requires the crypto application (a dependency of ssl) for Websocket. + These dependencies must be started for the gun application to work.</description> + </item> + + <item> + <title>ranch(3)</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch/</guid> + <description>Name ranch - socket acceptor pool + Description The ranch module provides functions for starting and manipulating Ranch listeners. + Types max_conns() = non_neg_integer() | infinity Maximum number of connections allowed on this listener. + This is a soft limit. The actual number of connections might be slightly above the limit due to concurrency when accepting new connections. Some connections may also be removed from this count explicitly by the user code.</description> + </item> + + <item> + <title>ranch(3)</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch/</guid> + <description>Name ranch - socket acceptor pool + Description The ranch module provides functions for starting and manipulating Ranch listeners. + Types max_conns() = non_neg_integer() | infinity Maximum number of connections allowed on this listener. + This is a soft limit. The actual number of connections might be slightly above the limit due to concurrency when accepting new connections. Some connections may also be removed from this count explicitly by the user code.</description> + </item> + + <item> + <title>ranch(7)</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_app/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_app/</guid> + <description>Name ranch - Socket acceptor pool for TCP protocols. + Dependencies The ranch application has no particular dependency required to start. + It has optional dependencies that are only required when listening for SSL connections. The dependencies are crypto, asn1, public_key and ssl. They are started automatically if they weren&#8217;t before. + Environment The ranch application defines one application environment configuration parameter. + profile (false) When enabled, Ranch will start eprof profiling automatically.</description> + </item> + + <item> + <title>ranch(7)</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_app/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_app/</guid> + <description>Name ranch - Socket acceptor pool for TCP protocols. + Dependencies The ranch application depends on the ssl application to start. It is used for handling secure connections, when the transport is ranch_ssl. It can be disabled if SSL is not used. + Environment The ranch application defines one application environment configuration parameter. + profile (false) When enabled, Ranch will start eprof profiling automatically.</description> + </item> + + <item> + <title>ranch_protocol(3)</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_protocol/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_protocol/</guid> + <description>Name ranch_protocol - behaviour for protocol modules + Description The ranch_protocol behaviour defines the interface used by Ranch protocols. + Types None. + Callbacks start_link(Ref, Socket, Transport, ProtoOpts) &#8594; {ok, pid()} | {ok, pid(), pid()} Ref = ranch:ref() Listener name. Socket = any() Socket for this connection. Transport = module() Transport module for this socket.</description> + </item> + + <item> + <title>ranch_protocol(3)</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_protocol/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_protocol/</guid> + <description>Name ranch_protocol - behaviour for protocol modules + Description The ranch_protocol behaviour defines the interface used by Ranch protocols. + Types None. + Callbacks start_link(Ref, Socket, Transport, ProtoOpts) &#8594; {ok, pid()} | {ok, pid(), pid()} Ref = ranch:ref() Listener name. Socket = any() Socket for this connection. Transport = module() Transport module for this socket.</description> + </item> + + <item> + <title>ranch_ssl(3)</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_ssl/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_ssl/</guid> + <description>Name ranch_ssl - SSL transport module + Description The ranch_ssl module implements an SSL Ranch transport. + Types ssl_opt() ssl_opt() = {alpn_preferred_protocols, [binary()]} | {cacertfile, string()} | {cacerts, [public_key:der_encoded()]} | {cert, public_key:der_encoded()} | {certfile, string()} | {ciphers, [ssl:erl_cipher_suite()] | string()} | {client_renegotiation, boolean()} | {crl_cache, {module(), {internal | any(), list()}}} | {crl_check, boolean() | peer | best_effort} | {depth, 0..255} | {dh, public_key:der_encoded()} | {dhfile, string()} | {fail_if_no_peer_cert, boolean()} | {hibernate_after, integer() | undefined} | {honor_cipher_order, boolean()} | {key, {'RSAPrivateKey' | 'DSAPrivateKey' | 'PrivateKeyInfo', public_key:der_encoded()}} | {keyfile, string()} | {log_alert, boolean()} | {next_protocols_advertised, [binary()]} | {partial_chain, fun(([public_key:der_encoded()]) -&gt; {trusted_ca, public_key:der_encoded()} | unknown_ca)} | {password, string()} | {psk_identity, string()} | {reuse_session, fun()} | {reuse_sessions, boolean()} | {secure_renegotiate, boolean()} | {sni_fun, fun()} | {sni_hosts, [{string(), ssl_opt()}]} | {user_lookup_fun, {fun(), any()}} | {verify, ssl:verify_type()} | {verify_fun, {fun(), any()}} | {versions, [atom()]}.</description> + </item> + + <item> + <title>ranch_ssl(3)</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_ssl/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_ssl/</guid> + <description>Name ranch_ssl - SSL transport module + Description The ranch_ssl module implements an SSL Ranch transport. + Types ssl_opt() ssl_opt() = {alpn_preferred_protocols, [binary()]} | {beast_mitigation, one_n_minus_one | zero_n | disabled} | {cacertfile, string()} | {cacerts, [public_key:der_encoded()]} | {cert, public_key:der_encoded()} | {certfile, string()} | {ciphers, [ssl:erl_cipher_suite()] | string()} | {client_renegotiation, boolean()} | {crl_cache, {module(), {internal | any(), list()}}} | {crl_check, boolean() | peer | best_effort} | {depth, 0.</description> + </item> + + <item> + <title>ranch_tcp(3)</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_tcp/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_tcp/</guid> + <description>Name ranch_tcp - TCP transport module + Description The ranch_tcp module implements a TCP Ranch transport. + Note that due to bugs in OTP up to at least R16B02, it is recommended to disable async threads when using the sendfile function of this transport, as it can make the threads stuck indefinitely. + Types opt() opt() = {backlog, non_neg_integer()} | {buffer, non_neg_integer()} | {delay_send, boolean()} | {dontroute, boolean()} | {exit_on_close, boolean()} | {fd, non_neg_integer()} | {high_msgq_watermark, non_neg_integer()} | {high_watermark, non_neg_integer()} | inet | inet6 | {ip, inet:ip_address()} | {keepalive, boolean()} | {linger, {boolean(), non_neg_integer()}} | {low_msgq_watermark, non_neg_integer()} | {low_watermark, non_neg_integer()} | {nodelay, boolean()} | {port, inet:port_number()} | {priority, integer()} | {raw, non_neg_integer(), non_neg_integer(), binary()} | {recbuf, non_neg_integer()} | {send_timeout, timeout()} | {send_timeout_close, boolean()} | {sndbuf, non_neg_integer()} | {tos, integer()} Listen options.</description> + </item> + + <item> + <title>ranch_tcp(3)</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_tcp/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_tcp/</guid> + <description>Name ranch_tcp - TCP transport module + Description The ranch_tcp module implements a TCP Ranch transport. + Note that due to bugs in OTP up to at least R16B02, it is recommended to disable async threads when using the sendfile function of this transport, as it can make the threads stuck indefinitely. + Types opt() opt() = {backlog, non_neg_integer()} | {buffer, non_neg_integer()} | {delay_send, boolean()} | {dontroute, boolean()} | {exit_on_close, boolean()} | {fd, non_neg_integer()} | {high_msgq_watermark, non_neg_integer()} | {high_watermark, non_neg_integer()} | inet | inet6 | {ip, inet:ip_address()} | {ipv6_v6only, boolean()} | {keepalive, boolean()} | {linger, {boolean(), non_neg_integer()}} | {low_msgq_watermark, non_neg_integer()} | {low_watermark, non_neg_integer()} | {nodelay, boolean()} | {port, inet:port_number()} | {priority, integer()} | {raw, non_neg_integer(), non_neg_integer(), binary()} | {recbuf, non_neg_integer()} | {send_timeout, timeout()} | {send_timeout_close, boolean()} | {sndbuf, non_neg_integer()} | {tos, integer()} Listen options.</description> + </item> + + <item> + <title>ranch_transport(3)</title> + <link>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_transport/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_transport/</guid> + <description>Name ranch_transport - behaviour for transport modules + Description The ranch_transport behaviour defines the interface used by Ranch transports. + Types sendfile_opts() = [{chunk_size, non_neg_integer()}] Options used by the sendfile function and callbacks. + Allows configuring the chunk size, in bytes. Defaults to 8191 bytes. + Callbacks accept(LSocket, Timeout) &#8594; {ok, CSocket} | {error, closed | timeout | atom()} LSocket = CSocket = any() Listening socket.</description> + </item> + + <item> + <title>ranch_transport(3)</title> + <link>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_transport/</link> + <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate> + + <guid>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_transport/</guid> + <description>Name ranch_transport - behaviour for transport modules + Description The ranch_transport behaviour defines the interface used by Ranch transports. + Types sendfile_opts() = [{chunk_size, non_neg_integer()}] Options used by the sendfile function and callbacks. + Allows configuring the chunk size, in bytes. Defaults to 8191 bytes. + Callbacks accept(LSocket, Timeout) &#8594; {ok, CSocket} | {error, closed | timeout | atom()} LSocket = CSocket = any() Listening socket.</description> </item> </channel> diff --git a/services/index.html b/services/index.html index 8b39d01a..15cfc232 100644 --- a/services/index.html +++ b/services/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Consulting & Training</title> @@ -67,107 +67,107 @@ <h1 class="lined-header"><span>Services</span></h1> -<div class="paragraph"><p>If you are interested by any of these opportunities,
-<a href="mailto:[email protected]">send me an email</a>.</p></div>
-<div class="sect1">
-<h2 id="_consulting">Consulting</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can get me, Loïc Hoguin, author of Cowboy, to help you
-solve a problem or work on a particular project.</p></div>
-<div class="paragraph"><p>My area of expertise is Erlang; HTTP, Websocket and REST APIs;
-design and implementation of protocols; and messaging systems.</p></div>
-<div class="paragraph"><p>I can also be helpful with testing or code reviews.</p></div>
-<div class="paragraph"><p>I offer both hourly and daily rates:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-200€ hourly rate (remote)
-</p>
-</li>
-<li>
-<p>
-1000€ daily rate (remote and on-site)
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>For remote consulting, the work can be done by phone, email,
-IRC, GitHub and/or any other platform for collaborative work.</p></div>
-<div class="paragraph"><p>For on-site consulting, the travel expenses and
-accomodations are to be paid by the customer. I will also
-ask for a higher rate if forced to stay on-site for more
-than a week.</p></div>
-<div class="paragraph"><p>Note that my expertise does not cover all areas where
-Erlang is used. My help will be limited in the areas of
-distributed databases, or large distributed systems.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_sponsoring">Sponsoring</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can sponsor one of my projects.</p></div>
-<div class="paragraph"><p>Sponsoring gives you:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-a direct, private line of communication
-</p>
-</li>
-<li>
-<p>
-the power to make me maintain older versions of my projects
- (as long as they are sponsoring)
-</p>
-</li>
-<li>
-<p>
-priority when adding features or fixing bugs
-</p>
-</li>
-<li>
-<p>
-advertisement space on this website and in the README file
- of the project of your choice
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>Sponsors may choose to benefit from any of these perks.</p></div>
-<div class="paragraph"><p>In exchange sponsors must contribute financially. A minimum
-of 200€ per month is required. Sponsors may give as much as
-they want. Payment can be monthly or one-time. Invoices are
-of course provided.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_erlang_beginner_training">Erlang beginner training</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>I would be happy to introduce more people to Erlang. I have
-a 1-day Erlang training readily available for consumption.
-The goal of this training is to teach the basics of Erlang
-systems and programming. It’s a kind of "Getting started"
-for Erlang.</p></div>
-<div class="paragraph"><p>You can review the <a href="/talks/thinking-in-erlang/thinking-in-erlang.html">training slides</a>.</p></div>
-<div class="paragraph"><p>This training is meant to be given to a large number of
-people interested in Erlang, as part of a public event,
-where anyone interested can come.</p></div>
-<div class="paragraph"><p>Another important aspect of this training is that it is
-meant to be affordable. We want the most people to learn
-Erlang as possible.</p></div>
-<div class="paragraph"><p>If you have room, think you can gather 20+ people and
-are interested in sponsoring a training session, then
-we should talk.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_custom_training">Custom training</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>I can also provide custom training, tailored to your level
-and your needs. It can take the form of a class, Q&A or a
-code review/writing session. I need to know your expectations
-to prepare an appropriate training.</p></div>
-<div class="paragraph"><p>Custom training rates are the same as consulting rates and
-the same restrictions apply.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>If you are interested by any of these opportunities, +<a href="mailto:[email protected]">send me an email</a>.</p></div> +<div class="sect1"> +<h2 id="_consulting">Consulting</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You can get me, Loïc Hoguin, author of Cowboy, to help you +solve a problem or work on a particular project.</p></div> +<div class="paragraph"><p>My area of expertise is Erlang; HTTP, Websocket and REST APIs; +design and implementation of protocols; and messaging systems.</p></div> +<div class="paragraph"><p>I can also be helpful with testing or code reviews.</p></div> +<div class="paragraph"><p>I offer both hourly and daily rates:</p></div> +<div class="ulist"><ul> +<li> +<p> +200€ hourly rate (remote) +</p> +</li> +<li> +<p> +1000€ daily rate (remote and on-site) +</p> +</li> +</ul></div> +<div class="paragraph"><p>For remote consulting, the work can be done by phone, email, +IRC, GitHub and/or any other platform for collaborative work.</p></div> +<div class="paragraph"><p>For on-site consulting, the travel expenses and +accomodations are to be paid by the customer. I will also +ask for a higher rate if forced to stay on-site for more +than a week.</p></div> +<div class="paragraph"><p>Note that my expertise does not cover all areas where +Erlang is used. My help will be limited in the areas of +distributed databases, or large distributed systems.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_sponsoring">Sponsoring</h2> +<div class="sectionbody"> +<div class="paragraph"><p>You can sponsor one of my projects.</p></div> +<div class="paragraph"><p>Sponsoring gives you:</p></div> +<div class="ulist"><ul> +<li> +<p> +a direct, private line of communication +</p> +</li> +<li> +<p> +the power to make me maintain older versions of my projects + (as long as they are sponsoring) +</p> +</li> +<li> +<p> +priority when adding features or fixing bugs +</p> +</li> +<li> +<p> +advertisement space on this website and in the README file + of the project of your choice +</p> +</li> +</ul></div> +<div class="paragraph"><p>Sponsors may choose to benefit from any of these perks.</p></div> +<div class="paragraph"><p>In exchange sponsors must contribute financially. A minimum +of 200€ per month is required. Sponsors may give as much as +they want. Payment can be monthly or one-time. Invoices are +of course provided.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_erlang_beginner_training">Erlang beginner training</h2> +<div class="sectionbody"> +<div class="paragraph"><p>I would be happy to introduce more people to Erlang. I have +a 1-day Erlang training readily available for consumption. +The goal of this training is to teach the basics of Erlang +systems and programming. It’s a kind of "Getting started" +for Erlang.</p></div> +<div class="paragraph"><p>You can review the <a href="/talks/thinking-in-erlang/thinking-in-erlang.html">training slides</a>.</p></div> +<div class="paragraph"><p>This training is meant to be given to a large number of +people interested in Erlang, as part of a public event, +where anyone interested can come.</p></div> +<div class="paragraph"><p>Another important aspect of this training is that it is +meant to be affordable. We want the most people to learn +Erlang as possible.</p></div> +<div class="paragraph"><p>If you have room, think you can gather 20+ people and +are interested in sponsoring a training session, then +we should talk.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_custom_training">Custom training</h2> +<div class="sectionbody"> +<div class="paragraph"><p>I can also provide custom training, tailored to your level +and your needs. It can take the form of a class, Q&A or a +code review/writing session. I need to know your expectations +to prepare an appropriate training.</p></div> +<div class="paragraph"><p>Custom training rates are the same as consulting rates and +the same restrictions apply.</p></div> +</div> +</div> </div> @@ -196,22 +196,6 @@ the same restrictions apply.</p></div> - <div class="sect2">
-<h3 id="_like_my_work_donate">Like my work? Donate!</h3>
-<div class="paragraph"><p>Donate to Loïc Hoguin because his work on Cowboy
-and Erlang.mk is fantastic:</p></div>
-<form action="https://www.paypal.com/cgi-bin/webscr" method="post" style="display:inline">
-<input type="hidden" name="cmd" value="_donations">
-<input type="hidden" name="business" value="[email protected]">
-<input type="hidden" name="lc" value="FR">
-<input type="hidden" name="item_name" value="Loic Hoguin">
-<input type="hidden" name="item_number" value="99s">
-<input type="hidden" name="currency_code" value="EUR">
-<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHosted">
-<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
-<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1">
-</form>
-</div>
@@ -362,6 +346,40 @@ and Erlang.mk is fantastic:</p></div> + <div class="sect2"> +<h3 id="_like_my_work_donate">Like my work? Donate!</h3> +<div class="paragraph"><p>Donate to Loïc Hoguin because his work on Cowboy +and Erlang.mk is fantastic:</p></div> +<form action="https://www.paypal.com/cgi-bin/webscr" method="post" style="display:inline"> +<input type="hidden" name="cmd" value="_donations"> +<input type="hidden" name="business" value="[email protected]"> +<input type="hidden" name="lc" value="FR"> +<input type="hidden" name="item_name" value="Loic Hoguin"> +<input type="hidden" name="item_number" value="99s"> +<input type="hidden" name="currency_code" value="EUR"> +<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHosted"> +<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!"> +<img alt="" border="0" src="https://www.paypalobjects.com/fr_FR/i/scr/pixel.gif" width="1" height="1"> +</form> +</div> + + + + + + + + + + + + + + + + + + diff --git a/sitemap.xml b/sitemap.xml index 7bb840da..e2d65ba5 100644 --- a/sitemap.xml +++ b/sitemap.xml @@ -1,783 +1,822 @@ <?xml version="1.0" encoding="utf-8" standalone="yes" ?> -<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"> +<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" + xmlns:xhtml="http://www.w3.org/1999/xhtml"> <url> - <loc>https://ninenines.eu/</loc> - <lastmod>2017-08-23T18:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/installation/</loc> </url> <url> - <loc>https://ninenines.eu/articles/cowboy-2.0.0-rc.2/</loc> - <lastmod>2017-08-23T18:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/gun/1.0/guide/introduction/</loc> </url> <url> - <loc>https://ninenines.eu/articles/cowboy-2.0.0-rc.1/</loc> - <lastmod>2017-07-24T18:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/ranch/1.2/guide/introduction/</loc> </url> <url> - <loc>https://ninenines.eu/articles/the-elephant-in-the-room/</loc> - <lastmod>2017-03-26T00:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/ranch/1.3/guide/introduction/</loc> </url> <url> - <loc>https://ninenines.eu/articles/dont-let-it-crash/</loc> - <lastmod>2017-01-22T00:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/modern_web/</loc> </url> <url> - <loc>https://ninenines.eu/articles/cowboy-2.0.0-pre.4/</loc> - <lastmod>2017-01-03T00:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/erlang_web/</loc> </url> <url> - <loc>https://ninenines.eu/articles/ranch-1.3/</loc> - <lastmod>2016-11-28T00:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/getting_started/</loc> </url> <url> - <loc>https://ninenines.eu/articles/ml-archives/</loc> - <lastmod>2016-08-29T00:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/ranch/1.2/guide/listeners/</loc> </url> <url> - <loc>https://ninenines.eu/articles/website-update/</loc> - <lastmod>2016-04-02T00:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/ranch/1.3/guide/listeners/</loc> </url> <url> - <loc>https://ninenines.eu/articles/erlanger-playbook-september-2015-update/</loc> - <lastmod>2015-09-02T00:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/gun/1.0/guide/start/</loc> </url> <url> - <loc>https://ninenines.eu/services/</loc> - <lastmod>2015-07-01T00:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/gun/1.0/guide/protocols/</loc> </url> <url> - <loc>https://ninenines.eu/docs/</loc> - <lastmod>2015-07-01T00:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/introduction/</loc> </url> <url> - <loc>https://ninenines.eu/donate/</loc> - <lastmod>2015-07-01T00:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/ranch/1.2/guide/transports/</loc> </url> <url> - <loc>https://ninenines.eu/talks/</loc> - <lastmod>2015-07-01T00:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/ranch/1.3/guide/transports/</loc> </url> <url> - <loc>https://ninenines.eu/slogan/</loc> - <lastmod>2015-07-01T00:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/overview/</loc> </url> <url> - <loc>https://ninenines.eu/articles/erlanger-playbook/</loc> - <lastmod>2015-06-18T00:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/gun/1.0/guide/connect/</loc> </url> <url> - <loc>https://ninenines.eu/articles/erlang-validate-utf8/</loc> - <lastmod>2015-03-06T00:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/ranch/1.2/guide/protocols/</loc> </url> <url> - <loc>https://ninenines.eu/articles/on-open-source/</loc> - <lastmod>2014-09-05T00:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/ranch/1.3/guide/protocols/</loc> </url> <url> - <loc>https://ninenines.eu/articles/the-story-so-far/</loc> - <lastmod>2014-08-23T00:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/getting_started/</loc> </url> <url> - <loc>https://ninenines.eu/articles/cowboy2-qs/</loc> - <lastmod>2014-08-20T00:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/updating/</loc> </url> <url> - <loc>https://ninenines.eu/articles/january-2014-status/</loc> - <lastmod>2014-01-07T00:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/gun/1.0/guide/http/</loc> </url> <url> - <loc>https://ninenines.eu/articles/farwest-funded/</loc> - <lastmod>2013-06-27T00:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/ranch/1.2/guide/embedded/</loc> </url> <url> - <loc>https://ninenines.eu/articles/erlang.mk-and-relx/</loc> - <lastmod>2013-05-28T00:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/ranch/1.3/guide/embedded/</loc> </url> <url> - <loc>https://ninenines.eu/articles/xerl-0.5-intermediate-module/</loc> - <lastmod>2013-03-25T00:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/limitations/</loc> </url> <url> - <loc>https://ninenines.eu/articles/xerl-0.4-expression-separator/</loc> - <lastmod>2013-03-01T00:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/flow_diagram/</loc> </url> <url> - <loc>https://ninenines.eu/articles/erlang-scalability/</loc> - <lastmod>2013-02-18T00:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/gun/1.0/guide/websocket/</loc> </url> <url> - <loc>https://ninenines.eu/articles/xerl-0.3-atomic-expressions/</loc> - <lastmod>2013-02-18T00:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/ranch/1.2/guide/parsers/</loc> </url> <url> - <loc>https://ninenines.eu/articles/xerl-0.2-two-modules/</loc> - <lastmod>2013-02-03T00:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/ranch/1.3/guide/parsers/</loc> </url> <url> - <loc>https://ninenines.eu/articles/xerl-0.1-empty-modules/</loc> - <lastmod>2013-01-30T00:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/app/</loc> </url> <url> - <loc>https://ninenines.eu/articles/ranch-ftp/</loc> - <lastmod>2012-11-14T00:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/listeners/</loc> </url> <url> - <loc>https://ninenines.eu/articles/tictactoe/</loc> - <lastmod>2012-10-17T00:00:00+01:00</lastmod> + <loc>https://ninenines.eu/docs/en/ranch/1.2/guide/ssl_auth/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/</loc> + <loc>https://ninenines.eu/docs/en/ranch/1.3/guide/ssl_auth/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/</loc> + <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/deps/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/routing/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/gun/1.0/manual/</loc> + <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/ports/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/gun/1.0/guide/</loc> + <loc>https://ninenines.eu/docs/en/ranch/1.2/guide/internals/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/http_status_codes/</loc> + <loc>https://ninenines.eu/docs/en/ranch/1.3/guide/internals/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.2/manual/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/constraints/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.3/manual/</loc> + <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/releases/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.2/guide/</loc> + <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/sfx/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.3/guide/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/handlers/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy/</loc> + <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/escripts/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_app/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/loop_handlers/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.set_env/</loc> + <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/kerl/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.start_clear/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/static_files/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.start_tls/</loc> + <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/compat/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.stop_listener/</loc> + <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/asciidoc/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_handler/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/req/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_handler.terminate/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/req_body/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_http/</loc> + <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/edoc/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_http2/</loc> + <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/shell/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_loop/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/resp/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_middleware/</loc> + <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/eunit/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/cookies/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.binding/</loc> + <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/common_test/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.bindings/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/multipart/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.body_length/</loc> + <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/coverage/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.delete_resp_header/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/rest_principles/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.has_body/</loc> + <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/ci/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.has_resp_body/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/rest_handlers/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.has_resp_header/</loc> + <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/dialyzer/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.header/</loc> + <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/xref/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.headers/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/rest_flowcharts/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.host/</loc> + <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/external_plugins/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.host_info/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/resource_design/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.match_cookies/</loc> + <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/external_plugins_list/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.match_qs/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/ws_protocol/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.method/</loc> + <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/why/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.parse_cookies/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/ws_handlers/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.parse_header/</loc> + <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/history/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.parse_qs/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/streams/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.path/</loc> + <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/contributing/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.path_info/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/middlewares/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.peer/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/migrating_from_1.0/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.port/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/specs/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.push/</loc> + <loc>https://ninenines.eu/articles/cowboy-2.0.0-rc.2/</loc> + <lastmod>2017-08-23T18:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.qs/</loc> + <loc>https://ninenines.eu/articles/cowboy-2.0.0-rc.1/</loc> + <lastmod>2017-07-24T18:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.read_body/</loc> + <loc>https://ninenines.eu/articles/the-elephant-in-the-room/</loc> + <lastmod>2017-03-26T00:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.read_part/</loc> + <loc>https://ninenines.eu/articles/dont-let-it-crash/</loc> + <lastmod>2017-01-22T00:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.read_part_body/</loc> + <loc>https://ninenines.eu/articles/cowboy-2.0.0-pre.4/</loc> + <lastmod>2017-01-03T00:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.read_urlencoded_body/</loc> + <loc>https://ninenines.eu/articles/ranch-1.3/</loc> + <lastmod>2016-11-28T00:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.reply/</loc> + <loc>https://ninenines.eu/articles/ml-archives/</loc> + <lastmod>2016-08-29T00:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.resp_header/</loc> + <loc>https://ninenines.eu/articles/website-update/</loc> + <lastmod>2016-04-02T00:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.resp_headers/</loc> + <loc>https://ninenines.eu/articles/erlanger-playbook-september-2015-update/</loc> + <lastmod>2015-09-02T00:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.scheme/</loc> + <loc>https://ninenines.eu/services/</loc> + <lastmod>2015-07-01T00:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_body/</loc> + <loc>https://ninenines.eu/docs/</loc> + <lastmod>2015-07-01T00:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_cookie/</loc> + <loc>https://ninenines.eu/donate/</loc> + <lastmod>2015-07-01T00:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_header/</loc> + <loc>https://ninenines.eu/talks/</loc> + <lastmod>2015-07-01T00:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_headers/</loc> + <loc>https://ninenines.eu/slogan/</loc> + <lastmod>2015-07-01T00:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.stream_body/</loc> + <loc>https://ninenines.eu/articles/erlanger-playbook/</loc> + <lastmod>2015-06-18T00:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.stream_reply/</loc> + <loc>https://ninenines.eu/articles/erlang-validate-utf8/</loc> + <lastmod>2015-03-06T00:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.uri/</loc> + <loc>https://ninenines.eu/articles/on-open-source/</loc> + <lastmod>2014-09-05T00:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.version/</loc> + <loc>https://ninenines.eu/articles/the-story-so-far/</loc> + <lastmod>2014-08-23T00:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_rest/</loc> + <loc>https://ninenines.eu/articles/cowboy2-qs/</loc> + <lastmod>2014-08-20T00:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_router/</loc> + <loc>https://ninenines.eu/articles/january-2014-status/</loc> + <lastmod>2014-01-07T00:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_router.compile/</loc> + <loc>https://ninenines.eu/articles/farwest-funded/</loc> + <lastmod>2013-06-27T00:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_static/</loc> + <loc>https://ninenines.eu/articles/erlang.mk-and-relx/</loc> + <lastmod>2013-05-28T00:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_stream/</loc> + <loc>https://ninenines.eu/articles/xerl-0.5-intermediate-module/</loc> + <lastmod>2013-03-25T00:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_websocket/</loc> + <loc>https://ninenines.eu/articles/xerl-0.4-expression-separator/</loc> + <lastmod>2013-03-01T00:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/gun/1.0/manual/gun/</loc> + <loc>https://ninenines.eu/articles/erlang-scalability/</loc> + <lastmod>2013-02-18T00:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/gun/1.0/manual/gun_app/</loc> + <loc>https://ninenines.eu/articles/xerl-0.3-atomic-expressions/</loc> + <lastmod>2013-02-18T00:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch/</loc> + <loc>https://ninenines.eu/articles/xerl-0.2-two-modules/</loc> + <lastmod>2013-02-03T00:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch/</loc> + <loc>https://ninenines.eu/articles/xerl-0.1-empty-modules/</loc> + <lastmod>2013-01-30T00:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_app/</loc> + <loc>https://ninenines.eu/articles/ranch-ftp/</loc> + <lastmod>2012-11-14T00:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_app/</loc> + <loc>https://ninenines.eu/articles/tictactoe/</loc> + <lastmod>2012-10-17T00:00:00+01:00</lastmod> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_protocol/</loc> + <loc>https://ninenines.eu/articles/</loc> + <lastmod>2017-08-23T18:00:00+01:00</lastmod> + <priority>0</priority> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_protocol/</loc> + <loc>https://ninenines.eu/categories/</loc> + <priority>0</priority> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_ssl/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_ssl/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_tcp/</loc> + <loc>https://ninenines.eu/docs/</loc> + <priority>0</priority> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_tcp/</loc> + <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_transport/</loc> + <loc>https://ninenines.eu/docs/en/gun/1.0/manual/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_transport/</loc> + <loc>https://ninenines.eu/docs/en/gun/1.0/guide/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/installation/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/http_status_codes/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/gun/1.0/guide/introduction/</loc> + <loc>https://ninenines.eu/</loc> + <lastmod>2017-08-23T18:00:00+01:00</lastmod> + <priority>0</priority> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.2/guide/introduction/</loc> + <loc>https://ninenines.eu/docs/en/ranch/1.2/manual/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.3/guide/introduction/</loc> + <loc>https://ninenines.eu/docs/en/ranch/1.3/manual/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/modern_web/</loc> + <loc>https://ninenines.eu/docs/en/ranch/1.2/guide/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/erlang_web/</loc> + <loc>https://ninenines.eu/docs/en/ranch/1.3/guide/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/getting_started/</loc> + <loc>https://ninenines.eu/tags/</loc> + <priority>0</priority> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.2/guide/listeners/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.3/guide/listeners/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_app/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/gun/1.0/guide/start/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.set_env/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/gun/1.0/guide/protocols/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.start_clear/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/introduction/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.start_tls/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.2/guide/transports/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy.stop_listener/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.3/guide/transports/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_constraints/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/overview/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_constraints.int/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/gun/1.0/guide/connect/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_constraints.nonempty/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.2/guide/protocols/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_handler/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.3/guide/protocols/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_handler.terminate/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/getting_started/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_http/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/updating/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_http2/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/gun/1.0/guide/http/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_loop/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.2/guide/embedded/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_middleware/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.3/guide/embedded/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/limitations/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.binding/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/flow_diagram/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.bindings/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/gun/1.0/guide/websocket/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.body_length/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.2/guide/parsers/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.delete_resp_header/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.3/guide/parsers/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.has_body/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/app/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.has_resp_body/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/listeners/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.has_resp_header/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.2/guide/ssl_auth/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.header/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.3/guide/ssl_auth/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.headers/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/deps/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.host/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/routing/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.host_info/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/ports/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.match_cookies/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.2/guide/internals/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.match_qs/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/ranch/1.3/guide/internals/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.method/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/constraints/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.parse_cookies/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/releases/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.parse_header/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/sfx/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.parse_qs/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/handlers/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.path/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/escripts/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.path_info/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/loop_handlers/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.peer/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/compat/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.port/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/static_files/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.push/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/asciidoc/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.qs/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/edoc/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.read_body/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/req/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.read_part/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/req_body/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.read_part_body/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/shell/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.read_urlencoded_body/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/eunit/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.reply/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/resp/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.resp_header/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/common_test/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.resp_headers/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/cookies/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.scheme/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/multipart/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_body/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/coverage/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_cookie/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/rest_principles/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_header/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/ci/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.set_resp_headers/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/dialyzer/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.stream_body/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/rest_handlers/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.stream_reply/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/xref/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.uri/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/external_plugins/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_req.version/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/rest_flowcharts/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_rest/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/external_plugins_list/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_router/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/resource_design/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_router.compile/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/ws_protocol/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_static/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/why/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_stream/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/history/</loc> + <loc>https://ninenines.eu/docs/en/cowboy/2.0/manual/cowboy_websocket/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/ws_handlers/</loc> + <loc>https://ninenines.eu/docs/en/gun/1.0/manual/gun/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/erlang.mk/1/guide/contributing/</loc> + <loc>https://ninenines.eu/docs/en/gun/1.0/manual/gun_app/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/streams/</loc> + <loc>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/middlewares/</loc> + <loc>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/migrating_from_1.0/</loc> + <loc>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_app/</loc> </url> <url> - <loc>https://ninenines.eu/docs/en/cowboy/2.0/guide/specs/</loc> + <loc>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_app/</loc> + </url> + + <url> + <loc>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_protocol/</loc> + </url> + + <url> + <loc>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_protocol/</loc> + </url> + + <url> + <loc>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_ssl/</loc> + </url> + + <url> + <loc>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_ssl/</loc> + </url> + + <url> + <loc>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_tcp/</loc> + </url> + + <url> + <loc>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_tcp/</loc> + </url> + + <url> + <loc>https://ninenines.eu/docs/en/ranch/1.2/manual/ranch_transport/</loc> + </url> + + <url> + <loc>https://ninenines.eu/docs/en/ranch/1.3/manual/ranch_transport/</loc> </url> </urlset>
\ No newline at end of file diff --git a/slogan/index.html b/slogan/index.html index 7d0dcbc9..8b426caf 100644 --- a/slogan/index.html +++ b/slogan/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Slogan</title> @@ -65,9 +65,9 @@ <h2></h2> </div> <div class="content"> - <div class="paragraph"><p>Feeling generous? Love reading?<br />
-<a href="https://salt.bountysource.com/teams/ninenines">Crowdfund my salary</a>
-or buy <a href="/articles/erlanger-playbook">The Erlanger Playbook</a></p></div>
+ <div class="paragraph"><p>Feeling generous? Love reading?<br /> +<a href="https://salt.bountysource.com/teams/ninenines">Crowdfund my salary</a> +or buy <a href="/articles/erlanger-playbook">The Erlanger Playbook</a></p></div> </div> diff --git a/support/index.html b/support/index.html index ca1b17c3..0ab3fab4 100644 --- a/support/index.html +++ b/support/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/services/</title><link rel="canonical" href="https://ninenines.eu/services/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/services/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/services/</title><link rel="canonical" href="https://ninenines.eu/services/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/services/" /></head></html>
\ No newline at end of file diff --git a/tags/index.html b/tags/index.html index 278c2993..b84bcce0 100644 --- a/tags/index.html +++ b/tags/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Tags</title> diff --git a/tags/index.xml b/tags/index.xml new file mode 100644 index 00000000..875943a0 --- /dev/null +++ b/tags/index.xml @@ -0,0 +1,14 @@ +<?xml version="1.0" encoding="utf-8" standalone="yes" ?> +<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"> + <channel> + <title>Tags on Nine Nines</title> + <link>https://ninenines.eu/tags/</link> + <description>Recent content in Tags on Nine Nines</description> + <generator>Hugo -- gohugo.io</generator> + <language>en-us</language> + + <atom:link href="https://ninenines.eu/tags/index.xml" rel="self" type="application/rss+xml" /> + + + </channel> +</rss>
\ No newline at end of file diff --git a/talks/index.html b/talks/index.html index 6ea5eabd..d3ee009f 100644 --- a/talks/index.html +++ b/talks/index.html @@ -7,7 +7,7 @@ <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.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: Public talks</title> @@ -109,14 +109,14 @@ </div> <div class="span3 sidecol"> -<div class="sect2">
-<h3 id="_talk_requests">Talk requests</h3>
-<div class="paragraph"><p>Organizing a conference and in need of a speaker for a talk
-about Erlang and the Web? Need an introduction to Erlang/OTP
-for your company? Looking for a cool subject for a user group
-meeting?</p></div>
-<div class="paragraph"><p><a href="mailto:[email protected]">Send me an email with the details</a>.</p></div>
-</div>
+<div class="sect2"> +<h3 id="_talk_requests">Talk requests</h3> +<div class="paragraph"><p>Organizing a conference and in need of a speaker for a talk +about Erlang and the Web? Need an introduction to Erlang/OTP +for your company? Looking for a cool subject for a user group +meeting?</p></div> +<div class="paragraph"><p><a href="mailto:[email protected]">Send me an email with the details</a>.</p></div> +</div> </div> </div> diff --git a/training/index.html b/training/index.html index ca1b17c3..0ab3fab4 100644 --- a/training/index.html +++ b/training/index.html @@ -1 +1 @@ -<!DOCTYPE html><html><head><title>https://ninenines.eu/services/</title><link rel="canonical" href="https://ninenines.eu/services/"/><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/services/" /></head></html>
\ No newline at end of file +<!DOCTYPE html><html><head><title>https://ninenines.eu/services/</title><link rel="canonical" href="https://ninenines.eu/services/"/><meta name="robots" content="noindex"><meta http-equiv="content-type" content="text/html; charset=utf-8" /><meta http-equiv="refresh" content="0; url=https://ninenines.eu/services/" /></head></html>
\ No newline at end of file |
