[[websocket-intro]]
= Introduction

The WebSocket protocol http://tools.ietf.org/html/rfc6455[RFC 6455] provides a standardized
way to establish a full-duplex, two-way communication channel between client and server
over a single TCP connection. It is a different TCP protocol from HTTP but is designed to
work over HTTP, using ports 80 and 443 and allowing re-use of existing firewall rules.

A WebSocket interaction begins with an HTTP request that uses the HTTP `"Upgrade"` header
to upgrade, or in this case to switch, to the WebSocket protocol:

[subs="quotes"]
----
GET /spring-websocket-portfolio/portfolio HTTP/1.1
Host: localhost:8080
**Upgrade: websocket**
**Connection: Upgrade**
Sec-WebSocket-Key: Uc9l9TMkWGbHFD2qnFHltg==
Sec-WebSocket-Protocol: v10.stomp, v11.stomp
Sec-WebSocket-Version: 13
Origin: http://localhost:8080
----

Instead of the usual 200 status code, a server with WebSocket support returns:

[subs="quotes"]
----
**HTTP/1.1 101 Switching Protocols**
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: 1qVdfYHU9hPOl4JYYNXF623Gzn0=
Sec-WebSocket-Protocol: v10.stomp
----

After a successful handshake the TCP socket underlying the HTTP upgrade request remains
open for both client and server to continue to send and receive messages.

A complete introduction of how WebSockets work is beyond the scope of this document.
Please read RFC 6455, the WebSocket chapter of HTML5, or one of many introductions and
tutorials on the Web.

Note that if a WebSocket server is running behind a web server (e.g. nginx) you will
likely need to configure it to pass WebSocket upgrade requests on to the WebSocket
server. Likewise if the application runs in a cloud environment, check the
instructions of the cloud provider related to WebSocket support.




[[websocket-intro-architecture]]
== HTTP vs WebSocket

Even though WebSocket is designed to be HTTP compatible and starts with an HTTP request,
it is important to understand that the two protocols lead to very different
architectures and application programming models.

In HTTP and REST, an application is modeled as many URLs. To interact with the application
clients access those URLs, request-response style. Servers route requests to the
appropriate handler based on the HTTP URL, method, and headers.

By contrast in WebSockets there is usually just one URL for the initial connect and
subsequently all application messages flow on that same TCP connection. This points to
an entirely different asynchronous, event-driven, messaging architecture.

WebSocket is also a low-level transport protocol which unlike HTTP does not prescribe
any semantics to the content of messages. That means there is no way to route or process
a message unless client and server agree on message semantics.

WebSocket clients and servers can negotiate the use of a higher-level, messaging protocol
(e.g. STOMP), via the `"Sec-WebSocket-Protocol"` header on the HTTP handshake request,
or in the absence of that they need to come up with their own conventions.



[[websocket-intro-when-to-use]]
== When to use it?

WebSockets can make a web page dynamic and interactive. However in many cases
a combination of Ajax and HTTP streaming and/or long polling could provide a simple and
effective solution.

For example news, mail, and social feeds need to update dynamically but it may be
perfectly okay to do so every few minutes. Collaboration, games, and financial apps on
the other hand need to be much closer to real time.

Latency alone is not a deciding factor. If the volume of messages is relatively low (e.g.
monitoring network failures) HTTP streaming or polling may provide an effective solution.
It is the combination of low latency, high frequency and high volume that make the best
case for the use WebSocket.

Keep in mind also that over the Internet, restrictive proxies  outside your control,
may preclude WebSocket interactions either because they are not configured to pass on the
`Upgrade` header or because they close long lived connections that appear idle? This
means that the use of WebSocket for internal applications within the firewall is a more
straight-forward decision than it is for public facing applications.
