= Vert.x Http Proxy
:toc: left

Vert.x Http Proxy is a reverse proxy based on Vert.x, it aims to implement reusable reverse proxy logic to focus on
higher concerns.

WARNING: This module has _Tech Preview_ status, this means the API can change between versions.

== Using Vert.x Http Proxy

To use Vert.x Http Proxy, add the following dependency to the _dependencies_ section of your build descriptor:

* Maven (in your `pom.xml`):

[source,xml,subs="+attributes"]
----
<dependency>
 <groupId>io.vertx</groupId>
 <artifactId>vertx-http-proxy</artifactId>
 <version>4.2.2</version>
</dependency>
----

* Gradle (in your `build.gradle` file):

[source,groovy,subs="+attributes"]
----
dependencies {
 compile 'io.vertx:vertx-http-proxy:4.2.2'
}
----

== Basic Http Proxy

In order to accomplish a reverse proxy with Vert.x Http Proxy you need the following:

1. *Proxy Server* that handles outbound requests and forward them to the *origin server* using `HttpProxy` instance.
2. *Origin Server* that handles requests from the *proxy server* and handles responses accordingly.

Now, you have the overall concept so let's dive in implementation and begin with *origin server* then
the *proxy server* with `HttpProxy`:

== Origin Server

You simply create the *origin server* that listens to port `7070`

[source,java]
----
HttpServer originServer = vertx.createHttpServer();

originServer.requestHandler(req -> {
  req.response()
    .putHeader("content-type", "text/html")
    .end("<html><body><h1>I'm the target resource!</h1></body></html>");
}).listen(7070);
----

== Proxy Server With `HttpProxy`

Create the *proxy server* that listens to port `8080` with `HttpProxy` instance that handles reverse proxy logic
accordingly.

[source,java]
----
HttpClient proxyClient = vertx.createHttpClient();

HttpProxy proxy = HttpProxy.reverseProxy(proxyClient);
proxy.origin(7070, "origin");

HttpServer proxyServer = vertx.createHttpServer();

proxyServer.requestHandler(proxy).listen(8080);
----

Finally, all outbound requests will be forwarded as a reverse proxy to the *origin server* conveniently.

=== WebSockets

The proxy supports WebSocket by default.

WebSocket handshake requests  are forwarded to the origin server (including the `connection` header)  and the handshake
happens between the user agent and the origin server.

You can configure WebSocket support with `link:../../apidocs/io/vertx/httpproxy/ProxyOptions.html#setSupportWebSocket-boolean-[setSupportWebSocket]`.

=== Proxy caching

By default the proxy does not cache response and ignores most cache directives, you can enable caching by setting the cache options.

[source,java]
----
HttpProxy proxy = HttpProxy.reverseProxy(new ProxyOptions().setCacheOptions(new CacheOptions()), proxyClient);
----