<!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">
<title>Nine Nines: cowboy_stream_h(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=7" 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="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_stream_h(3)</span></h1>
<h2 id="_name">Name</h2>
<p>cowboy_stream_h - Default stream handler</p>
<h2 id="_description">Description</h2>
<p>The module <code>cowboy_stream_h</code> is Cowboy's default stream handler and defines much of its behavior. It is responsible for managing the request process, sending it the request body and translating its messages into commands that Cowboy understands.</p>
<h2 id="_options">Options</h2>
<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><b><font color="#000000">opts</font></b>() <font color="#990000">::</font> #{
<font color="#0000FF">env</font> <font color="#990000">=></font> <b><font color="#000000">cowboy_middleware:env</font></b>(),
<font color="#0000FF">middlewares</font> <font color="#990000">=></font> [<b><font color="#000000">module</font></b>()],
<font color="#000080">shutdown</font><font color="#009900">_timeout</font> <font color="#990000">=></font> <b><font color="#000000">timeout</font></b>()
}</tt></pre>
</div></div>
<p>Configuration for the default stream handler.</p>
<p>The default value is given next to the option name:</p>
<dl><dt>env (#{})</dt>
<dd><p>Middleware environment.</p>
</dd>
<dt>middlewares ([cowboy_router, cowboy_handler])</dt>
<dd><p>Middlewares to run for every request.</p>
</dd>
<dt>shutdown_timeout (5000)</dt>
<dd><p>Time in ms Cowboy will wait for child processes to shut down before killing them.</p>
</dd>
</dl>
<h2 id="_events">Events</h2>
<p>The default stream handler spawns the request process and receives its exit signal when it terminates. It will stop the stream once its receives it.</p>
<p>Because this stream handler converts events from the request process into commands, other stream handlers may not work properly if they are executed after the default stream handler. Always be mindful of in which order stream handlers will get executed.</p>
<h3 id="_request_body">Request body</h3>
<p>The default stream handler implements the <code>read_body</code> mechanism. In addition to reading the body, the handler will automatically handle the <code>expect: 100-continue</code> header and send a 100 Continue response.</p>
<p>Normally one would use <a href="../cowboy_req.read_body">cowboy_req:read_body(3)</a> to read the request body. The default stream handler will buffer data until the amount gets larger than the requested length before sending it. Alternatively, it will send whatever data it has when the period timeout triggers. Depending on the protocol, the flow control window is updated to allow receiving data for the requested length.</p>
<p>The default stream handler also comes with an automatic mode for reading the request body. This can be used by sending the event message <code>{read_body, Pid, Ref, auto, infinity}</code> using <a href="../cowboy_req.cast">cowboy_req:cast(3)</a>. The default stream handler will then send data as soon as some becomes available using one of these two messages depending on whether body reading was completed:</p>
<ul><li><code>{request_body, Ref, nofin, Data}</code>
</li>
<li><code>{request_body, Ref, fin, BodyLen, Data}</code>
</li>
</ul>
<p>Depending on the protocol, Cowboy will update the flow control window using the size of the data that was read.</p>
<p>Auto mode automatically gets disabled after data has been sent to the handler. Therefore in order to continue reading data a <code>read_body</code> event message must be sent after each <code>request_body</code> message.</p>
<h3 id="_response">Response</h3>
<p>In addition it returns a command for any event message looking like one of the following commands: <code>inform</code>, <code>response</code>, <code>headers</code>, <code>data</code>, <code>trailers</code>, <code>push</code>, <code>switch_protocol</code>. This is what allows the request process to send a response.</p>
<h2 id="_changelog">Changelog</h2>
<ul><li><strong>2.11</strong>: Introduce body reading using auto mode.
</li>
<li><strong>2.0</strong>: Module introduced.
</li>
</ul>
<h2 id="_see_also">See also</h2>
<p><a href="..">cowboy(7)</a>, <a href="../cowboy_stream">cowboy_stream(3)</a>, <a href="../cowboy_compress_h">cowboy_compress_h(3)</a>, <a href="../cowboy_decompress_h">cowboy_decompress_h(3)</a>, <a href="../cowboy_metrics_h">cowboy_metrics_h(3)</a>, <a href="../cowboy_tracer_h">cowboy_tracer_h(3)</a>, <a href="../cowboy_req.cast">cowboy_req:cast(3)</a></p>
</div>
<div class="span3 sidecol">
<h3>
Cowboy
2.12
Function Reference
</h3>
<ul>
<li><a href="/docs/en/cowboy/2.12/guide">User Guide</a></li>
<li><a href="/docs/en/cowboy/2.12/manual">Function Reference</a></li>
</ul>
<h4 id="docs-nav">Navigation</h4>
<h4>Version select</h4>
<ul>
<li><a href="/docs/en/cowboy/2.12/manual">2.12</a></li>
<li><a href="/docs/en/cowboy/2.11/manual">2.11</a></li>
<li><a href="/docs/en/cowboy/2.10/manual">2.10</a></li>
<li><a href="/docs/en/cowboy/2.9/manual">2.9</a></li>
<li><a href="/docs/en/cowboy/2.8/manual">2.8</a></li>
<li><a href="/docs/en/cowboy/2.7/manual">2.7</a></li>
<li><a href="/docs/en/cowboy/2.6/manual">2.6</a></li>
</ul>
<h3 id="_like_my_work__donate">Like my work? Donate!</h3>
<p>Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:</p>
<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><p>Recurring payment options are also available via <a href="https://github.com/sponsors/essen">GitHub Sponsors</a>. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.</p>
</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-2018</p>
</div>
</div>
</div>
</footer>
<script src="/js/custom.js"></script>
</body>
</html>
