1 files changed, 83 insertions, 162 deletions
diff --git a/doc/src/guide/modern_web.asciidoc b/doc/src/guide/modern_web.asciidoc
index 732972f..6c43adb 100644
--- a/doc/src/guide/modern_web.asciidoc
+++ b/doc/src/guide/modern_web.asciidoc
@@ -1,164 +1,58 @@
 [[modern_web]]
 == The modern Web
 
-Let's take a look at various technologies from the beginnings
-of the Web up to this day, and get a preview of what's
-coming next.
+// @todo Link to related xrefs.
 
-Cowboy is compatible with all the technology cited in this
-chapter except of course HTTP/2.0 which has no implementation
-in the wild at the time of writing.
+Cowboy is a server for the modern Web. This chapter explains
+what it means and details all the standards involved.
 
-=== The prehistoric Web
+Cowboy supports all the standards listed in this document.
 
-HTTP was initially created to serve HTML pages and only
-had the GET method for retrieving them. This initial
-version is documented and is sometimes called HTTP/0.9.
-HTTP/1.0 defined the GET, HEAD and POST methods, and
-was able to send data with POST requests.
-
-HTTP/1.0 works in a very simple way. A TCP connection
-is first established to the server. Then a request is
-sent. Then the server sends a response back and closes
-the connection.
-
-Suffice to say, HTTP/1.0 is not very efficient. Opening
-a TCP connection takes some time, and pages containing
-many assets load much slower than they could because of
-this.
-
-Most improvements done in recent years focused on reducing
-this load time and reducing the latency of the requests.
-
-=== HTTP/1.1
-
-HTTP/1.1 quickly followed and added a keep-alive mechanism
-to allow using the same connection for many requests, as
-well as streaming capabilities, allowing an endpoint to send
-a body in well defined chunks.
-
-HTTP/1.1 defines the OPTIONS, GET, HEAD, POST, PUT, DELETE,
-TRACE and CONNECT methods. The PATCH method was added in more
-recent years. It also improves the caching capabilities with
-the introduction of many headers.
-
-HTTP/1.1 still works like HTTP/1.0 does, except the connection
-can be kept alive for subsequent requests. This however allows
-clients to perform what is called as pipelining: sending many
-requests in a row, and then processing the responses which will
-be received in the same order as the requests.
-
-=== REST
-
-The design of HTTP/1.1 was influenced by the REST architectural
-style. REST, or REpresentational State Transfer, is a style of
-architecture for loosely connected distributed systems.
-
-REST defines constraints that systems must obey to in order to
-be RESTful. A system which doesn't follow all the constraints
-cannot be considered RESTful.
-
-REST is a client-server architecture with a clean separation
-of concerns between the client and the server. They communicate
-by referencing resources. Resources can be identified, but
-also manipulated. A resource representation has a media type
-and information about whether it can be cached and how. Hypermedia
-determines how resources are related and how they can be used.
-REST is also stateless. All requests contain the complete
-information necessary to perform the action.
-
-HTTP/1.1 defines all the methods, headers and semantics required
-to implement RESTful systems.
-
-REST is most often used when designing web application APIs
-which are generally meant to be used by executable code directly.
-
-=== XmlHttpRequest
-
-Also know as AJAX, this technology allows Javascript code running
-on a web page to perform asynchronous requests to the server.
-This is what started the move from static websites to dynamic
-web applications.
-
-XmlHttpRequest still performs HTTP requests under the hood,
-and then waits for a response, but the Javascript code can
-continue to run until the response arrives. It will then receive
-the response through a callback previously defined.
-
-This is of course still requests initiated by the client,
-the server still had no way of pushing data to the client
-on its own, so new technology appeared to allow that.
-
-=== Long-polling
-
-Polling was a technique used to overcome the fact that the server
-cannot push data directly to the client. Therefore the client had
-to repeatedly create a connection, make a request, get a response,
-then try again a few seconds later. This is overly expensive and
-adds an additional delay before the client receives the data.
-
-Polling was necessary to implement message queues and other
-similar mechanisms, where a user must be informed of something
-when it happens, rather than when he refreshes the page next.
-A typical example would be a chat application.
-
-Long-polling was created to reduce the server load by creating
-less connections, but also to improve latency by getting the
-response back to the client as soon as it becomes available
-on the server.
-
-Long-polling works in a similar manner to polling, except the
-request will not get a response immediately. Instead the server
-leaves it open until it has a response to send. After getting
-the response, the client creates a new request and gets back
-to waiting.
-
-You probably guessed by now that long-polling is a hack, and
-like most hacks it can suffer from unforeseen issues, in this
-case it doesn't always play well with proxies.
+=== HTTP/2
 
-=== HTML5
+HTTP/2 is the most efficient protocol for consuming Web
+services. It enables clients to keep a connection open
+for long periods of time; to send requests concurrently;
+to reduce the size of requests through HTTP headers
+compression; and more. The protocol is binary, greatly
+reducing the resources needed to parse it.
 
