Web modules
API docs
You are currently viewing the documentation for the unreleased version 5.0.0.CR2 of Vert.x. Visit the latest stable version of this page.

Vert.x Web Proxy

Vert.x Web Proxy provides a handler that handles the reverse proxy logic using Vert.x Http Proxy.

This module has Tech Preview status, this means the API can change between versions.

Using Vert.x Web Proxy

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

  • Maven (in your pom.xml):

<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-web-proxy</artifactId>
  <version>5.0.0.CR2</version>
</dependency>

  • Gradle (in your build.gradle file):

dependencies {
  compile 'io.vertx:vertx-web-proxy:5.0.0.CR2'
}

Basic Web Proxy

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

  1. Proxy Server that handles front requests and forward them to the origin server using ProxyHandler.

  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 using ProxyHandler:

Origin Server (Backend)

You simply create the origin server and handle requests with Vert.x Web Router, the origin server listens to port 7070

HttpServer backendServer = vertx.createHttpServer();

Router backendRouter = Router.router(vertx);

backendRouter.route(HttpMethod.GET, "/foo").handler(rc -> {
  rc.response()
    .putHeader("content-type", "text/html")
    .end("<html><body><h1>I'm the target resource!</h1></body></html>");
});

backendServer.requestHandler(backendRouter).listen(7070);

Proxy Server

Create the proxy server that listens to port 8080

HttpServer proxyServer = vertx.createHttpServer();

Router proxyRouter = Router.router(vertx);

proxyServer.requestHandler(proxyRouter);

proxyServer.listen(8080);

Using ProxyHandler

The last interesting part is to route proxy server requests to the origin server, so you need to create HttpProxy with specified target and ProxyHandler.

HttpClient proxyClient = vertx.createHttpClient();

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

proxyRouter
  .route(HttpMethod.GET, "/foo").handler(ProxyHandler.create(httpProxy));

Or you can specify the target in ProxyHandler instead.

HttpClient proxyClient = vertx.createHttpClient();

HttpProxy httpProxy = HttpProxy.reverseProxy(proxyClient);

proxyRouter
  .route(HttpMethod.GET, "/foo")
  .handler(ProxyHandler.create(httpProxy, 7070, "localhost"));

Finally, the proxy server requests will be routed as a reverse proxy to the origin server conveniently.

The BodyHandler is not compatible with the ProxyHandler. It shouldn’t be installed on the same route or a previous route.

router.post().handler(BodyHandler.create()); // Don't do this
router.route("/product").handler(ProxyHandler.create(productServiceProxy));

router.route("/product")
  .handler(BodyHandler.create()) // Don't do this
  .handler(ProxyHandler.create(productServiceProxy));

Using ProxyHandler for multiple targets

In order to route proxy server requests to multiple origin servers you simply create HttpProxy for each one and specify the target independently.

HttpClient proxyClient = vertx.createHttpClient();

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

HttpProxy httpProxy2 = HttpProxy.reverseProxy(proxyClient);
httpProxy2.origin(6060, "localhost");

proxyRouter
  .route(HttpMethod.GET, "/foo").handler(ProxyHandler.create(httpProxy1));

proxyRouter
  .route(HttpMethod.GET, "/bar").handler(ProxyHandler.create(httpProxy2));