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
|
[[protocols]]
== Supported protocols
This chapter describes the protocols supported and the
operations available to them.
=== HTTP/1.1
HTTP/1.1 is a text request-response protocol. The client
sends a request, the server sends back a response.
Gun provides convenience functions for performing GET, HEAD,
OPTIONS, POST, PATCH, PUT, and DELETE requests. All these
functions are aliases of `gun:headers/4,5` or `gun:request/5,6`
for the respective methods. Gun also provides a `gun:data/4`
function for streaming the request body.
Gun will send a `gun_inform` message for every intermediate
informational responses received. They will always be sent
before the `gun_response` message.
Gun will send a `gun_response` message for every response
received, followed by zero or more `gun_data` messages for
the response body, which is optionally terminated by a
`gun_trailers` message. If something goes wrong, a `gun_error`
will be sent instead.
Gun provides convenience functions for dealing with messages.
The `gun:await/2,3,4` function waits for a response to the given
request, and the `gun:await_body/2,3,4` function for the
response body. The `gun:flush/1` function can be used to clear all
messages related to a request or a connection from the mailbox
of the calling process.
The function `gun:cancel/2` can be used to silence the
response to a request previously sent if it is no longer
needed. When using HTTP/1.1 there is no multiplexing so
Gun will have to receive the response fully before any
other responses can be received.
Finally, Gun can upgrade an HTTP/1.1 connection to Websocket.
It provides the `gun:ws_upgrade/2,3,4` function for that
purpose. A `gun_upgrade` message will be sent on success;
a `gun_response` message otherwise.
=== HTTP/2
HTTP/2 is a binary protocol based on HTTP, compatible with
the HTTP semantics, that reduces the complexity of parsing
requests and responses, compresses the HTTP headers and
allows the server to push additional resources along with
the normal response to the original request.
The HTTP/2 interface is very similar to HTTP/1.1, so this
section instead focuses on the differences in the interface
for the two protocols.
Gun will send `gun_push` messages for every push received.
They will always be sent before the `gun_response` message.
They can be ignored safely if they are not needed, or they
can be canceled.
The `gun:cancel/2` function will use the HTTP/2 stream
cancellation mechanism which allows Gun to inform the
server to stop sending a response for this particular
request, saving resources.
Note that because HTTP/2 headers are compressed, there
are scenarios where it is possible to probe or extract
data, creating security risks. One scenario being the
use of Gun as a proxy to create a single connection to
an origin, with requests coming from multiple mutually
distrustful entities. Gun will provide configuration
options to restrict headers that can be compressed in
a future release.
=== Websocket
Websocket is a binary protocol built on top of HTTP that
allows asynchronous concurrent communication between the
client and the server. A Websocket server can push data to
the client at any time.
Once the Websocket connection is established over an HTTP/1.1
connection, the only operation available on this connection
is sending Websocket frames using `gun:ws_send/3`.
Gun will send a `gun_ws` message for every frame received.
It is recommended to disable automatic reconnect when
Websocket is used because Gun cannot automatically upgrade
to Websocket on reconnect, and so an undetected disconnect
may lead to many error messages from Gun.
=== Summary
The two following tables summarize the supported operations
and the messages Gun sends depending on the connection's
current protocol.
.Supported operations per protocol
[cols="<,3*^",options="header"]
|===
| Operation | HTTP/1.1 | HTTP/2 | Websocket
| delete | yes | yes | no
| get | yes | yes | no
| head | yes | yes | no
| options | yes | yes | no
| patch | yes | yes | no
| post | yes | yes | no
| put | yes | yes | no
| request | yes | yes | no
| data | yes | yes | no
| await | yes | yes | no
| await_body | yes | yes | no
| flush | yes | yes | no
| cancel | yes | yes | no
| ws_upgrade | yes | yes | no
| ws_send | no | no | yes
|===
.Messages sent per protocol
[cols="<,3*^",options="header"]
|===
| Message | HTTP/1.1 | HTTP/2 | Websocket
| gun_push | no | yes | no
| gun_inform | yes | yes | no
| gun_response | yes | yes | no
| gun_data | yes | yes | no
| gun_trailers | yes | yes | no
| gun_error | yes | yes | yes
| gun_upgrade | yes | yes | no
| gun_ws | no | no | yes
|===
|
