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
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
|
<!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: HTTP</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="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>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
by 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
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
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
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
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
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
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
by 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
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
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
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
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
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
by 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
by 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
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
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
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
by 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
by 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
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">
<a style="float:left" href="https://ninenines.eu/docs/en/gun/1.0/guide/connect/">
Connection
</a>
<a style="float:right" href="https://ninenines.eu/docs/en/gun/1.0/guide/websocket/">
Websocket
</a>
</nav>
</div>
<div class="span3 sidecol">
<h3>
Gun
1.0
User Guide
</h3>
<ul>
<li><a href="/docs/en/gun/1.0/guide">User Guide</a></li>
<li><a href="/docs/en/gun/1.0/manual">Function Reference</a></li>
</ul>
<h4 id="docs-nav">Navigation</h4>
<h4>Version select</h4>
<ul>
<li><a href="/docs/en/gun/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>
|
