1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
|
<!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>
|
