[[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.

=== 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.

=== 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
|===