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
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
|
<!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: Migrating from Gun 1.3 to 2.0</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>Migrating from Gun 1.3 to 2.0</span></h1>
<p>Gun 2.0 adds many features including graceful shutdown, flow control for data messages, event handlers, support for tunneling TLS connections through TLS proxies, Socks proxy support, and much more. It has only a limited number of breaking changes compared to the previous version.</p>
<p>Gun 2.0 greatly improves the HTTP/2 performance when it comes to receiving large response bodies; and when receiving response bodies from many separate requests concurrently.</p>
<p>Gun now shares much of its HTTP/2 code with Cowboy, including the HTTP/2 state machine. Numerous issues were fixed as a result because the Cowboy implementation was much more advanced.</p>
<p>The Gun connection process is now implemented using <code>gen_statem</code>.</p>
<p>Gun 2.0 requires Erlang/OTP 22.0 or greater.</p>
<h2 id="_features_added">Features added</h2>
<ul><li>Cookie store support has been added. The <code>cookie_store</code> option allows configuring the cookie store backend. The <code>gun_cookies</code> module provides functions to help implementing such a backend. Gun comes with the backend <code>gun_cookies_list</code> which provides a per-connection, non-persistent cookie store. The cookie store engine implements the entire RFC6265bis draft algorithms except the parts about non-HTTP cookies as no such interface is provided; and the parts about SameSite as Gun has no concept of "browsing context".
</li>
<li>Graceful shutdown has been implemented. Graceful shutdown can be initiated on the client side by calling the new function <code>gun:shutdown/1</code> or when the owner process goes away; or on the peer side via the connection: close HTTP/1.1 header, the HTTP/2 GOAWAY frame or the Websocket close frame. Gun will try to complete existing streams when possible; other streams get canceled immediately. The <code>closing_timeout</code> option controls how long we are willing to wait at most before closing the connection.
</li>
<li>Flow control has been added. It allows limiting the number of data/Websocket messages Gun sends to the calling process. Gun will stop reading from the socket or stop updating the protocol's flow control window when applicable as well, to apply some backpressure to the remote endpoint(s). It is disabled by default and can be applied on a per-request basis if necessary.
</li>
<li>An event handler interface has been added providing access to many internal Gun events. This can be used for a variety of purposes including logging, tracing or otherwise instrumenting a Gun connection.
</li>
<li>In order to get separate events when connecting, the domain lookup, connection and TLS handshakes are now performed separately by Gun. As a result, there exists three separate timeout options for each of the steps, and the transport options had to be split into <code>tcp_opts</code> and <code>tls_opts</code>.
</li>
<li>Gun can connect through any number of HTTP, HTTPS, Socks or secure Socks proxies, including when Socks proxies are located after the HTTP(S) proxies. The ultimate endpoint may be using any protocol, including plain TCP, TLS, HTTP/1.1 or HTTP/2.
</li>
<li>Gun now supports connecting through Socks5 proxies, including secure Socks proxies. Both unauthenticated and username/password authentication are supported.
</li>
<li>When specifying which protocols to use, options can now be provided specific to those protocols. It is now possible to have separate HTTP options for an HTTP proxy and the origin HTTP server, for example. See the new <code>protocols()</code> type for details.
</li>
<li>Gun can now be used to send and receive raw data, as if it was just a normal socket. This can be useful when needing to connect through a number of HTTP/Socks proxies, allowing the use of Gun's great proxying capabilities (including TLS over TLS) for any sort of protocols. This can also be useful when performing HTTP/1.1 Upgrade to custom protocols.
</li>
<li>Headers can now be provided as a map.
</li>
<li>Header names may now be provided as binary, string or atom.
</li>
<li>Many HTTP/2 options have been added, allowing great control over how Gun and the remote endpoint are using the HTTP/2 connection. They can be used to improve performance or lower the memory usage, for example.
</li>
<li>It is now possible to send many Websocket frames in a single <code>gun:ws_send/2</code> call.
</li>
<li>Gun will now send Websocket ping frames automatically at intervals determined by the <code>keepalive</code> option. It defaults to 5 seconds.
</li>
<li>A new <code>silence_pings</code> option can be set to <code>false</code> to receive all ping and pong frames when using Websocket. They are typically not needed and therefore silent by default.
</li>
<li>The <code>reply_to</code> option has been added to <code>gun:ws_upgrade/4</code>. The option applies to both the response and subsequent Websocket frames.
</li>
<li>The <code>reply_to</code> option is also propagated to messages following a CONNECT request when the protocol requested is not HTTP.
</li>
<li>A new option <code>retry_fun</code> can be used to implement different backoff strategies when reconnecting.
</li>
<li>A new option <code>supervise</code> can be used to start a Gun connection without using Gun's supervisor. It defaults to <code>true</code>.
</li>
<li>Gun now automatically lowercases provided header names.
</li>
<li>Many improvements have been done to postpone or reject requests and other operations while in the wrong state (for example during state transitions when switching protocols or connecting to proxies).
</li>
</ul>
<h2 id="_features_removed">Features removed</h2>
<ul><li>Gun used to reject operations by processes that were not the owner of the connection. This behavior has been removed. In general the caller of a request or other operation will receive the relevant messages unless the <code>reply_to</code> option is used.
</li>
<li>The <code>connect_destination()</code> option <code>protocol</code> has been removed. It was previously deprecated in favor of <code>protocols</code>.
</li>
<li>The <code>keepalive</code> timeout is now disabled by default for HTTP/1.1. To be perfectly clear, this is unrelated to the HTTP/1.1 keep-alive mechanism.
</li>
</ul>
<h2 id="_functions_added">Functions added</h2>
<ul><li>The function <code>gun:set_owner/2</code> has been added. It allows changing the owner of a connection process. Only the current owner can do this operation.
</li>
<li>The function <code>gun:shutdown/1</code> has been added. It initiates the graceful shutdown of the connection, followed by the termination of the Gun process.
</li>
<li>The function <code>gun:stream_info/2</code> has been added. It provides information about a specific HTTP stream.
</li>
</ul>
<h2 id="_functions_modified">Functions modified</h2>
<ul><li>The function <code>gun:info/1</code> now returns the owner of the connection.
</li>
<li>The functions <code>gun:await/2,3,4</code>, <code>gun:await_body/2,3,4</code> and <code>gun:await_up/1,2,3</code> now distinguish the error types. They can be a timeout, a connection error, a stream error or a down error (when the Gun process exited while waiting).
</li>
<li>The functions <code>gun:await/2,3,4</code> will now receive upgrade and Websocket messages and return them.
</li>
<li>The functions <code>gun:request/4,5,6</code> have been replaced with <code>gun:headers/4,5</code> and <code>gun:request/5,6</code>. This provides a cleaner separation between requests that are followed by a body separately from those that don't.
</li>
</ul>
<h2 id="_messages_modified">Messages modified</h2>
<ul><li>The <code>gun_down</code> message no longer has its final element documented as <code>UnprocessedStreams</code>. It never worked and was always an empty list.
</li>
</ul>
<h2 id="_bugs_fixed">Bugs fixed</h2>
<ul><li><strong>POTENTIAL SECURITY VULNERABILITY</strong>: Fix transfer-encoding precedence over content-length in responses. This bug may contribute to a response smuggling security vulnerability when Gun is used inside a proxy.
</li>
<li>Gun will no longer send duplicate connection-wide <code>gun_error</code> messages to the same process.
</li>
<li>Gun no longer crashes when trying to upgrade to Websocket over a connection restricted to HTTP/1.0.
</li>
<li>The default value for the preferred protocols when using CONNECT over TLS has been corrected. It was mistakenly not enabling HTTP/2.
</li>
<li>Gun will no longer send an empty HTTP/2 DATA frame when there is no request body. It was not necessary.
</li>
<li>Gun will no longer error out when the owner process exits. The error reason will now be a <code>shutdown</code> tuple instead.
</li>
<li>The host header was set incorrectly during Websocket upgrades when the host was configured with an IP address, resulting in a crash. This has been corrected.
</li>
<li>A completed stream could be found in the <code>gun_down</code> message when the response contained a connection: close header. This is no longer the case.
</li>
<li>Hostnames can now be provided as atom as stated by the documentation.
</li>
<li>Gun will no longer attempt to send empty data chunks. When using HTTP/1.1 chunked transfer-encoding this caused the request body to terminated, even when <code>nofin</code> was given.
</li>
<li>Gun now always retries connecting immediately when the connection goes down.
</li>
<li>The default port number for the HTTP and HTTPS schemes is no longer sent in the host header.
</li>
<li>An invalid stream reference was sent on failed Websocket upgrade responses. This has been corrected.
</li>
<li>HTTP/2 connection preface errors are now properly detected and propagated in the <code>gun_down</code> message to the connection owner as well as the exit reason of the Gun process.
</li>
<li>HTTP/2 connection preface errors now provide a different human readable error when the data received looks like an HTTP/1.x response.
</li>
<li>HTTP/2 connection errors were missing the human readable reason in the <code>gun_error</code> message. This has been corrected.
</li>
<li>Fix the host and :authority (pseudo-)headers when connecting to an IPv6 address given as a tuple. They were lacking the surrounding brackets.
</li>
<li>Fix a crash in gun:info/1 when the socket was closed before we call Transport:sockname/1.
</li>
</ul>
<nav style="margin:1em 0">
<a style="float:left" href="https://ninenines.eu/docs/en/gun/2.0/guide/websocket/">
Websocket
</a>
<a style="float:right" href="https://ninenines.eu/docs/en/gun/2.0/guide/migrating_from_1.2/">
Migrating from Gun 1.2 to 1.3
</a>
</nav>
</div>
<div class="span3 sidecol">
<h3>
Gun
2.0
User Guide
</h3>
<ul>
<li><a href="/docs/en/gun/2.0/guide">User Guide</a></li>
<li><a href="/docs/en/gun/2.0/manual">Function Reference</a></li>
</ul>
<h4 id="docs-nav">Navigation</h4>
<h4>Version select</h4>
<ul>
<li><a href="/docs/en/gun/2.0/guide">2.0</a></li>
<li><a href="/docs/en/gun/1.3/guide">1.3</a></li>
<li><a href="/docs/en/gun/1.2/guide">1.2</a></li>
<li><a href="/docs/en/gun/1.1/guide">1.1</a></li>
<li><a href="/docs/en/gun/1.0/guide">1.0</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>
|
