x-http-proxy.4.2.6.source-code.index.adoc Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of vertx-http-proxy Show documentation
There is a newer version: 5.0.0.CR3
= 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"]
----

  io.vertx
  vertx-http-proxy
  ${maven.version}

----

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

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

== Reverse proxy server

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

1. *Proxy Server* that handles user-agent requests and forward them to the *origin server*
2. *Origin Server* that handles requests from the *proxy server* and respond accordingly

You can create a *proxy server* that listens to port `8080` and implement reverse proxy logic

[source,java]
----
{@link examples.HttpProxyExamples#proxy}
----

All user-agent requests are forwarded 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 io.vertx.httpproxy.ProxyOptions#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]
----
{@link examples.HttpProxyExamples#cacheConfig}
----

=== Proxy interception

Interception is a powerful way to extend the proxy withg new features.

You can implement {@link io.vertx.httpproxy.ProxyInterceptor#handleProxyRequest} to perform any operation on the proxy request

[source,java]
----
{@link examples.HttpProxyExamples#inboundInterceptor}
----

Likewise with the proxy response

[source,java]
----
{@link examples.HttpProxyExamples#outboundInterceptor}
----

==== Body filtering

You can filter body by simply replacing the original {@link io.vertx.httpproxy.Body} with a new one

[source,java]
----
{@link examples.HttpProxyExamples#bodyFilter}
----

==== Interception control

{@link io.vertx.httpproxy.ProxyContext#sendRequest} and {@link io.vertx.httpproxy.ProxyContext#sendResponse} continue the
current interception chain and then send the result to the origin server or the user-agent.

You can change the control, e.g you can send a response immediately to the user-agent without even requesting the origin server

[source,java]
----
{@link examples.HttpProxyExamples#immediateResponse}
----