//  ========================================================================
//  Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd.
//  ========================================================================
//  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.
//  ========================================================================

[[proxy-servlet]]
=== Proxy Servlet

[[proxy-servlet-metadata]]
==== Info

* Classname: `org.eclipse.jetty.proxy.ProxyServlet`
* Maven Artifact: org.eclipse.jetty:jetty-proxy
* Javadoc: {JDURL}/org/eclipse/jetty/proxy/ProxyServlet.html
* Xref: {JXURL}/org/eclipse/jetty/proxy/ProxyServlet.html

[[proxy-servlet-usage]]
==== Usage

An asynchronous servlet that forwards requests to another server either as a standard web reverse proxy (as defined by RFC2616) or as a transparent reverse proxy.
Internally it uses the async jetty-client.

To facilitate JMX monitoring, the `HttpClient` instance is set as context attribute, prefixed with the servlet's name and exposed by the mechanism provided by `ContextHandler.MANAGED_ATTRIBUTES`.

[[proxy-servlet-init]]
==== Init Parameters

The following init parameters may be used to configure the servlet:

hostHeader::
  forces the host header to a particular value
viaHost::
  the name to use in the Via header: Via: http/1.1 <viaHost>
whiteList::
  comma-separated list of allowed proxy hosts
blackList::
  comma-separated list of forbidden proxy hosts


In addition, there are a number of init parameters that can be used to configure the `HttpClient` instance used internally for the proxy.

maxThreads::
Default Value: 256
The max number of threads of HttpClient's Executor

maxConnections::
Default Value: 32768
The max number of connections per destination.
RFC 2616 suggests that 2 connections should be opened per each destination, but browsers commonly open 6 or more.
If this `HttpClient` is used for load testing, it is common to have only one destination (the server to load test), and it is recommended to set this value to a high value (at least as much as the threads present in the executor).

idleTimeout::
Default Value: 30000
The idle timeout in milliseconds that a connection can be idle, that is without traffic of bytes in either direction.

timeout::
Default Value: 60000
The total timeout in milliseconds for the request/response conversation.

requestBufferSize::
Default Value: 4096
The size of the request buffer the request is written into.

responseBufferSize::
Default Value: 4096
The size of the response buffer the response is written into.
