Structural Fixes

framework-docs/modules/ROOT/partials/web/websocket-intro.adoc

@@ -0,0 +1,103 @@
+[[introduction-to-websocket]]
+= Introduction to WebSocket
+
+The WebSocket protocol, https://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. The following example
+shows such an interaction:
+
+[source,yaml,indent=0,subs="verbatim,quotes"]
+----
+	GET /spring-websocket-portfolio/portfolio HTTP/1.1
+	Host: localhost:8080
+	Upgrade: websocket <1>
+	Connection: Upgrade <2>
+	Sec-WebSocket-Key: Uc9l9TMkWGbHFD2qnFHltg==
+	Sec-WebSocket-Protocol: v10.stomp, v11.stomp
+	Sec-WebSocket-Version: 13
+	Origin: http://localhost:8080
+----
+<1> The `Upgrade` header.
+<2> Using the `Upgrade` connection.
+
+
+Instead of the usual 200 status code, a server with WebSocket support returns output
+similar to the following:
+
+[source,yaml,indent=0,subs="verbatim,quotes"]
+----
+	HTTP/1.1 101 Switching Protocols <1>
+	Upgrade: websocket
+	Connection: Upgrade
+	Sec-WebSocket-Accept: 1qVdfYHU9hPOl4JYYNXF623Gzn0=
+	Sec-WebSocket-Protocol: v10.stomp
+----
+<1> Protocol switch
+
+
+After a successful handshake, the TCP socket underlying the HTTP upgrade request remains
+open for both the client and the server to continue to send and receive messages.
+
+A complete introduction of how WebSockets work is beyond the scope of this document.
+See RFC 6455, the WebSocket chapter of HTML5, or any of the many introductions and
+tutorials on the Web.
+
+Note that, if a WebSocket server is running behind a web server (e.g. nginx), you
+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.
+
+
+
+
+[[http-versus-websocket]]
+== HTTP Versus 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 only one URL for the initial connect.
+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 that there is no way to route or process
+a message unless the client and the server agree on message semantics.
+
+WebSocket clients and servers can negotiate the use of a higher-level, messaging protocol
+(for example, STOMP), through the `Sec-WebSocket-Protocol` header on the HTTP handshake request.
+In the absence of that, they need to come up with their own conventions.
+
+
+
+
+[[when-to-use-websockets]]
+== When to Use WebSockets
+
+WebSockets can make a web page be dynamic and interactive. However, in many cases,
+a combination of AJAX and HTTP streaming or long polling can 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 (for example,
+monitoring network failures) HTTP streaming or polling can provide an effective solution.
+It is the combination of low latency, high frequency, and high volume that make the best
+case for the use of WebSocket.
+
+Keep in mind also that over the Internet, restrictive proxies that are outside of 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
+straightforward decision than it is for public facing applications.