blob: cc34a8dca3950162a55161225f81d509ee9362c0 (
plain) (
tree)
|
|
<!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.37.1" />
<title>Nine Nines: Streams</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>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>
<nav style="margin:1em 0">
<a style="float:left" href="https://ninenines.eu/docs/en/cowboy/2.1/guide/ws_handlers/">
Websocket handlers
</a>
<a style="float:right" href="https://ninenines.eu/docs/en/cowboy/2.1/guide/middlewares/">
Middlewares
</a>
</nav>
</div>
<div class="span3 sidecol">
<h3>
Cowboy
2.1
User Guide
</h3>
<ul>
<li><a href="/docs/en/cowboy/2.1/guide">User Guide</a></li>
<li><a href="/docs/en/cowboy/2.1/manual">Function Reference</a></li>
</ul>
<h4 id="docs-nav">Navigation</h4>
<h4>Version select</h4>
<ul>
<li><a href="/docs/en/cowboy/2.3/guide">2.3</a></li>
<li><a href="/docs/en/cowboy/2.2/guide">2.2</a></li>
<li><a href="/docs/en/cowboy/2.1/guide">2.1</a></li>
<li><a href="/docs/en/cowboy/2.0/guide">2.0</a></li>
<li><a href="/docs/en/cowboy/1.0/guide">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-2018</p>
</div>
</div>
</div>
</footer>
<script src="/js/custom.js"></script>
</body>
</html>
|
