/*
 * Copyright 2014 Red Hat, Inc.
 *
 *  All rights reserved. This program and the accompanying materials
 *  are made available under the terms of the Eclipse Public License v1.0
 *  and Apache License v2.0 which accompanies this distribution.
 *
 *  The Eclipse Public License is available at
 *  http://www.eclipse.org/legal/epl-v10.html
 *
 *  The Apache License v2.0 is available at
 *  http://www.opensource.org/licenses/apache2.0.php
 *
 *  You may elect to redistribute this code under either of these licenses.
 */

/**
 * == Writing HTTP servers and clients
 *
 * Vert.x allows you to easily write non blocking HTTP clients and servers.
 *
 * Vert.x supports the HTTP/1.0, HTTP/1.1 and HTTP/2 protocols.
 *
 * The base API for HTTP is the same for HTTP/1.x and HTTP/2, specific API features are available for dealing with the
 * HTTP/2 protocol.
 *
 * === Creating an HTTP Server
 *
 * The simplest way to create an HTTP server, using all default options is as follows:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example1}
 * ----
 *
 * === Configuring an HTTP server
 *
 * If you don't want the default, a server can be configured by passing in a {@link io.vertx.core.http.HttpServerOptions}
 * instance when creating it:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example2}
 * ----
 *
 * === Configuring an HTTP/2 server
 *
 * Vert.x supports HTTP/2 over TLS `h2` and over TCP `h2c`.
 *
 * - `h2` identifies the HTTP/2 protocol when used over TLS negotiated by https://en.wikipedia.org/wiki/Application-Layer_Protocol_Negotiation[Application-Layer Protocol Negotiation] (ALPN)
 * - `h2c` identifies the HTTP/2 protocol when using in clear text over TCP, such connections are established either with
 * an HTTP/1.1 upgraded request or directly
 *
 * To handle `h2` requests, TLS must be enabled along with {@link io.vertx.core.http.HttpServerOptions#setUseAlpn(boolean)}:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#example0}
 * ----
 *
 * ALPN is a TLS extension that negotiates the protocol before the client and the server start to exchange data.
 *
 * Clients that don't support ALPN will still be able to do a _classic_ SSL handshake.
 *
 * ALPN will usually agree on the `h2` protocol, although `http/1.1` can be used if the server or the client decides
 * so.
 *
 * To handle `h2c` requests, TLS must be disabled, the server will upgrade to HTTP/2 any request HTTP/1.1 that wants to
 * upgrade to HTTP/2. It will also accept a direct `h2c` connection beginning with the `PRI * HTTP/2.0\r\nSM\r\n` preface.
 *
 * WARNING: most browsers won't support `h2c`, so for serving web sites you should use `h2` and not `h2c`.
 *
 * When a server accepts an HTTP/2 connection, it sends to the client its {@link io.vertx.core.http.HttpServerOptions#getInitialSettings initial settings}.
 * The settings define how the client can use the connection, the default initial settings for a server are:
 *
 * - {@link io.vertx.core.http.Http2Settings#getMaxConcurrentStreams}: {@code 100} as recommended by the HTTP/2 RFC
 * - the default HTTP/2 settings values for the others
 *
 * NOTE: Worker Verticles are not compatible with HTTP/2
 *
 * === Logging network server activity
 *
 * For debugging purposes, network activity can be logged.
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#exampleServerLogging}
 * ----
 *
 * See the chapter on <<logging_network_activity, logging network activity>> for a detailed explanation.
 *
 * === Start the Server Listening
 *
 * To tell the server to listen for incoming requests you use one of the {@link io.vertx.core.http.HttpServer#listen}
 * alternatives.
 *
 * To tell the server to listen at the host and port as specified in the options:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example3}
 * ----
 *
 * Or to specify the host and port in the call to listen, ignoring what is configured in the options:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example4}
 * ----
 *
 * The default host is `0.0.0.0` which means 'listen on all available addresses' and the default port is `80`.
 *
 * The actual bind is asynchronous so the server might not actually be listening until some time *after* the call to
 * listen has returned.
 *
 * If you want to be notified when the server is actually listening you can provide a handler to the `listen` call.
 * For example:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example5}
 * ----
 *
 * === Getting notified of incoming requests
 *
 * To be notified when a request arrives you need to set a {@link io.vertx.core.http.HttpServer#requestHandler}:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example6}
 * ----
 *
 * === Handling requests
 *
 * When a request arrives, the request handler is called passing in an instance of {@link io.vertx.core.http.HttpServerRequest}.
 * This object represents the server side HTTP request.
 *
 * The handler is called when the headers of the request have been fully read.
 *
 * If the request contains a body, that body will arrive at the server some time after the request handler has been called.
 *
 * The server request object allows you to retrieve the {@link io.vertx.core.http.HttpServerRequest#uri},
 * {@link io.vertx.core.http.HttpServerRequest#path}, {@link io.vertx.core.http.HttpServerRequest#params} and
 * {@link io.vertx.core.http.HttpServerRequest#headers}, amongst other things.
 *
 * Each server request object is associated with one server response object. You use
 * {@link io.vertx.core.http.HttpServerRequest#response} to get a reference to the {@link io.vertx.core.http.HttpServerResponse}
 * object.
 *
 * Here's a simple example of a server handling a request and replying with "hello world" to it.
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example7_1}
 * ----
 *
 * ==== Request version
 *
 * The version of HTTP specified in the request can be retrieved with {@link io.vertx.core.http.HttpServerRequest#version}
 *
 * ==== Request method
 *
 * Use {@link io.vertx.core.http.HttpServerRequest#method} to retrieve the HTTP method of the request.
 * (i.e. whether it's GET, POST, PUT, DELETE, HEAD, OPTIONS, etc).
 *
 * ==== Request URI
 *
 * Use {@link io.vertx.core.http.HttpServerRequest#uri} to retrieve the URI of the request.
 *
 * Note that this is the actual URI as passed in the HTTP request, and it's almost always a relative URI.
 *
 * The URI is as defined in http://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html[Section 5.1.2 of the HTTP specification - Request-URI]
 *
 * ==== Request path
 *
 * Use {@link io.vertx.core.http.HttpServerRequest#path} to return the path part of the URI
 *
 * For example, if the request URI was:
 *
 *  a/b/c/page.html?param1=abc&param2=xyz
 *
 * Then the path would be
 *
 *  /a/b/c/page.html
 *
 * ==== Request query
 *
 * Use {@link io.vertx.core.http.HttpServerRequest#query} to return the query part of the URI
 *
 * For example, if the request URI was:
 *
 *  a/b/c/page.html?param1=abc&param2=xyz
 *
 * Then the query would be
 *
 *  param1=abc&param2=xyz
 *
 * ==== Request headers
 *
 * Use {@link io.vertx.core.http.HttpServerRequest#headers} to return the headers of the HTTP request.
 *
 * This returns an instance of {@link io.vertx.core.MultiMap} - which is like a normal Map or Hash but allows multiple
 * values for the same key - this is because HTTP allows multiple header values with the same key.
 *
 * It also has case-insensitive keys, that means you can do the following:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example8}
 * ----
 *
 * ==== Request host
 *
 * Use {@link io.vertx.core.http.HttpServerRequest#host} to return the host of the HTTP request.
 *
 * For HTTP/1.x requests the `host` header is returned, for HTTP/1 requests the `:authority` pseudo header is returned.
 *
 * ==== Request parameters
 *
 * Use {@link io.vertx.core.http.HttpServerRequest#params} to return the parameters of the HTTP request.
 *
 * Just like {@link io.vertx.core.http.HttpServerRequest#headers} this returns an instance of {@link io.vertx.core.MultiMap}
 * as there can be more than one parameter with the same name.
 *
 * Request parameters are sent on the request URI, after the path. For example if the URI was:
 *
 *  /page.html?param1=abc&param2=xyz
 *
 * Then the parameters would contain the following:
 *
 * ----
 * param1: 'abc'
 * param2: 'xyz
 * ----
 *
 * Note that these request parameters are retrieved from the URL of the request. If you have form attributes that
 * have been sent as part of the submission of an HTML form submitted in the body of a `multi-part/form-data` request
 * then they will not appear in the params here.
 *
 * ==== Remote address
 *
 * The address of the sender of the request can be retrieved with {@link io.vertx.core.http.HttpServerRequest#remoteAddress}.
 *
 * ==== Absolute URI
 *
 * The URI passed in an HTTP request is usually relative. If you wish to retrieve the absolute URI corresponding
 * to the request, you can get it with {@link io.vertx.core.http.HttpServerRequest#absoluteURI}
 *
 * ==== End handler
 *
 * The {@link io.vertx.core.http.HttpServerRequest#endHandler} of the request is invoked when the entire request,
 * including any body has been fully read.
 *
 * ==== Reading Data from the Request Body
 *
 * Often an HTTP request contains a body that we want to read. As previously mentioned the request handler is called
 * when just the headers of the request have arrived so the request object does not have a body at that point.
 *
 * This is because the body may be very large (e.g. a file upload) and we don't generally want to buffer the entire
 * body in memory before handing it to you, as that could cause the server to exhaust available memory.
 *
 * To receive the body, you can use the {@link io.vertx.core.http.HttpServerRequest#handler}  on the request,
 * this will get called every time a chunk of the request body arrives. Here's an example:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example9}
 * ----
 *
 * The object passed into the handler is a {@link io.vertx.core.buffer.Buffer}, and the handler can be called
 * multiple times as data arrives from the network, depending on the size of the body.
 *
 * In some cases (e.g. if the body is small) you will want to aggregate the entire body in memory, so you could do
 * the aggregation yourself as follows:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example10}
 * ----
 *
 * This is such a common case, that Vert.x provides a {@link io.vertx.core.http.HttpServerRequest#bodyHandler} to do this
 * for you. The body handler is called once when all the body has been received:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example11}
 * ----
 *
 * ==== Pumping requests
 *
 * The request object is a {@link io.vertx.core.streams.ReadStream} so you can pump the request body to any
 * {@link io.vertx.core.streams.WriteStream} instance.
 *
 * See the chapter on <<streams, streams and pumps>> for a detailed explanation.
 *
 * ==== Handling HTML forms
 *
 * HTML forms can be submitted with either a content type of `application/x-www-form-urlencoded` or `multipart/form-data`.
 *
 * For url encoded forms, the form attributes are encoded in the url, just like normal query parameters.
 *
 * For multi-part forms they are encoded in the request body, and as such are not available until the entire body
 * has been read from the wire.
 *
 * Multi-part forms can also contain file uploads.
 *
 * If you want to retrieve the attributes of a multi-part form you should tell Vert.x that you expect to receive
 * such a form *before* any of the body is read by calling {@link io.vertx.core.http.HttpServerRequest#setExpectMultipart}
 * with true, and then you should retrieve the actual attributes using {@link io.vertx.core.http.HttpServerRequest#formAttributes}
 * once the entire body has been read:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example12}
 * ----
 *
 * ==== Handling form file uploads
 *
 * Vert.x can also handle file uploads which are encoded in a multi-part request body.
 *
 * To receive file uploads you tell Vert.x to expect a multi-part form and set an
 * {@link io.vertx.core.http.HttpServerRequest#uploadHandler} on the request.
 *
 * This handler will be called once for every
 * upload that arrives on the server.
 *
 * The object passed into the handler is a {@link io.vertx.core.http.HttpServerFileUpload} instance.
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example13}
 * ----
 *
 * File uploads can be large we don't provide the entire upload in a single buffer as that might result in memory
 * exhaustion, instead, the upload data is received in chunks:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example14}
 * ----
 *
 * The upload object is a {@link io.vertx.core.streams.ReadStream} so you can pump the request body to any
 * {@link io.vertx.core.streams.WriteStream} instance. See the chapter on <<streams, streams and pumps>> for a
 * detailed explanation.
 *
 * If you just want to upload the file to disk somewhere you can use {@link io.vertx.core.http.HttpServerFileUpload#streamToFileSystem}:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example15}
 * ----
 *
 * WARNING: Make sure you check the filename in a production system to avoid malicious clients uploading files
 * to arbitrary places on your filesystem. See <<Security notes, security notes>> for more information.
 *
 * ==== Handling compressed body
 *
 * Vert.x can handle compressed body payloads which are encoded by the client with the _deflate_ or _gzip_
 * algorithms.
 *
 * To enable decompression set {@link io.vertx.core.http.HttpServerOptions#setDecompressionSupported(boolean)} on the
 * options when creating the server.
 *
 * By default decompression is disabled.
 *
 * ==== Receiving custom HTTP/2 frames
 *
 * HTTP/2 is a framed protocol with various frames for the HTTP request/response model. The protocol allows other kind
 * of frames to be sent and received.
 *
 * To receive custom frames, you can use the {@link io.vertx.core.http.HttpServerRequest#customFrameHandler} on the request,
 * this will get called every time a custom frame arrives. Here's an example:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#example1}
 * ----
 *
 * HTTP/2 frames are not subject to flow control - the frame handler will be called immediatly when a
 * custom frame is received whether the request is paused or is not
 *
 * ==== Non standard HTTP methods
 *
 * The {@link io.vertx.core.http.HttpMethod#OTHER} HTTP method is used for non standard methods, in this case
 * {@link io.vertx.core.http.HttpServerRequest#rawMethod()} returns the HTTP method as sent by the client.
 *
 * === Sending back responses
 *
 * The server response object is an instance of {@link io.vertx.core.http.HttpServerResponse} and is obtained from the
 * request with {@link io.vertx.core.http.HttpServerRequest#response}.
 *
 * You use the response object to write a response back to the HTTP client.
 *
 * ==== Setting status code and message
 *
 * The default HTTP status code for a response is `200`, representing `OK`.
 *
 * Use {@link io.vertx.core.http.HttpServerResponse#setStatusCode} to set a different code.
 *
 * You can also specify a custom status message with {@link io.vertx.core.http.HttpServerResponse#setStatusMessage}.
 *
 * If you don't specify a status message, the default one corresponding to the status code will be used.
 *
 * NOTE: for HTTP/2 the status won't be present in the response since the protocol won't transmit the message
 * to the client
 *
 * ==== Writing HTTP responses
 *
 * To write data to an HTTP response, you use one the {@link io.vertx.core.http.HttpServerResponse#write} operations.
 *
 * These can be invoked multiple times before the response is ended. They can be invoked in a few ways:
 *
 * With a single buffer:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example16}
 * ----
 *
 * With a string. In this case the string will encoded using UTF-8 and the result written to the wire.
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example17}
 * ----
 *
 * With a string and an encoding. In this case the string will encoded using the specified encoding and the
 * result written to the wire.
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example18}
 * ----
 *
 * Writing to a response is asynchronous and always returns immediately after the write has been queued.
 *
 * If you are just writing a single string or buffer to the HTTP response you can write it and end the response in a
 * single call to the {@link io.vertx.core.http.HttpServerResponse#end(String)}
 *
 * The first call to write results in the response header being being written to the response. Consequently, if you are
 * not using HTTP chunking then you must set the `Content-Length` header before writing to the response, since it will
 * be too late otherwise. If you are using HTTP chunking you do not have to worry.
 *
 * ==== Ending HTTP responses
 *
 * Once you have finished with the HTTP response you should {@link io.vertx.core.http.HttpServerResponse#end} it.
 *
 * This can be done in several ways:
 *
 * With no arguments, the response is simply ended.
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example19}
 * ----
 *
 * It can also be called with a string or buffer in the same way `write` is called. In this case it's just the same as
 * calling write with a string or buffer followed by calling end with no arguments. For example:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example20}
 * ----
 *
 * ==== Closing the underlying connection
 *
 * You can close the underlying TCP connection with {@link io.vertx.core.http.HttpServerResponse#close}.
 *
 * Non keep-alive connections will be automatically closed by Vert.x when the response is ended.
 *
 * Keep-alive connections are not automatically closed by Vert.x by default. If you want keep-alive connections to be
 * closed after an idle time, then you configure {@link io.vertx.core.http.HttpServerOptions#setIdleTimeout}.
 *
 * HTTP/2 connections send a {@literal GOAWAY} frame before closing the response.
 *
 * ==== Setting response headers
 *
 * HTTP response headers can be added to the response by adding them directly to the
 * {@link io.vertx.core.http.HttpServerResponse#headers}:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example21}
 * ----
 *
 * Or you can use {@link io.vertx.core.http.HttpServerResponse#putHeader}
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example22}
 * ----
 *
 * Headers must all be added before any parts of the response body are written.
 *
 * ==== Chunked HTTP responses and trailers
 *
 * Vert.x supports http://en.wikipedia.org/wiki/Chunked_transfer_encoding[HTTP Chunked Transfer Encoding].
 *
 * This allows the HTTP response body to be written in chunks, and is normally used when a large response body is
 * being streamed to a client and the total size is not known in advance.
 *
 * You put the HTTP response into chunked mode as follows:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example23}
 * ----
 *
 * Default is non-chunked. When in chunked mode, each call to one of the {@link io.vertx.core.http.HttpServerResponse#write}
 * methods will result in a new HTTP chunk being written out.
 *
 * When in chunked mode you can also write HTTP response trailers to the response. These are actually written in
 * the final chunk of the response.
 *
 * NOTE: chunked response has no effect for an HTTP/2 stream
 *
 * To add trailers to the response, add them directly to the {@link io.vertx.core.http.HttpServerResponse#trailers}.
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example24}
 * ----
 *
 * Or use {@link io.vertx.core.http.HttpServerResponse#putTrailer}.
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example25}
 * ----
 *
 * ==== Serving files directly from disk or the classpath
 *
 * If you were writing a web server, one way to serve a file from disk would be to open it as an {@link io.vertx.core.file.AsyncFile}
 * and pump it to the HTTP response.
 *
 * Or you could load it it one go using {@link io.vertx.core.file.FileSystem#readFile} and write it straight to the response.
 *
 * Alternatively, Vert.x provides a method which allows you to serve a file from disk or the filesystem to an HTTP response 
 * in one operation.
 * Where supported by the underlying operating system this may result in the OS directly transferring bytes from the
 * file to the socket without being copied through user-space at all.
 *
 * This is done by using {@link io.vertx.core.http.HttpServerResponse#sendFile}, and is usually more efficient for large
 * files, but may be slower for small files.
 *
 * Here's a very simple web server that serves files from the file system using sendFile:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example26}
 * ----
 *
 * Sending a file is asynchronous and may not complete until some time after the call has returned. If you want to
 * be notified when the file has been writen you can use {@link io.vertx.core.http.HttpServerResponse#sendFile(String, io.vertx.core.Handler)}
 *
 * Please see the chapter about <<classpath, serving files from the classpath>> for restrictions about the classpath resolution or disabling it.
 *
 * NOTE: If you use `sendFile` while using HTTPS it will copy through user-space, since if the kernel is copying data
 * directly from disk to socket it doesn't give us an opportunity to apply any encryption.
 *
 * WARNING: If you're going to write web servers directly using Vert.x be careful that users cannot exploit the
 * path to access files outside the directory from which you want to serve them or the classpath It may be safer instead to use
 * Vert.x Web. 
 *
 * When there is a need to serve just a segment of a file, say starting from a given byte, you can achieve this by doing:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example26b}
 * ----
 *
 * You are not required to supply the length if you want to send a file starting from an offset until the end, in this
 * case you can just do:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example26c}
 * ----
 *
 * ==== Pumping responses
 *
 * The server response is a {@link io.vertx.core.streams.WriteStream} instance so you can pump to it from any
 * {@link io.vertx.core.streams.ReadStream}, e.g. {@link io.vertx.core.file.AsyncFile}, {@link io.vertx.core.net.NetSocket},
 * {@link io.vertx.core.http.WebSocket} or {@link io.vertx.core.http.HttpServerRequest}.
 *
 * Here's an example which echoes the request body back in the response for any PUT methods.
 * It uses a pump for the body, so it will work even if the HTTP request body is much larger than can fit in memory
 * at any one time:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example27}
 * ----
 *
 * ==== Writing HTTP/2 frames
 *
 * HTTP/2 is a framed protocol with various frames for the HTTP request/response model. The protocol allows other kind
 * of frames to be sent and received.
 *
 * To send such frames, you can use the {@link io.vertx.core.http.HttpServerResponse#writeCustomFrame} on the response.
 * Here's an example:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#example2}
 * ----
 *
 * These frames are sent immediately and are not subject to flow control - when such frame is sent there it may be done
 * before other {@literal DATA} frames.
 *
 * ==== Stream reset
 *
 * HTTP/1.x does not allow a clean reset of a request or a response stream, for example when a client uploads
 * a resource already present on the server, the server needs to accept the entire response.
 *
 * HTTP/2 supports stream reset at any time during the request/response:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#example3}
 * ----
 *
 * By default the `NO_ERROR` (0) error code is sent, another code can sent instead:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#example4}
 * ----
 *
 * The HTTP/2 specification defines the list of http://httpwg.org/specs/rfc7540.html#ErrorCodes[error codes] one can use.
 *
 * The request handler are notified of stream reset events with the {@link io.vertx.core.http.HttpServerRequest#exceptionHandler request handler} and
 * {@link io.vertx.core.http.HttpServerResponse#exceptionHandler response handler}:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#example5}
 * ----
 *
 * ==== Server push
 *
 * Server push is a new feature of HTTP/2 that enables sending multiple responses in parallel for a single client request.
 *
 * When a server process a request, it can push a request/response to the client:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#example6}
 * ----
 *
 * When the server is ready to push the response, the push response handler is called and the handler can send the response.
 *
 * The push response handler may receive a failure, for instance the client may cancel the push because it already has `main.js` in its
 * cache and does not want it anymore.
 *
 * The {@link io.vertx.core.http.HttpServerResponse#push} method must be called before the initiating response ends, however
 * the pushed response can be written after.
 *
 * === HTTP Compression
 *
 * Vert.x comes with support for HTTP Compression out of the box.
 *
 * This means you are able to automatically compress the body of the responses before they are sent back to the client.
 *
 * If the client does not support HTTP compression the responses are sent back without compressing the body.
 *
 * This allows to handle Client that support HTTP Compression and those that not support it at the same time.
 *
 * To enable compression use can configure it with {@link io.vertx.core.http.HttpServerOptions#setCompressionSupported}.
 *
 * By default compression is not enabled.
 *
 * When HTTP compression is enabled the server will check if the client includes an `Accept-Encoding` header which
 * includes the supported compressions. Commonly used are deflate and gzip. Both are supported by Vert.x.
 *
 * If such a header is found the server will automatically compress the body of the response with one of the supported
 * compressions and send it back to the client.
 *
 * Be aware that compression may be able to reduce network traffic but is more CPU-intensive.
 * 
 * To address this latter issue Vert.x allows you to tune the 'compression level' parameter that is native of the gzip/deflate compression algorithms. 
 * 
 * Compression level allows to configure gizp/deflate algorithms in terms of the compression ratio of the resulting data and the computational cost of the compress/decompress operation. 
 * 
 * The compression level is an integer value ranged from '1' to '9', where '1' means lower compression ratio but fastest algorithm and '9' means maximum compression ratio available but a slower algorithm. 
 * 
 * Using compression levels higher that 1-2 usually allows to save just some bytes in size - the gain is not linear, and depends on the specific data to be compressed 
 * - but it comports a non-trascurable cost in term of CPU cycles required to the server while generating the compressed response data 
 * ( Note that at moment Vert.x doesn't support any form caching of compressed response data, even for static files, so the compression is done on-the-fly 
 * at every request body generation ) and in the same way it affects client(s) while decoding (inflating) received responses, operation that becomes more CPU-intensive 
 * the more the level increases.
 * 
 * By default - if compression is enabled via {@link io.vertx.core.http.HttpServerOptions#setCompressionSupported} - Vert.x will use '6' as compression level,
 * but the parameter can be configured to address any case with {@link io.vertx.core.http.HttpServerOptions#setCompressionLevel}.
 *
 * === Creating an HTTP client
 *
 * You create an {@link io.vertx.core.http.HttpClient} instance with default options as follows:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example28}
 * ----
 *
 * If you want to configure options for the client, you create it as follows:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example29}
 * ----
 *
 * Vert.x supports HTTP/2 over TLS `h2` and over TCP `h2c`.
 *
 * By default the http client performs HTTP/1.1 requests, to perform HTTP/2 requests the {@link io.vertx.core.http.HttpClientOptions#setProtocolVersion}
 * must be set to {@link io.vertx.core.http.HttpVersion#HTTP_2}.
 *
 * For `h2` requests, TLS must be enabled with _Application-Layer Protocol Negotiation_:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#example7}
 * ----
 *
 * For `h2c` requests, TLS must be disabled, the client will do an HTTP/1.1 requests and try an upgrade to HTTP/2:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#example8}
 * ----
 *
 * `h2c` connections can also be established directly, i.e connection started with a prior knowledge, when
 * {@link io.vertx.core.http.HttpClientOptions#setHttp2ClearTextUpgrade(boolean)} options is set to false: after the
 * connection is established, the client will send the HTTP/2 connection preface and expect to receive
 * the same preface from the server.
 *
 * The http server may not support HTTP/2, the actual version can be checked
 * with {@link io.vertx.core.http.HttpClientResponse#version()} when the response arrives.
 *
 * When a clients connects to an HTTP/2 server, it sends to the server its {@link io.vertx.core.http.HttpClientOptions#getInitialSettings initial settings}.
 * The settings define how the server can use the connection, the default initial settings for a client are the default
 * values defined by the HTTP/2 RFC.
 *
 * === Logging network client activity
 *
 * For debugging purposes, network activity can be logged.
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#exampleClientLogging}
 * ----
 *
 * See the chapter on <<logging_network_activity, logging network activity>> for a detailed explanation.
 *
 * === Making requests
 *
 * The http client is very flexible and there are various ways you can make requests with it.
 *
 *
 * Often you want to make many requests to the same host/port with an http client. To avoid you repeating the host/port
 * every time you make a request you can configure the client with a default host/port:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example30}
 * ----
 *
 * Alternatively if you find yourself making lots of requests to different host/ports with the same client you can
 * simply specify the host/port when doing the request.
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example31}
 * ----
 *
 * Both methods of specifying host/port are supported for all the different ways of making requests with the client.
 *
 * ==== Simple requests with no request body
 *
 * Often, you'll want to make HTTP requests with no request body. This is usually the case with HTTP GET, OPTIONS and
 * HEAD requests.
 *
 * The simplest way to do this with the Vert.x http client is using the methods prefixed with `Now`. For example
 * {@link io.vertx.core.http.HttpClient#getNow}.
 *
 * These methods create the http request and send it in a single method call and allow you to provide a handler that will be
 * called with the http response when it comes back.
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example32}
 * ----
 *
 * ==== Writing general requests
 *
 * At other times you don't know the request method you want to send until run-time. For that use case we provide
 * general purpose request methods such as {@link io.vertx.core.http.HttpClient#request} which allow you to specify
 * the HTTP method at run-time:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example33}
 * ----
 *
 * ==== Writing request bodies
 *
 * Sometimes you'll want to write requests which have a body, or perhaps you want to write headers to a request
 * before sending it.
 *
 * To do this you can call one of the specific request methods such as {@link io.vertx.core.http.HttpClient#post} or
 * one of the general purpose request methods such as {@link io.vertx.core.http.HttpClient#request}.
 *
 * These methods don't send the request immediately, but instead return an instance of {@link io.vertx.core.http.HttpClientRequest}
 * which can be used to write to the request body or write headers.
 *
 * Here are some examples of writing a POST request with a body:
 *m
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example34}
 * ----
 *
 * Methods exist to write strings in UTF-8 encoding and in any specific encoding and to write buffers:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example35}
 * ----
 *
 * If you are just writing a single string or buffer to the HTTP request you can write it and end the request in a
 * single call to the `end` function.
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example36}
 * ----
 *
 * When you're writing to a request, the first call to `write` will result in the request headers being written
 * out to the wire.
 *
 * The actual write is asynchronous and might not occur until some time after the call has returned.
 *
 * Non-chunked HTTP requests with a request body require a `Content-Length` header to be provided.
 *
 * Consequently, if you are not using chunked HTTP then you must set the `Content-Length` header before writing
 * to the request, as it will be too late otherwise.
 *
 * If you are calling one of the `end` methods that take a string or buffer then Vert.x will automatically calculate
 * and set the `Content-Length` header before writing the request body.
 *
 * If you are using HTTP chunking a a `Content-Length` header is not required, so you do not have to calculate the size
 * up-front.
 *
 * ==== Writing request headers
 *
 * You can write headers to a request using the {@link io.vertx.core.http.HttpClientRequest#headers()} multi-map as follows:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example37}
 * ----
 *
 * The headers are an instance of {@link io.vertx.core.MultiMap} which provides operations for adding, setting and removing
 * entries. Http headers allow more than one value for a specific key.
 *
 * You can also write headers using {@link io.vertx.core.http.HttpClientRequest#putHeader}
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example38}
 * ----
 *
 * If you wish to write headers to the request you must do so before any part of the request body is written.
 *
 * ==== Non standard HTTP methods
 *
 * The {@link io.vertx.core.http.HttpMethod#OTHER} HTTP method is used for non standard methods, when this method
 * is used, {@link io.vertx.core.http.HttpClientRequest#setRawMethod(java.lang.String)} must be used to
 * set the raw method to send to the server.
 *
 * ==== Ending HTTP requests
 *
 * Once you have finished with the HTTP request you must end it with one of the {@link io.vertx.core.http.HttpClientRequest#end}
 * operations.
 *
 * Ending a request causes any headers to be written, if they have not already been written and the request to be marked
 * as complete.
 *
 * Requests can be ended in several ways. With no arguments the request is simply ended:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example39}
 * ----
 *
 * Or a string or buffer can be provided in the call to `end`. This is like calling `write` with the string or buffer
 * before calling `end` with no arguments
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example40}
 * ----
 *
 * ==== Chunked HTTP requests
 *
 * Vert.x supports http://en.wikipedia.org/wiki/Chunked_transfer_encoding[HTTP Chunked Transfer Encoding] for requests.
 *
 * This allows the HTTP request body to be written in chunks, and is normally used when a large request body is being streamed
 * to the server, whose size is not known in advance.
 *
 * You put the HTTP request into chunked mode using {@link io.vertx.core.http.HttpClientRequest#setChunked(boolean)}.
 *
 * In chunked mode each call to write will cause a new chunk to be written to the wire. In chunked mode there is
 * no need to set the `Content-Length` of the request up-front.
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example41}
 * ----
 *
 * ==== Request timeouts
 *
 * You can set a timeout for a specific http request using {@link io.vertx.core.http.HttpClientRequest#setTimeout(long)}.
 *
 * If the request does not return any data within the timeout period an exception will be passed to the exception handler
 * (if provided) and the request will be closed.
 *
 * ==== Handling exceptions
 *
 * You can handle exceptions corresponding to a request by setting an exception handler on the
 * {@link io.vertx.core.http.HttpClientRequest} instance:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example42}
 * ----
 *
 * This does not handle non _2xx_ response that need to be handled in the
 * {@link io.vertx.core.http.HttpClientResponse} code:
 *
 * [source, $lang]
 * ----
 * {@link examples.HTTPExamples#statusCodeHandling}
 * ----
 *
 * IMPORTANT: `XXXNow` methods cannot receive an exception handler.
 *
 * ==== Specifying a handler on the client request
 *
 * Instead of providing a response handler in the call to create the client request object, alternatively, you can
 * not provide a handler when the request is created and set it later on the request object itself, using
 * {@link io.vertx.core.http.HttpClientRequest#handler(io.vertx.core.Handler)}, for example:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example43}
 * ----
 *
 * ==== Using the request as a stream
 *
 * The {@link io.vertx.core.http.HttpClientRequest} instance is also a {@link io.vertx.core.streams.WriteStream} which means
 * you can pump to it from any {@link io.vertx.core.streams.ReadStream} instance.
 *
 * For, example, you could pump a file on disk to a http request body as follows:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example44}
 * ----
 *
 * ==== Writing HTTP/2 frames
 *
 * HTTP/2 is a framed protocol with various frames for the HTTP request/response model. The protocol allows other kind
 * of frames to be sent and received.
 *
 * To send such frames, you can use the {@link io.vertx.core.http.HttpClientRequest#write} on the request. Here's an example:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#example9}
 * ----
 *
 * ==== Stream reset
 *
 * HTTP/1.x does not allow a clean reset of a request or a response stream, for example when a client uploads a resource already
 * present on the server, the server needs to accept the entire response.
 *
 * HTTP/2 supports stream reset at any time during the request/response:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#example10}
 * ----
 *
 * By default the NO_ERROR (0) error code is sent, another code can sent instead:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#example11}
 * ----
 *
 * The HTTP/2 specification defines the list of http://httpwg.org/specs/rfc7540.html#ErrorCodes[error codes] one can use.
 *
 * The request handler are notified of stream reset events with the {@link io.vertx.core.http.HttpClientRequest#exceptionHandler request handler} and
 * {@link io.vertx.core.http.HttpClientResponse#exceptionHandler response handler}:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#example12}
 * ----
 *
 * === Handling http responses
 *
 * You receive an instance of {@link io.vertx.core.http.HttpClientResponse} into the handler that you specify in of
 * the request methods or by setting a handler directly on the {@link io.vertx.core.http.HttpClientRequest} object.
 *
 * You can query the status code and the status message of the response with {@link io.vertx.core.http.HttpClientResponse#statusCode}
 * and {@link io.vertx.core.http.HttpClientResponse#statusMessage}.
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example45}
 * ----
 *
 * ==== Using the response as a stream
 *
 * The {@link io.vertx.core.http.HttpClientResponse} instance is also a {@link io.vertx.core.streams.ReadStream} which means
 * you can pump it to any {@link io.vertx.core.streams.WriteStream} instance.
 *
 * ==== Response headers and trailers
 *
 * Http responses can contain headers. Use {@link io.vertx.core.http.HttpClientResponse#headers} to get the headers.
 *
 * The object returned is a {@link io.vertx.core.MultiMap} as HTTP headers can contain multiple values for single keys.
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example46}
 * ----
 *
 * Chunked HTTP responses can also contain trailers - these are sent in the last chunk of the response body.
 *
 * You use {@link io.vertx.core.http.HttpClientResponse#trailers} to get the trailers. Trailers are also a {@link io.vertx.core.MultiMap}.
 *
 * ==== Reading the request body
 *
 * The response handler is called when the headers of the response have been read from the wire.
 *
 * If the response has a body this might arrive in several pieces some time after the headers have been read. We
 * don't wait for all the body to arrive before calling the response handler as the response could be very large and we
 * might be waiting a long time, or run out of memory for large responses.
 *
 * As parts of the response body arrive, the {@link io.vertx.core.http.HttpClientResponse#handler} is called with
 * a {@link io.vertx.core.buffer.Buffer} representing the piece of the body:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example47}
 * ----
 *
 * If you know the response body is not very large and want to aggregate it all in memory before handling it, you can
 * either aggregate it yourself:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example48}
 * ----
 *
 * Or you can use the convenience {@link io.vertx.core.http.HttpClientResponse#bodyHandler(io.vertx.core.Handler)} which
 * is called with the entire body when the response has been fully read:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example49}
 * ----
 *
 * ==== Response end handler
 *
 * The response {@link io.vertx.core.http.HttpClientResponse#endHandler} is called when the entire response body has been read
 * or immediately after the headers have been read and the response handler has been called if there is no body.
 *
 * ==== Reading cookies from the response
 *
 * You can retrieve the list of cookies from a response using {@link io.vertx.core.http.HttpClientResponse#cookies()}.
 *
 * Alternatively you can just parse the `Set-Cookie` headers yourself in the response.
 *
 * ==== 30x redirection handling
 *
 * The client can be configured to follow HTTP redirections: when the client receives an
 * `301`, `302`, `303` or `307` status code, it follows the redirection provided by the `Location` response header
 * and the response handler is passed the redirected response instead of the original response.
 *
 * Here's an example:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#exampleFollowRedirect01}
 * ----
 *
 * The redirection policy is as follow
 *
 * * on a `301`, `302` or `303` status code, follow the redirection with a `GET` method
 * * on a `307` status code, follow the redirection with the same HTTP method and the cached body
 *
 * WARNING: following redirections caches the request body
 *
 * The maximum redirects is `16` by default and can be changed with {@link io.vertx.core.http.HttpClientOptions#setMaxRedirects(int)}.
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#exampleFollowRedirect02}
 * ----
 *
 * One size does not fit all and the default redirection policy may not be adapted to your needs.
 *
 * The default redirection policy can changed with a custom implementation:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#exampleFollowRedirect03}
 * ----
 *
 * The policy handles the original {@link io.vertx.core.http.HttpClientResponse} received and returns either `null`
 * or a `Future<HttpClientRequest>`.
 *
 * - when `null` is returned, the original response is processed
 * - when a future is returned, the request will be sent on its successful completion
 * - when a future is returned, the exception handler set on the request is called on its failure
 *
 * The returned request must be unsent so the original request handlers can be sent and the client can send it after.
 *
 * Most of the original request settings will be propagated to the new request:
 *
 * * request headers, unless if you have set some headers (including {@link io.vertx.core.http.HttpClientRequest#setHost})
 * * request body unless the returned request uses a `GET` method
 * * response handler
 * * request exception handler
 * * request timeout
 *
 * ==== 100-Continue handling
 *
 * According to the http://www.w3.org/Protocols/rfc2616/rfc2616-sec8.html[HTTP 1.1 specification] a client can set a
 * header `Expect: 100-Continue` and send the request header before sending the rest of the request body.
 *
 * The server can then respond with an interim response status `Status: 100 (Continue)` to signify to the client that
 * it is ok to send the rest of the body.
 *
 * The idea here is it allows the server to authorise and accept/reject the request before large amounts of data are sent.
 * Sending large amounts of data if the request might not be accepted is a waste of bandwidth and ties up the server
 * in reading data that it will just discard.
 *
 * Vert.x allows you to set a {@link io.vertx.core.http.HttpClientRequest#continueHandler(io.vertx.core.Handler)} on the
 * client request object
 *
 * This will be called if the server sends back a `Status: 100 (Continue)` response to signify that it is ok to send
 * the rest of the request.
 *
 * This is used in conjunction with {@link io.vertx.core.http.HttpClientRequest#sendHead()}to send the head of the request.
 *
 * Here's an example:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example50}
 * ----
 *
 * On the server side a Vert.x http server can be configured to automatically send back 100 Continue interim responses
 * when it receives an `Expect: 100-Continue` header.
 *
 * This is done by setting the option {@link io.vertx.core.http.HttpServerOptions#setHandle100ContinueAutomatically(boolean)}.
 *
 * If you'd prefer to decide whether to send back continue responses manually, then this property should be set to
 * `false` (the default), then you can inspect the headers and call {@link io.vertx.core.http.HttpServerResponse#writeContinue()}
 * to have the client continue sending the body:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example50_1}
 * ----
 *
 * You can also reject the request by sending back a failure status code directly: in this case the body
 * should either be ignored or the connection should be closed (100-Continue is a performance hint and
 * cannot be a logical protocol constraint):
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example50_2}
 * ----
 *
 * ==== Client push
 *
 * Server push is a new feature of HTTP/2 that enables sending multiple responses in parallel for a single client request.
 *
 * A push handler can be set on a request to receive the request/response pushed by the server:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#example13}
 * ----
 *
 * If the client does not want to receive a pushed request, it can reset the stream:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#example14}
 * ----
 *
 * When no handler is set, any stream pushed will be automatically cancelled by the client with
 * a stream reset (`8` error code).
 *
 * ==== Receiving custom HTTP/2 frames
 *
 * HTTP/2 is a framed protocol with various frames for the HTTP request/response model. The protocol allows other kind of
 * frames to be sent and received.
 *
 * To receive custom frames, you can use the customFrameHandler on the request, this will get called every time a custom
 * frame arrives. Here's an example:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#example15}
 * ----
 *
 * === Enabling compression on the client
 *
 * The http client comes with support for HTTP Compression out of the box.
 *
 * This means the client can let the remote http server know that it supports compression, and will be able to handle
 * compressed response bodies.
 *
 * An http server is free to either compress with one of the supported compression algorithms or to send the body back
 * without compressing it at all. So this is only a hint for the Http server which it may ignore at will.
 *
 * To tell the http server which compression is supported by the client it will include an `Accept-Encoding` header with
 * the supported compression algorithm as value. Multiple compression algorithms are supported. In case of Vert.x this
 * will result in the following header added:
 *
 *  Accept-Encoding: gzip, deflate
 *
 * The server will choose then from one of these. You can detect if a server ompressed the body by checking for the
 * `Content-Encoding` header in the response sent back from it.
 *
 * If the body of the response was compressed via gzip it will include for example the following header:
 *
 *  Content-Encoding: gzip
 *
 * To enable compression set {@link io.vertx.core.http.HttpClientOptions#setTryUseCompression(boolean)} on the options
 * used when creating the client.
 *
 * By default compression is disabled.
 *
 * === HTTP/1.x pooling and keep alive
 *
 * Http keep alive allows http connections to be used for more than one request. This can be a more efficient use of
 * connections when you're making multiple requests to the same server.
 *
 * For HTTP/1.x versions, the http client supports pooling of connections, allowing you to reuse connections between requests.
 *
 * For pooling to work, keep alive must be true using {@link io.vertx.core.http.HttpClientOptions#setKeepAlive(boolean)}
 * on the options used when configuring the client. The default value is true.
 *
 * When keep alive is enabled. Vert.x will add a `Connection: Keep-Alive` header to each HTTP/1.0 request sent.
 * When keep alive is disabled. Vert.x will add a `Connection: Close` header to each HTTP/1.1 request sent to signal
 * that the connection will be closed after completion of the response.
 *
 * The maximum number of connections to pool *for each server* is configured using {@link io.vertx.core.http.HttpClientOptions#setMaxPoolSize(int)}
 *
 * When making a request with pooling enabled, Vert.x will create a new connection if there are less than the maximum number of
 * connections already created for that server, otherwise it will add the request to a queue.
 *
 * Keep alive connections will not be closed by the client automatically. To close them you can close the client instance.
 *
 * Alternatively you can set idle timeout using {@link io.vertx.core.http.HttpClientOptions#setIdleTimeout(int)} - any
 * connections not used within this timeout will be closed. Please note the idle timeout value is in seconds not milliseconds.
 *
 * === HTTP/1.1 pipe-lining
 *
 * The client also supports pipe-lining of requests on a connection.
 *
 * Pipe-lining means another request is sent on the same connection before the response from the preceding one has
 * returned. Pipe-lining is not appropriate for all requests.
 *
 * To enable pipe-lining, it must be enabled using {@link io.vertx.core.http.HttpClientOptions#setPipelining(boolean)}.
 * By default pipe-lining is disabled.
 *
 * When pipe-lining is enabled requests will be written to connections without waiting for previous responses to return.
 *
 * The number of pipe-lined requests over a single connection is limited by {@link io.vertx.core.http.HttpClientOptions#setPipeliningLimit}.
 * This option defines the maximum number of http requests sent to the server awaiting for a response. This limit ensures the
 * fairness of the distribution of the client requests over the connections to the same server.
 * 
 * === HTTP/2 multiplexing
 *
 * HTTP/2 advocates to use a single connection to a server, by default the http client uses a single
 * connection for each server, all the streams to the same server are multiplexed over the same connection.
 *
 * When the clients needs to use more than a single connection and use pooling, the {@link io.vertx.core.http.HttpClientOptions#setHttp2MaxPoolSize(int)}
 * shall be used.
 *
 * When it is desirable to limit the number of multiplexed streams per connection and use a connection
 * pool instead of a single connection, {@link io.vertx.core.http.HttpClientOptions#setHttp2MultiplexingLimit(int)}
 * can be used.
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#useMaxStreams}
 * ----
 *
 * The multiplexing limit for a connection is a setting set on the client that limits the number of streams
 * of a single connection. The effective value can be even lower if the server sets a lower limit
 * with the {@link io.vertx.core.http.Http2Settings#setMaxConcurrentStreams SETTINGS_MAX_CONCURRENT_STREAMS} setting.
 *
 * HTTP/2 connections will not be closed by the client automatically. To close them you can call {@link io.vertx.core.http.HttpConnection#close()}
 * or close the client instance.
 *
 * Alternatively you can set idle timeout using {@link io.vertx.core.http.HttpClientOptions#setIdleTimeout(int)} - any
 * connections not used within this timeout will be closed. Please note the idle timeout value is in seconds not milliseconds.
 *
 * === HTTP connections
 *
 * The {@link io.vertx.core.http.HttpConnection} offers the API for dealing with HTTP connection events, lifecycle
 * and settings.
 *
 * HTTP/2 implements fully the {@link io.vertx.core.http.HttpConnection} API.
 *
 * HTTP/1.x implements partially the {@link io.vertx.core.http.HttpConnection} API: only the close operation,
 * the close handler and exception handler are implemented. This protocol does not provide semantics for
 * the other operations.
 *
 * ==== Server connections
 *
 * The {@link io.vertx.core.http.HttpServerRequest#connection()} method returns the request connection on the server:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#example16}
 * ----
 *
 * A connection handler can be set on the server to be notified of any incoming connection:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#example17}
 * ----
 *
 * ==== Client connections
 *
 * The {@link io.vertx.core.http.HttpClientRequest#connection()} method returns the request connection on the client:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#example18}
 * ----
 *
 * A connection handler can be set on the request to be notified when the connection happens:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#example19}
 * ----
 *
 * ==== Connection settings
 *
 * The configuration of an HTTP/2 is configured by the {@link io.vertx.core.http.Http2Settings} data object.
 *
 * Each endpoint must respect the settings sent by the other side of the connection.
 *
 * When a connection is established, the client and the server exchange initial settings. Initial settings
 * are configured by {@link io.vertx.core.http.HttpClientOptions#setInitialSettings} on the client and
 * {@link io.vertx.core.http.HttpServerOptions#setInitialSettings} on the server.
 *
 * The settings can be changed at any time after the connection is established:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#example20}
 * ----
 *
 * As the remote side should acknowledge on reception of the settings update, it's possible to give a callback
 * to be notified of the acknowledgment:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#example21}
 * ----
 *
 * Conversely the {@link io.vertx.core.http.HttpConnection#remoteSettingsHandler(io.vertx.core.Handler)} is notified
 * when the new remote settings are received:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#example22}
 * ----
 *
 * NOTE: this only applies to the HTTP/2 protocol
 *
 * ==== Connection ping
 *
 * HTTP/2 connection ping is useful for determining the connection round-trip time or check the connection
 * validity: {@link io.vertx.core.http.HttpConnection#ping} sends a {@literal PING} frame to the remote
 * endpoint:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#example23}
 * ----
 *
 * Vert.x will send automatically an acknowledgement when a {@literal PING} frame is received,
 * an handler can be set to be notified for each ping received:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#example24}
 * ----
 *
 * The handler is just notified, the acknowledgement is sent whatsoever. Such feature is aimed for
 * implementing  protocols on top of HTTP/2.
 *
 * NOTE: this only applies to the HTTP/2 protocol
 *
 * ==== Connection shutdown and go away
 *
 * Calling {@link io.vertx.core.http.HttpConnection#shutdown()} will send a {@literal GOAWAY} frame to the
 * remote side of the connection, asking it to stop creating streams: a client will stop doing new requests
 * and a server will stop pushing responses. After the {@literal GOAWAY} frame is sent, the connection
 * waits some time (30 seconds by default) until all current streams closed and close the connection:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#example25}
 * ----
 *
 * The {@link io.vertx.core.http.HttpConnection#shutdownHandler} notifies when all streams have been closed, the
 * connection is not yet closed.
 *
 * It's possible to just send a {@literal GOAWAY} frame, the main difference with a shutdown is that
 * it will just tell the remote side of the connection to stop creating new streams without scheduling a connection
 * close:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#example26}
 * ----
 *
 * Conversely, it is also possible to be notified when {@literal GOAWAY} are received:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#example27}
 * ----
 *
 * The {@link io.vertx.core.http.HttpConnection#shutdownHandler} will be called when all current streams
 * have been closed and the connection can be closed:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTP2Examples#example28}
 * ----
 *
 * This applies also when a {@literal GOAWAY} is received.
 *
 * NOTE: this only applies to the HTTP/2 protocol
 *
 * ==== Connection close
 *
 * Connection {@link io.vertx.core.http.HttpConnection#close} closes the connection:
 *
 * - it closes the socket for HTTP/1.x
 * - a shutdown with no delay for HTTP/2, the {@literal GOAWAY} frame will still be sent before the connection is closed. *
 *
 * The {@link io.vertx.core.http.HttpConnection#closeHandler} notifies when a connection is closed.
 *
 * === HttpClient usage
 *
 * The HttpClient can be used in a Verticle or embedded.
 *
 * When used in a Verticle, the Verticle *should use its own client instance*.
 *
 * More generally a client should not be shared between different Vert.x contexts as it can lead to unexpected behavior.
 *
 * For example a keep-alive connection will call the client handlers on the context of the request that opened the connection, subsequent requests will use
 * the same context.
 *
 * When this happen Vert.x detects it and log a warn:
 *
 * ----
 * Reusing a connection with a different context: an HttpClient is probably shared between different Verticles
 * ----
 *
 * The HttpClient can be embedded in a non Vert.x thread like a unit test or a plain java `main`: the client handlers
 * will be called by different Vert.x threads and contexts, such contexts are created as needed. For production this
 * usage is not recommended.
 *
 * === Server sharing
 *
 * When several HTTP servers listen on the same port, vert.x orchestrates the request handling using a
 * round-robin strategy.
 *
 * Let's take a verticle creating a HTTP server such as:
 *
 * .io.vertx.examples.http.sharing.HttpServerVerticle
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#serversharing(io.vertx.core.Vertx)}
 * ----
 *
 * This service is listening on the port 8080. So, when this verticle is instantiated multiple times as with:
 * `vertx run io.vertx.examples.http.sharing.HttpServerVerticle -instances 2`, what's happening ? If both
 * verticles would bind to the same port, you would receive a socket exception. Fortunately, vert.x is handling
 * this case for you. When you deploy another server on the same host and port as an existing server it doesn't
 * actually try and create a new server listening on the same host/port. It binds only once to the socket. When
 * receiving a request it calls the server handlers following a round robin strategy.
 *
 * Let's now imagine a client such as:
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#serversharingclient(io.vertx.core.Vertx)}
 * ----
 *
 * Vert.x delegates the requests to one of the server sequentially:
 *
 * [source]
 * ----
 * Hello from i.v.e.h.s.HttpServerVerticle@1
 * Hello from i.v.e.h.s.HttpServerVerticle@2
 * Hello from i.v.e.h.s.HttpServerVerticle@1
 * Hello from i.v.e.h.s.HttpServerVerticle@2
 * ...
 * ----
 *
 * Consequently the servers can scale over available cores while each Vert.x verticle instance remains strictly
 * single threaded, and you don't have to do any special tricks like writing load-balancers in order to scale your
 * server on your multi-core machine.
 *
 * === Using HTTPS with Vert.x
 *
 * Vert.x http servers and clients can be configured to use HTTPS in exactly the same way as net servers.
 *
 * Please see <<ssl, configuring net servers to use SSL>> for more information.
 *
 * SSL can also be enabled/disabled per request with {@link io.vertx.core.http.RequestOptions} or when
 * specifying a scheme with {@link io.vertx.core.http.HttpClient#requestAbs(io.vertx.core.http.HttpMethod, java.lang.String)}
 * method.
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#setSSLPerRequest(io.vertx.core.http.HttpClient)}
 * ----
 *
 * The {@link io.vertx.core.http.HttpClientOptions#setSsl(boolean)} setting acts as the default client setting.
 *
 * The {@link io.vertx.core.http.RequestOptions#setSsl(boolean)} overrides the default client setting
 *
 * * setting the value to `false` will disable SSL/TLS even if the client is configured to use SSL/TLS
 * * setting the value to `true` will enable SSL/TLS  even if the client is configured to not use SSL/TLS, the actual
 * client SSL/TLS (such as trust, key/certificate, ciphers, ALPN, ...) will be reused
 *
 * Likewise {@link io.vertx.core.http.HttpClient#requestAbs(io.vertx.core.http.HttpMethod, java.lang.String)} scheme
 * also overrides the default client setting.
 *
 * ==== Server Name Indication (SNI)
 *
 * Vert.x http servers can be configured to use SNI in exactly the same way as {@linkplain io.vertx.core.net net servers}.
 *
 * Vert.x http client will present the actual hostname as _server name_ during the TLS handshake.
 *
 * === WebSockets
 *
 * http://en.wikipedia.org/wiki/WebSocket[WebSockets] are a web technology that allows a full duplex socket-like
 * connection between HTTP servers and HTTP clients (typically browsers).
 *
 * Vert.x supports WebSockets on both the client and server-side.
 *
 * ==== WebSockets on the server
 *
 * There are two ways of handling WebSockets on the server side.
 *
 * ===== WebSocket handler
 *
 * The first way involves providing a {@link io.vertx.core.http.HttpServer#websocketHandler(io.vertx.core.Handler)}
 * on the server instance.
 *
 * When a WebSocket connection is made to the server, the handler will be called, passing in an instance of
 * {@link io.vertx.core.http.ServerWebSocket}.
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example51}
 * ----
 *
 * You can choose to reject the WebSocket by calling {@link io.vertx.core.http.ServerWebSocket#reject()}.
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example52}
 * ----
 *
 * ===== Upgrading to WebSocket
 *
 * The second way of handling WebSockets is to handle the HTTP Upgrade request that was sent from the client, and
 * call {@link io.vertx.core.http.HttpServerRequest#upgrade()} on the server request.
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example53}
 * ----
 *
 * ===== The server WebSocket
 *
 * The {@link io.vertx.core.http.ServerWebSocket} instance enables you to retrieve the {@link io.vertx.core.http.ServerWebSocket#headers() headers},
 * {@link io.vertx.core.http.ServerWebSocket#path() path}, {@link io.vertx.core.http.ServerWebSocket#query() query} and
 * {@link io.vertx.core.http.ServerWebSocket#uri() URI} of the HTTP request of the WebSocket handshake.
 *
 * ==== WebSockets on the client
 *
 * The Vert.x {@link io.vertx.core.http.HttpClient} supports WebSockets.
 *
 * You can connect a WebSocket to a server using one of the {@link io.vertx.core.http.HttpClient#websocket} operations and
 * providing a handler.
 *
 * The handler will be called with an instance of {@link io.vertx.core.http.WebSocket} when the connection has been made:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example54}
 * ----
 *
 * ==== Writing messages to WebSockets
 *
 * If you wish to write a single WebSocket message to the WebSocket you can do this with
 * {@link io.vertx.core.http.WebSocket#writeBinaryMessage(io.vertx.core.buffer.Buffer)} or
 * {@link io.vertx.core.http.WebSocket#writeTextMessage(java.lang.String)} :
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example55}
 * ----
 *
 * If the WebSocket message is larger than the maximum websocket frame size as configured with
 * {@link io.vertx.core.http.HttpClientOptions#setMaxWebsocketFrameSize(int)}
 * then Vert.x will split it into multiple WebSocket frames before sending it on the wire.
 *
 * ==== Writing frames to WebSockets
 *
 * A WebSocket message can be composed of multiple frames. In this case the first frame is either a _binary_ or _text_ frame
 * followed by zero or more _continuation_ frames.
 *
 * The last frame in the message is marked as _final_.
 *
 * To send a message consisting of multiple frames you create frames using
 * {@link io.vertx.core.http.WebSocketFrame#binaryFrame(io.vertx.core.buffer.Buffer, boolean)}
 * , {@link io.vertx.core.http.WebSocketFrame#textFrame(java.lang.String, boolean)} or
 * {@link io.vertx.core.http.WebSocketFrame#continuationFrame(io.vertx.core.buffer.Buffer, boolean)} and write them
 * to the WebSocket using {@link io.vertx.core.http.WebSocket#writeFrame(io.vertx.core.http.WebSocketFrame)}.
 *
 * Here's an example for binary frames:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example56}
 * ----
 *
 * In many cases you just want to send a websocket message that consists of a single final frame, so we provide a couple
 * of shortcut methods to do that with {@link io.vertx.core.http.WebSocket#writeFinalBinaryFrame(io.vertx.core.buffer.Buffer)}
 * and {@link io.vertx.core.http.WebSocket#writeFinalTextFrame(String)}.
 *
 * Here's an example:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example56_1}
 * ----
 *
 * ==== Reading frames from WebSockets
 *
 * To read frames from a WebSocket you use the {@link io.vertx.core.http.WebSocket#frameHandler(io.vertx.core.Handler)}.
 *
 * The frame handler will be called with instances of {@link io.vertx.core.http.WebSocketFrame} when a frame arrives,
 * for example:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example57}
 * ----
 *
 * ==== Closing WebSockets
 *
 * Use {@link io.vertx.core.http.WebSocket#close()} to close the WebSocket connection when you have finished with it.
 *
 * ==== Streaming WebSockets
 *
 * The {@link io.vertx.core.http.WebSocket} instance is also a {@link io.vertx.core.streams.ReadStream} and a
 * {@link io.vertx.core.streams.WriteStream} so it can be used with pumps.
 *
 * When using a WebSocket as a write stream or a read stream it can only be used with WebSockets connections that are
 * used with binary frames that are no split over multiple frames.
 *
 * === Using a proxy for HTTP/HTTPS connections
 *
 * The http client supports accessing http/https URLs via a HTTP proxy (e.g. Squid) or _SOCKS4a_ or _SOCKS5_ proxy.
 * The CONNECT protocol uses HTTP/1.x but can connect to HTTP/1.x and HTTP/2 servers.
 *
 * Connecting to h2c (unencrypted HTTP/2 servers) is likely not supported by http proxies since they will support
 * HTTP/1.1 only.
 *
 * The proxy can be configured in the {@link io.vertx.core.http.HttpClientOptions} by setting a
 * {@link io.vertx.core.net.ProxyOptions} object containing proxy type, hostname, port and optionally username and password.
 *
 * Here's an example of using an HTTP proxy:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example58}
 * ----
 *
 * When the client connects to an http URL, it connects to the proxy server and provides the full URL in the
 * HTTP request ("GET http://www.somehost.com/path/file.html HTTP/1.1").
 *
 * When the client connects to an https URL, it asks the proxy to create a tunnel to the remote host with
 * the CONNECT method.
 *
 * For a SOCKS5 proxy:
 *
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example59}
 * ----
 *
 * The DNS resolution is always done on the proxy server, to achieve the functionality of a SOCKS4 client, it is necessary
 * to resolve the DNS address locally.
 *
 * ==== Handling of other protocols
 *
 * The HTTP proxy implementation supports getting ftp:// urls if the proxy supports
 * that, which isn't available in non-proxy getAbs requests.
 * 
 * [source,$lang]
 * ----
 * {@link examples.HTTPExamples#example60}
 * ----
 *
 * Support for other protocols is not available since java.net.URL does not
 * support them (gopher:// for example).
 *
 * === Automatic clean-up in verticles
 *
 * If you're creating http servers and clients from inside verticles, those servers and clients will be automatically closed
 * when the verticle is undeployed.
 *
 */
@Document(fileName = "http.adoc")
package io.vertx.core.http;

import io.vertx.docgen.Document;