-HTML5 is, of course, the HTML version after HTML4. But HTML5
-emerged to solve a specific problem: dynamic web applications.
+HTTP/2 also enables the server to push messages to the
+client. This can be used for various purposes, including
+the sending of related resources before the client requests
+them, in an effort to reduce latency. This can also be used
+to enable bidirectional communication.
 
-HTML was initially created to write web pages which compose
-a website. But soon people and companies wanted to use HTML
-to write more and more complex websites, eventually known as
-web applications. They are for example your news reader, your
-email client in the browser, or your video streaming website.
+Cowboy provides transparent support for HTTP/2. Clients
+that know it can use it; others fall back to HTTP/1.1
+automatically.
 
-Because HTML wasn't enough, they started using proprietary
-solutions, often implemented using plug-ins. This wasn't
-perfect of course, but worked well enough for most people.
+HTTP/2 is compatible with the HTTP/1.1 semantics.
 
-However, the needs for a standard solution eventually became
-apparent. The browser needed to be able to play media natively.
-It needed to be able to draw anything. It needed an efficient
-way of streaming events to the server, but also receiving
-events from the server.
+HTTP/2 is defined by RFC 7540 and RFC 7541.
 
-The solution went on to become HTML5. At the time of writing
-it is being standardized.
+=== HTTP/1.1
 
-=== EventSource
+HTTP/1.1 is the previous version of the HTTP protocol.
+The protocol itself is text-based and suffers from numerous
+issues and limitations. In particular it is not possible
+to execute requests concurrently (though pipelining is
+sometimes possible), and it's also sometimes difficult
+to detect that a client disconnected.
 
-EventSource, sometimes also called Server-Sent Events, is a
-technology allowing servers to push data to HTML5 applications.
+HTTP/1.1 does provide very good semantics for interacting
+with Web services. It defines the standard methods, headers
+and status codes used by HTTP/1.1 and HTTP/2 clients and
+servers.
 
-EventSource is one-way communication channel from the server
-to the client. The client has no means to talk to the server
-other than by using HTTP requests.
+HTTP/1.1 also defines compatibility with an older version
+of the protocol, HTTP/1.0, which was never really standardized
+across implementations.
 
-It consists of a Javascript object allowing setting up an
-EventSource connection to the server, and a very small protocol
-for sending events to the client on top of the HTTP/1.1
-connection.
-
-EventSource is a lightweight solution that only works for
-UTF-8 encoded text data. Binary data and text data encoded
-differently are not allowed by the protocol. A heavier but
-more generic approach can be found in Websocket.
+The core of HTTP/1.1 is defined by RFC 7230, RFC 7231,
+RFC 7232, RFC 7233, RFC 7234 and RFC 7235. Numerous RFCs
+and other specifications exist defining additional HTTP
+methods, status codes, headers or semantics.
 
 === Websocket
 
@@ -180,21 +74,48 @@ A Websocket connection can be used to transfer any kind of data,
 small or big, text or binary. Because of this Websocket is
 sometimes used for communication between systems.
 
-=== HTTP/2
+Websocket messages have no semantics on their own. Websocket
+is closer to TCP in that aspect, and requires you to design
+and implement your own protocol on top of it; or adapt an
+existing protocol to Websocket.
+
+The Websocket protocol is defined by RFC 6455.
+
+=== Long-lived requests
+
+Cowboy provides an interface that can be used to support
+long-polling or to stream large amounts of data reliably,
+including using Server-Sent Events.
+
+Long-polling is a mechanism in which the client performs
+a request which may not be immediately answered by the
+server. It allows clients to request resources that may
+not currently exist, but are expected to be created soon,
+and which will be returned as soon as they are.
+
+Long-polling is essentially a hack, but it is widely used
+to overcome limitations on older clients and servers.
+
+Server-Sent Events is a small protocol defined as a media
+type, `text/event-stream`, along with a new HTTP header,
+`Last-Event-ID`. It is defined in the EventSource W3C
+specification.
+
+Cowboy provides an interface known as loop handlers that
+facilitates the implementation of long-polling or stream
+mechanisms. It works regardless of the underlying protocol.
+
+=== REST
+
+REST, or REpresentational State Transfer, is a style of
+architecture for loosely connected distributed systems.
+It can easily be implemented on top of HTTP.
+
+REST is essentially a set of constraints to be followed.
+Many of these constraints are purely architectural and
+solved by simply using HTTP. Some constraints must be
+explicitly followed by the developer.
 
-HTTP/2 is an attempt to reduce page loading time by opening a
-single connection per server, keeping it open for subsequent
-requests, and also by compressing the HTTP headers to reduce
-the size of requests.
-
-HTTP/2 is compatible with HTTP/1.1 semantics, and is actually
-just a different way of performing HTTP requests and responses,
-by using binary frames instead of a text-based protocol.
-HTTP/2 also allows the server to send extra responses following
-a request. This is meant to allow sending the resources
-associated with the request before the client requests them,
-saving latency when loading websites.
-
-Browsers make use of TLS Application-Layer Protocol Negotiation
-extension to upgrade to an HTTP/2 connection seamlessly if the
-server supports it.
+Cowboy provides an interface known as REST handlers that
+simplifies the implementation of a REST API on top of
+the HTTP protocol.