== 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:request/{4,5,6}` for each respective
methods. Gun also provides a `gun:data/4` function for streaming
the request body.

Gun will send a `gun_response` message for every response
received, followed by zero or more `gun_data` messages for
the response body. 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's 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 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 response 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_ws_upgrade` message will be sent on success;
a `gun_response` message otherwise.

=== SPDY

SPDY 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 multiple responses to a single
request.

The SPDY interface is very similar to HTTP/1.1, so this
section instead focuses on the differences in the interface
for the two protocols.

Because a SPDY server can push multiple responses to a
single request, Gun might send `gun_push` messages for
every push received. They can be ignored safely if they
are not needed.

The `gun:cancel/2` function will use the SPDY stream
cancellation mechanism which allows Gun to inform the
server to stop sending a response for this particular
request, saving resources.

It is not possible to upgrade a SPDY connection to Websocket
due to protocol limitations.

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

Websocket is only available as a connection upgrade over
an HTTP/1.1 connection.

Once the Websocket connection is established, the only
operation available on this connection is sending Websocket
frames using `gun:ws_send/2`.

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 | SPDY | 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      | no   | no
| ws_send    | no       | no   | yes
|===

.Messages sent per protocol
[cols="<,3*^",options="header"]
|===
| Message               | HTTP/1.1 | SPDY | Websocket
| gun_push              | no       | yes  | no
| gun_response          | yes      | yes  | no
| gun_data              | yes      | yes  | no
| gun_error (StreamRef) | yes      | yes  | no
| gun_error             | yes      | yes  | yes
| gun_ws_upgrade        | yes      | no   | no
| gun_ws                | no       | no   | yes
|===