From b5a40256ddd5585d12c2a01771eb93d4a8630a62 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Tue, 24 May 2016 14:50:27 +0200 Subject: Partial update of the user guide I will do more breaking changes before documenting more. --- doc/src/guide/modern_web.asciidoc | 245 +++++++++++++------------------------- 1 file changed, 83 insertions(+), 162 deletions(-) (limited to 'doc/src/guide/modern_web.asciidoc') 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. -- cgit v1.2.3