com.browserup.bup

Class BrowserUpProxyServer

java.lang.Object

com.browserup.bup.BrowserUpProxyServer

All Implemented Interfaces:

BrowserUpProxy

public class BrowserUpProxyServer
extends java.lang.Object
implements BrowserUpProxy

A LittleProxy-based implementation of BrowserUpProxy.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	VIA_HEADER_ALIAS The default pseudonym to use when adding the Via header to proxied requests.

Constructor Summary

Constructors

Constructor and Description
BrowserUpProxyServer()

Method Summary

Modifier and Type	Method and Description
void	abort() Like BrowserUpProxy.stop(), shuts down the proxy server and no longer accepts incoming connections, but does not wait for any existing network traffic to cease.
protected void	addBrowserUpFilters() Adds the basic BrowserUp-proxy filters, except for the relatively-expensive HAR capture filter.
void	addFirstHttpFilterFactory(org.littleshoot.proxy.HttpFiltersSource filterFactory) Adds a new filter factory (request/response interceptor) to the beginning of the HttpFilters chain.
protected void	addHarCaptureFilter() Enables the HAR capture filter if it has not already been enabled.
void	addHeader(java.lang.String name, java.lang.String value) Adds a new HTTP header to every request.
void	addHeaders(java.util.Map<java.lang.String,java.lang.String> headers) Adds the specified HTTP headers to every request.
void	addHttpFilterFactory(org.littleshoot.proxy.HttpFiltersSource filterFactory)
void	addLastHttpFilterFactory(org.littleshoot.proxy.HttpFiltersSource filterFactory) Adds a new filter factory (request/response interceptor) to the end of the HttpFilters chain.
void	addRequestFilter(RequestFilter filter) Note: The current implementation of this method forces a maximum request size of 2 MiB.
void	addResponseFilter(ResponseFilter filter) Note: The current implementation of this method forces a maximum response size of 2 MiB.
void	addWhitelistPattern(java.lang.String urlPattern) Adds a URL-matching regular expression to an existing whitelist.
AssertionResult	assertMostRecentUrlResponseTimeWithin(java.util.regex.Pattern url, long time)
void	autoAuthorization(java.lang.String domain, java.lang.String username, java.lang.String password, AuthType authType) Enables automatic authorization for the specified domain and auth type.
void	blacklistRequests(java.lang.String pattern, int responseCode) Adds a URL-matching regular expression to the blacklist.
void	blacklistRequests(java.lang.String pattern, int responseCode, java.lang.String method) Adds a URL-matching regular expression to the blacklist.
void	chainedProxyAuthorization(java.lang.String username, java.lang.String password, AuthType authType) Enables chained proxy authorization using the Proxy-Authorization header described in RFC 7235, section 4.4 (https://tools.ietf.org/html/rfc7235#section-4.4).
void	clearBlacklist() Clears any existing blacklist.
void	clearRewriteRules() Clears all existing rewrite rules.
void	disableHarCaptureTypes(CaptureType... captureTypes) Disables the specified HAR capture types.
void	disableHarCaptureTypes(java.util.Set<CaptureType> captureTypes) Disables the specified HAR capture types.
void	disableWhitelist() Clears any existing whitelist and disables whitelisting.
void	enableEmptyWhitelist(int statusCode) Enables the whitelist, but with no matching URLs.
void	enableHarCaptureTypes(CaptureType... captureTypes) Enables the specified HAR capture types.
void	enableHarCaptureTypes(java.util.Set<CaptureType> captureTypes) Enables the specified HAR capture types.
Har	endHar() Stops capturing traffic in the HAR.
void	endPage()
java.util.Collection<HarEntry>	findEntries(java.util.regex.Pattern url) Search the entire log for entries whose request URL matches the given url.
java.util.Optional<HarEntry>	findMostRecentEntry(java.util.regex.Pattern url) Search the entire log for the most recent entry whose request URL matches the given url.
java.util.Map<java.lang.String,java.lang.String>	getAllHeaders() Returns all headers previously added with BrowserUpProxy.addHeader(String name, String value).
java.util.Collection<BlacklistEntry>	getBlacklist() Returns all blacklist entries currently in effect.
java.net.InetSocketAddress	getChainedProxy() Returns the address and port of the upstream proxy.
java.net.InetAddress	getClientBindAddress() Returns the address of the network interface on which the proxy is listening for client connections.
HarPage	getCurrentHarPage()
java.util.List<org.littleshoot.proxy.HttpFiltersSource>	getFilterFactories()
Har	getHar() Retrieves the current HAR.
java.util.EnumSet<CaptureType>	getHarCaptureTypes()
AdvancedHostResolver	getHostNameResolver() Returns the current host name resolver.
int	getPort() Returns the actual port on which the proxy is listening for client connections.
long	getReadBandwidthLimit() Returns the current bandwidth limit for reading, in bytes per second.
java.util.Map<java.lang.String,java.lang.String>	getRewriteRules() Returns all rewrite rules currently in effect.
java.net.InetAddress	getServerBindAddress() Returns the address address of the network interface the proxy will use to initiate upstream connections.
int	getWhitelistStatusCode() Returns the status code returned for all URLs that do not match the whitelist.
java.util.Collection<java.lang.String>	getWhitelistUrls() Returns the URL-matching regular expressions currently in effect.
long	getWriteBandwidthLimit() Returns the current bandwidth limit for writing, in bytes per second.
boolean	isMitmDisabled()
boolean	isStarted() Returns true if the proxy is started and listening for connections, otherwise false.
boolean	isStopped()
boolean	isWhitelistEnabled() Returns true if the whitelist is enabled, otherwise false.
Har	newHar() Starts a new HAR file with the default page name (see BrowserUpProxy.newPage().
Har	newHar(java.lang.String initialPageRef) Starts a new HAR file with the specified initialPageRef as the page name and page title.
Har	newHar(java.lang.String initialPageRef, java.lang.String initialPageTitle) Starts a new HAR file with the specified page name and page title.
Har	newPage() Starts a new HAR page using the default page naming convention.
Har	newPage(java.lang.String pageRef) Starts a new HAR page using the specified pageRef as the page name and the page title.
Har	newPage(java.lang.String pageRef, java.lang.String pageTitle) Starts a new HAR page using the specified pageRef as the page name and the pageTitle as the page title.
void	removeAllHeaders() Removes all headers previously added with BrowserUpProxy.addHeader(String name, String value).
void	removeHeader(java.lang.String name) Removes a header previously added with BrowserUpProxy.addHeader(String name, String value).
void	removeRewriteRule(java.lang.String urlPattern) Removes an existing rewrite rule whose urlPattern matches the specified pattern.
void	rewriteUrl(java.lang.String pattern, java.lang.String replace) Adds a rewrite rule for the specified URL-matching regular expression.
void	rewriteUrls(java.util.Map<java.lang.String,java.lang.String> rewriteRules) Replaces existing rewrite rules with the specified patterns and replacement expressions.
void	setBlacklist(java.util.Collection<BlacklistEntry> blacklist) Replaces any existing blacklist with the specified blacklist.
void	setChainedProxy(java.net.InetSocketAddress chainedProxyAddress) Instructs this proxy to route traffic through an upstream proxy.
void	setChainedProxyManager(org.littleshoot.proxy.ChainedProxyManager chainedProxyManager) Allows access to the LittleProxy ChainedProxyManager for fine-grained control of the chained proxies.
void	setConnectTimeout(int connectTimeout, java.util.concurrent.TimeUnit timeUnit) Maximum amount of time to wait to establish a connection to a remote server.
void	setHarCaptureTypes(CaptureType... captureTypes) Sets the data types that will be captured in the HAR file for future requests.
void	setHarCaptureTypes(java.util.Set<CaptureType> harCaptureSettings) Sets the data types that will be captured in the HAR file for future requests.
void	setHostNameResolver(AdvancedHostResolver resolver) Sets the resolver that will be used to look up host names.
void	setIdleConnectionTimeout(int idleConnectionTimeout, java.util.concurrent.TimeUnit timeUnit) The LittleProxy implementation only allows idle connection timeouts to be specified in seconds.
void	setLatency(long latency, java.util.concurrent.TimeUnit timeUnit) The minimum amount of time that will elapse between the time the proxy begins receiving a response from the server and the time the proxy begins sending the response to the client.
void	setMitmDisabled(boolean mitmDisabled) Completely disables MITM for this proxy server.
void	setMitmManager(org.littleshoot.proxy.MitmManager mitmManager) Sets the MITM manager, which is responsible for generating forged SSL certificates to present to clients.
void	setReadBandwidthLimit(long bytesPerSecond) Sets the maximum bandwidth to consume when reading server responses.
void	setRequestTimeout(int requestTimeout, java.util.concurrent.TimeUnit timeUnit) Maximum amount of time to wait for an HTTP response from the remote server after the request has been sent in its entirety.
void	setThreadPoolConfiguration(org.littleshoot.proxy.impl.ThreadPoolConfiguration threadPoolConfiguration) Configures the Netty thread pool used by the LittleProxy back-end.
void	setTrustAllServers(boolean trustAllServers) Disables verification of all upstream servers' SSL certificates.
void	setTrustSource(com.browserup.bup.mitm.TrustSource trustSource) Sets the TrustSource that contains trusted root certificate authorities that will be used to validate upstream servers' certificates.
void	setUseEcc(boolean useEcc)
void	setWriteBandwidthLimit(long bytesPerSecond) Sets the maximum bandwidth to consume when sending requests to servers.
void	start() Starts the proxy on port 0 (a JVM-selected open port).
void	start(int port) Starts the proxy on the specified port.
void	start(int port, java.net.InetAddress bindAddress) Starts the proxy on the specified port.
void	start(int port, java.net.InetAddress clientBindAddress, java.net.InetAddress serverBindAddress) Starts the proxy on the specified port.
void	stop() Stops accepting new client connections and initiates a graceful shutdown of the proxy server, waiting up to 5 seconds for network traffic to stop.
protected void	stop(boolean graceful)
void	stopAutoAuthorization(java.lang.String domain) Stops automatic authorization for the specified domain.
boolean	waitForQuiescence(long quietPeriod, long timeout, java.util.concurrent.TimeUnit timeUnit) Waits for existing network traffic to stop, and for the specified quietPeriod to elapse.
void	whitelistRequests(java.util.Collection<java.lang.String> urlPatterns, int statusCode) Whitelists URLs matching the specified regular expression patterns.
void	whitelistRequests(java.lang.String[] patterns, int responseCode) Whitelist the specified request patterns, returning the specified responseCode for non-whitelisted requests.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

VIA_HEADER_ALIAS

public static final java.lang.String VIA_HEADER_ALIAS

The default pseudonym to use when adding the Via header to proxied requests.

See Also:

Constant Field Values

Constructor Detail

BrowserUpProxyServer

public BrowserUpProxyServer()

Method Detail

start

public void start(int port,
                  java.net.InetAddress clientBindAddress,
                  java.net.InetAddress serverBindAddress)

Description copied from interface: BrowserUpProxy

Starts the proxy on the specified port. The proxy will listen for connections on the network interface specified by the clientBindAddress, and will initiate connections to upstream servers from the network interface specified by the serverBindAddress.

Specified by:

start in interface BrowserUpProxy

Parameters:

port - port to listen on

clientBindAddress - address of the network interface on which the proxy will listen for connections

serverBindAddress - address of the network interface on which the proxy will connect to upstream servers

isStarted

public boolean isStarted()

Description copied from interface: BrowserUpProxy

Returns true if the proxy is started and listening for connections, otherwise false.

Specified by:

isStarted in interface BrowserUpProxy

Returns:

is proxy started

start

public void start(int port)

Description copied from interface: BrowserUpProxy

Starts the proxy on the specified port. The proxy will bind the listener to the wildcard address (0:0:0:0 - all network interfaces).

Specified by:

start in interface BrowserUpProxy

Parameters:

port - port to listen on

start

public void start(int port,
                  java.net.InetAddress bindAddress)

Description copied from interface: BrowserUpProxy

Starts the proxy on the specified port. The proxy will listen for connections on the network interface specified by the bindAddress, and will also initiate connections to upstream servers on the same network interface.

Specified by:

start in interface BrowserUpProxy

Parameters:

port - port to listen on

bindAddress - address of the network interface on which the proxy will listen for connections and also attempt to connect to upstream servers.

start

public void start()

Description copied from interface: BrowserUpProxy

Starts the proxy on port 0 (a JVM-selected open port). The proxy will bind the listener to the wildcard address (0:0:0:0 - all network interfaces).

Specified by:

start in interface BrowserUpProxy

stop

public void stop()

Description copied from interface: BrowserUpProxy

Stops accepting new client connections and initiates a graceful shutdown of the proxy server, waiting up to 5 seconds for network traffic to stop. If the proxy was previously stopped or aborted, this method has no effect.

Specified by:

stop in interface BrowserUpProxy

abort

public void abort()

Description copied from interface: BrowserUpProxy

Like BrowserUpProxy.stop(), shuts down the proxy server and no longer accepts incoming connections, but does not wait for any existing network traffic to cease. Any existing connections to clients or to servers may be force-killed immediately. If the proxy was previously stopped or aborted, this method has no effect.

Specified by:

abort in interface BrowserUpProxy

stop

protected void stop(boolean graceful)

getClientBindAddress

public java.net.InetAddress getClientBindAddress()

Description copied from interface: BrowserUpProxy

Returns the address of the network interface on which the proxy is listening for client connections.

Specified by:

getClientBindAddress in interface BrowserUpProxy

Returns:

the client bind address, or null if the proxy has not been started

getPort

public int getPort()

Description copied from interface: BrowserUpProxy

Returns the actual port on which the proxy is listening for client connections.

Specified by:

getPort in interface BrowserUpProxy

Returns:

port

getServerBindAddress

public java.net.InetAddress getServerBindAddress()

Description copied from interface: BrowserUpProxy

Returns the address address of the network interface the proxy will use to initiate upstream connections. If no server bind address has been set, this method returns null, even if the proxy has been started.

Specified by:

getServerBindAddress in interface BrowserUpProxy

Returns:

server bind address if one has been set, otherwise null

getHar

public Har getHar()

Description copied from interface: BrowserUpProxy

Retrieves the current HAR.

Specified by:

getHar in interface BrowserUpProxy

Returns:

current HAR, or null if HAR capture is not enabled

newHar

public Har newHar()

Description copied from interface: BrowserUpProxy

Starts a new HAR file with the default page name (see BrowserUpProxy.newPage(). Enables HAR capture if it was not previously enabled.

Specified by:

newHar in interface BrowserUpProxy

Returns:

existing HAR file, or null if none exists or HAR capture was disabled

newHar

public Har newHar(java.lang.String initialPageRef)

Description copied from interface: BrowserUpProxy

Starts a new HAR file with the specified initialPageRef as the page name and page title. Enables HAR capture if it was not previously enabled.

Specified by:

newHar in interface BrowserUpProxy

Parameters:

initialPageRef - initial page name of the new HAR file

Returns:

existing HAR file, or null if none exists or HAR capture was disabled

newHar

public Har newHar(java.lang.String initialPageRef,
                  java.lang.String initialPageTitle)

Description copied from interface: BrowserUpProxy

Starts a new HAR file with the specified page name and page title. Enables HAR capture if it was not previously enabled.

Specified by:

newHar in interface BrowserUpProxy

Parameters:

initialPageRef - initial page name of the new HAR file

initialPageTitle - initial page title of the new HAR file

Returns:

existing HAR file, or null if none exists or HAR capture was disabled

setHarCaptureTypes

public void setHarCaptureTypes(java.util.Set<CaptureType> harCaptureSettings)

Description copied from interface: BrowserUpProxy

Sets the data types that will be captured in the HAR file for future requests. Replaces any existing capture types with the specified capture types. A null or empty set will not disable HAR capture, but will disable collection of additional CaptureType data types. CaptureType provides several convenience methods to retrieve commonly-used capture settings. Note: HAR capture must still be explicitly enabled via BrowserUpProxy.newHar() or BrowserUpProxy.newHar(String) to begin capturing any request and response contents.

Specified by:

setHarCaptureTypes in interface BrowserUpProxy

Parameters:

harCaptureSettings - HAR data types to capture

setHarCaptureTypes

public void setHarCaptureTypes(CaptureType... captureTypes)

Description copied from interface: BrowserUpProxy

Sets the data types that will be captured in the HAR file for future requests. Replaces any existing capture types with the specified capture types. A null or empty set will not disable HAR capture, but will disable collection of additional CaptureType data types. CaptureType provides several convenience methods to retrieve commonly-used capture settings. Note: HAR capture must still be explicitly enabled via BrowserUpProxy.newHar() or BrowserUpProxy.newHar(String) to begin capturing any request and response contents.

Specified by:

setHarCaptureTypes in interface BrowserUpProxy

Parameters:

captureTypes - HAR data types to capture

getHarCaptureTypes

public java.util.EnumSet<CaptureType> getHarCaptureTypes()

Specified by:

getHarCaptureTypes in interface BrowserUpProxy

Returns:

A copy of HAR capture types currently in effect. The EnumSet cannot be used to modify the HAR capture types currently in effect.

enableHarCaptureTypes

public void enableHarCaptureTypes(java.util.Set<CaptureType> captureTypes)

Description copied from interface: BrowserUpProxy

Enables the specified HAR capture types. Does not replace or disable any other capture types that may already be enabled.

Specified by:

enableHarCaptureTypes in interface BrowserUpProxy

Parameters:

captureTypes - capture types to enable

enableHarCaptureTypes

public void enableHarCaptureTypes(CaptureType... captureTypes)

Description copied from interface: BrowserUpProxy

Enables the specified HAR capture types. Does not replace or disable any other capture types that may already be enabled.

Specified by:

enableHarCaptureTypes in interface BrowserUpProxy

Parameters:

captureTypes - capture types to enable

disableHarCaptureTypes

public void disableHarCaptureTypes(java.util.Set<CaptureType> captureTypes)

Description copied from interface: BrowserUpProxy

Disables the specified HAR capture types. Does not replace or disable any other capture types that may already be enabled.

Specified by:

disableHarCaptureTypes in interface BrowserUpProxy

Parameters:

captureTypes - capture types to disable

disableHarCaptureTypes

public void disableHarCaptureTypes(CaptureType... captureTypes)

Description copied from interface: BrowserUpProxy

Disables the specified HAR capture types. Does not replace or disable any other capture types that may already be enabled.

Specified by:

disableHarCaptureTypes in interface BrowserUpProxy

Parameters:

captureTypes - capture types to disable

newPage

public Har newPage()

Description copied from interface: BrowserUpProxy

Starts a new HAR page using the default page naming convention. The default page naming convention is "Page #", where "#" resets to 1 every time BrowserUpProxy.newHar() or BrowserUpProxy.newHar(String) is called, and increments on every subsequent call to BrowserUpProxy.newPage() or BrowserUpProxy.newHar(String). Populates the HarPageTiming.onLoad value based on the amount of time the current page has been captured.

Specified by:

newPage in interface BrowserUpProxy

Returns:

the HAR as it existed immediately after ending the current page

newPage

public Har newPage(java.lang.String pageRef)

Description copied from interface: BrowserUpProxy

Starts a new HAR page using the specified pageRef as the page name and the page title. Populates the HarPageTiming.onLoad value based on the amount of time the current page has been captured.

Specified by:

newPage in interface BrowserUpProxy

Parameters:

pageRef - name of the new page

Returns:

the HAR as it existed immediately after ending the current page

newPage

public Har newPage(java.lang.String pageRef,
                   java.lang.String pageTitle)

Description copied from interface: BrowserUpProxy

Starts a new HAR page using the specified pageRef as the page name and the pageTitle as the page title. Populates the HarPageTiming.onLoad value based on the amount of time the current page has been captured.

Specified by:

newPage in interface BrowserUpProxy

Parameters:

pageRef - name of the new page

pageTitle - title of the new page

Returns:

the HAR as it existed immediately after ending the current page

endHar

public Har endHar()

Description copied from interface: BrowserUpProxy

Stops capturing traffic in the HAR. Populates the HarPageTiming.onLoad value for the current page based on the amount of time it has been captured.

Specified by:

endHar in interface BrowserUpProxy

Returns:

the existing HAR

setReadBandwidthLimit

public void setReadBandwidthLimit(long bytesPerSecond)

Description copied from interface: BrowserUpProxy

Sets the maximum bandwidth to consume when reading server responses.

Specified by:

setReadBandwidthLimit in interface BrowserUpProxy

Parameters:

bytesPerSecond - maximum bandwidth, in bytes per second

getReadBandwidthLimit

public long getReadBandwidthLimit()

Description copied from interface: BrowserUpProxy

Returns the current bandwidth limit for reading, in bytes per second.

Specified by:

getReadBandwidthLimit in interface BrowserUpProxy

Returns:

ReadBandwidthLimit

setWriteBandwidthLimit

public void setWriteBandwidthLimit(long bytesPerSecond)

Description copied from interface: BrowserUpProxy

Sets the maximum bandwidth to consume when sending requests to servers.

Specified by:

setWriteBandwidthLimit in interface BrowserUpProxy

Parameters:

bytesPerSecond - maximum bandwidth, in bytes per second

getWriteBandwidthLimit

public long getWriteBandwidthLimit()

Description copied from interface: BrowserUpProxy

Returns the current bandwidth limit for writing, in bytes per second.

Specified by:

getWriteBandwidthLimit in interface BrowserUpProxy

Returns:

WriteBandwidthLimit

endPage

public void endPage()

addHeaders

public void addHeaders(java.util.Map<java.lang.String,java.lang.String> headers)

Description copied from interface: BrowserUpProxy

Adds the specified HTTP headers to every request. Replaces any existing additional headers with the specified headers.

Specified by:

addHeaders in interface BrowserUpProxy

Parameters:

headers - Map<header name, header value> to append to every request.

setLatency

public void setLatency(long latency,
                       java.util.concurrent.TimeUnit timeUnit)

Description copied from interface: BrowserUpProxy

The minimum amount of time that will elapse between the time the proxy begins receiving a response from the server and the time the proxy begins sending the response to the client.

Specified by:

setLatency in interface BrowserUpProxy

Parameters:

latency - minimum latency, or 0 for no minimum

timeUnit - TimeUnit for the latency

autoAuthorization

public void autoAuthorization(java.lang.String domain,
                              java.lang.String username,
                              java.lang.String password,
                              AuthType authType)

Description copied from interface: BrowserUpProxy

Enables automatic authorization for the specified domain and auth type. Every request sent to the specified domain will contain the specified authorization information.

Specified by:

autoAuthorization in interface BrowserUpProxy

Parameters:

domain - domain automatically send authorization information to

username - authorization username

password - authorization password

authType - authorization type

stopAutoAuthorization

public void stopAutoAuthorization(java.lang.String domain)

Description copied from interface: BrowserUpProxy

Stops automatic authorization for the specified domain.

Specified by:

stopAutoAuthorization in interface BrowserUpProxy

Parameters:

domain - domain to stop automatically sending authorization information to

chainedProxyAuthorization

public void chainedProxyAuthorization(java.lang.String username,
                                      java.lang.String password,
                                      AuthType authType)

Description copied from interface: BrowserUpProxy

Enables chained proxy authorization using the Proxy-Authorization header described in RFC 7235, section 4.4 (https://tools.ietf.org/html/rfc7235#section-4.4). Currently, only AuthType.BASIC authentication is supported.

Specified by:

chainedProxyAuthorization in interface BrowserUpProxy

Parameters:

username - the username to use to authenticate with the chained proxy

password - the password to use to authenticate with the chained proxy

authType - the auth type to use (currently, must be BASIC)

setConnectTimeout

public void setConnectTimeout(int connectTimeout,
                              java.util.concurrent.TimeUnit timeUnit)

Description copied from interface: BrowserUpProxy

Maximum amount of time to wait to establish a connection to a remote server. If the connection has not been established within the specified time, the proxy will respond with an HTTP 502 Bad Gateway. The default value is 60 seconds.

Specified by:

setConnectTimeout in interface BrowserUpProxy

Parameters:

connectTimeout - maximum time to wait to establish a connection to a server, or 0 to wait indefinitely

timeUnit - TimeUnit for the connectionTimeout

setIdleConnectionTimeout

public void setIdleConnectionTimeout(int idleConnectionTimeout,
                                     java.util.concurrent.TimeUnit timeUnit)

The LittleProxy implementation only allows idle connection timeouts to be specified in seconds. idleConnectionTimeouts greater than 0 but less than 1 second will be set to 1 second; otherwise, values will be truncated (i.e. 1500ms will become 1s).

Specified by:

setIdleConnectionTimeout in interface BrowserUpProxy

Parameters:

idleConnectionTimeout - maximum time to allow a connection to remain idle, or 0 to wait indefinitely.

timeUnit - TimeUnit for the idleConnectionTimeout

setRequestTimeout

public void setRequestTimeout(int requestTimeout,
                              java.util.concurrent.TimeUnit timeUnit)

Description copied from interface: BrowserUpProxy

Maximum amount of time to wait for an HTTP response from the remote server after the request has been sent in its entirety. The HTTP request must complete within the specified time. If the proxy has not yet begun to forward the response to the client, the proxy will respond with an HTTP 504 Gateway Timeout. If the proxy has already started forwarding the response to the client, the connection to the client may be closed abruptly. The default value is 0 (wait indefinitely).

Specified by:

setRequestTimeout in interface BrowserUpProxy

Parameters:

requestTimeout - maximum time to wait for an HTTP response, or 0 to wait indefinitely

timeUnit - TimeUnit for the requestTimeout

rewriteUrl

public void rewriteUrl(java.lang.String pattern,
                       java.lang.String replace)

Description copied from interface: BrowserUpProxy

Adds a rewrite rule for the specified URL-matching regular expression. If there are any existing rewrite rules, the new rewrite rule will be applied last, after all other rewrite rules are applied. The specified urlPattern will be replaced with the specified replacement expression. The urlPattern is treated as a Java regular expression and must be properly escaped (see Pattern). The replacementExpression may consist of capture groups specified in the urlPattern, denoted by a $ (see Matcher.appendReplacement(StringBuffer, String). For HTTP requests (not HTTPS), if the hostname and/or port is changed as a result of a rewrite rule, the Host header of the request will be modified to reflect the updated hostname/port. For HTTPS requests, the host and port cannot be changed by rewrite rules (use BrowserUpProxy.getHostNameResolver() and AdvancedHostResolver.remapHost(String, String) to direct HTTPS requests to a different host). Note: The rewriting applies to the entire URL, including scheme (http:// or https://), hostname/address, port, and query string. Note that this means a urlPattern of "http://www\.website\.com/page" will NOT match http://www.website.com:80/page. For example, the following rewrite rule:

    proxy.rewriteUrl("http://www\\.(yahoo|bing)\\.com/\\?(\\w+)=(\\w+)", "http://www.google.com/?originalDomain=$1&$2=$3");

will match an HTTP request (but not HTTPS!) to www.yahoo.com or www.bing.com with exactly 1 query parameter, and replace it with a call to www.google.com with an 'originalDomain' query parameter, as well as the original query parameter. When applied to the URL:

    http://www.yahoo.com?theFirstParam=someValue

will result in the proxy making a request to:

    http://www.google.com?originalDomain=yahoo&theFirstParam=someValue

When applied to the URL:

    http://www.bing.com?anotherParam=anotherValue

will result in the proxy making a request to:

    http://www.google.com?originalDomain=bing&anotherParam=anotherValue

Specified by:

rewriteUrl in interface BrowserUpProxy

Parameters:

pattern - URL-matching regular expression

replace - an expression, which may optionally contain capture groups, which will replace any URL which matches urlPattern

rewriteUrls

public void rewriteUrls(java.util.Map<java.lang.String,java.lang.String> rewriteRules)

Description copied from interface: BrowserUpProxy

Replaces existing rewrite rules with the specified patterns and replacement expressions. The rules will be applied in the order specified by the Map's iterator. See BrowserUpProxy.rewriteUrl(String, String) for details on the format of the rewrite rules.

Specified by:

rewriteUrls in interface BrowserUpProxy

Parameters:

rewriteRules - Map<urlPattern, replacementExpression>

clearRewriteRules

public void clearRewriteRules()

Description copied from interface: BrowserUpProxy

Clears all existing rewrite rules.

Specified by:

clearRewriteRules in interface BrowserUpProxy

blacklistRequests

public void blacklistRequests(java.lang.String pattern,
                              int responseCode)

Description copied from interface: BrowserUpProxy

Adds a URL-matching regular expression to the blacklist. Requests that match a blacklisted URL will return the specified HTTP statusCode for all HTTP methods. If there are existing patterns on the blacklist, the urlPattern will be evaluated last, after the URL is checked against all other blacklist entries. The urlPattern matches the full URL of the request, including scheme, host, and port, path, and query parameters for both HTTP and HTTPS requests. For example, to blacklist both HTTP and HTTPS requests to www.google.com, use a urlPattern of "https?://www\\.google\\.com/.*".

Specified by:

blacklistRequests in interface BrowserUpProxy

Parameters:

pattern - URL-matching regular expression to blacklist

responseCode - HTTP status code to return

blacklistRequests

public void blacklistRequests(java.lang.String pattern,
                              int responseCode,
                              java.lang.String method)

Description copied from interface: BrowserUpProxy

Adds a URL-matching regular expression to the blacklist. Requests that match a blacklisted URL will return the specified HTTP statusCode only when the request's HTTP method (GET, POST, PUT, etc.) matches the specified httpMethodPattern regular expression. If there are existing patterns on the blacklist, the urlPattern will be evaluated last, after the URL is checked against all other blacklist entries. See BrowserUpProxy.blacklistRequests(String, int) for details on the URL the urlPattern will match.

Specified by:

blacklistRequests in interface BrowserUpProxy

Parameters:

pattern - URL-matching regular expression to blacklist

responseCode - HTTP status code to return

method - regular expression matching a request's HTTP method

setBlacklist

public void setBlacklist(java.util.Collection<BlacklistEntry> blacklist)

Description copied from interface: BrowserUpProxy

Replaces any existing blacklist with the specified blacklist. URLs will be evaluated against the blacklist in the order specified by the Collection's iterator.

Specified by:

setBlacklist in interface BrowserUpProxy

Parameters:

blacklist - new blacklist entries

getBlacklist

public java.util.Collection<BlacklistEntry> getBlacklist()

Description copied from interface: BrowserUpProxy

Returns all blacklist entries currently in effect. Iterating over the returned Collection is guaranteed to return blacklist entries in the order in which URLs are actually evaluated against the blacklist.

Specified by:

getBlacklist in interface BrowserUpProxy

Returns:

blacklist entries, or an empty collection if none exist

isWhitelistEnabled

public boolean isWhitelistEnabled()

Description copied from interface: BrowserUpProxy

Returns true if the whitelist is enabled, otherwise false.

Specified by:

isWhitelistEnabled in interface BrowserUpProxy

Returns:

is WhitelistEnabled

getWhitelistUrls

public java.util.Collection<java.lang.String> getWhitelistUrls()

Description copied from interface: BrowserUpProxy

Returns the URL-matching regular expressions currently in effect. If the whitelist is disabled, this method always returns an empty collection. If the whitelist is enabled but empty, this method return an empty collection.

Specified by:

getWhitelistUrls in interface BrowserUpProxy

Returns:

whitelist currently in effect, or an empty collection if the whitelist is disabled or empty

getWhitelistStatusCode

public int getWhitelistStatusCode()

Description copied from interface: BrowserUpProxy

Returns the status code returned for all URLs that do not match the whitelist. If the whitelist is not currently enabled, returns -1.

Specified by:

getWhitelistStatusCode in interface BrowserUpProxy

Returns:

HTTP status code returned for non-whitelisted URLs, or -1 if the whitelist is disabled.

clearBlacklist

public void clearBlacklist()

Description copied from interface: BrowserUpProxy

Clears any existing blacklist.

Specified by:

clearBlacklist in interface BrowserUpProxy

whitelistRequests

public void whitelistRequests(java.util.Collection<java.lang.String> urlPatterns,
                              int statusCode)

Description copied from interface: BrowserUpProxy

Whitelists URLs matching the specified regular expression patterns. Replaces any existing whitelist. The urlPattern matches the full URL of the request, including scheme, host, and port, path, and query parameters for both HTTP and HTTPS requests. For example, to whitelist both HTTP and HTTPS requests to www.google.com, use a urlPattern of "https?://www\\.google\\.com/.*". Note: All HTTP CONNECT requests are automatically whitelisted and cannot be short-circuited using the whitelist response code.

Specified by:

whitelistRequests in interface BrowserUpProxy

Parameters:

urlPatterns - URL-matching regular expressions to whitelist; null or an empty collection will enable an empty whitelist

statusCode - HTTP status code to return to clients when a URL matches a pattern

addWhitelistPattern

public void addWhitelistPattern(java.lang.String urlPattern)

Description copied from interface: BrowserUpProxy

Adds a URL-matching regular expression to an existing whitelist.

Specified by:

addWhitelistPattern in interface BrowserUpProxy

Parameters:

urlPattern - URL-matching regular expressions to whitelist

whitelistRequests

public void whitelistRequests(java.lang.String[] patterns,
                              int responseCode)

Whitelist the specified request patterns, returning the specified responseCode for non-whitelisted requests.

Parameters:

patterns - regular expression strings matching URL patterns to whitelist. if empty or null, the whitelist will be enabled but will not match any URLs.

responseCode - the HTTP response code to return for non-whitelisted requests

enableEmptyWhitelist

public void enableEmptyWhitelist(int statusCode)

Description copied from interface: BrowserUpProxy

Enables the whitelist, but with no matching URLs. All requests will generated the specified HTTP statusCode.

Specified by:

enableEmptyWhitelist in interface BrowserUpProxy

Parameters:

statusCode - HTTP status code to return to clients on all requests

disableWhitelist

public void disableWhitelist()

Description copied from interface: BrowserUpProxy

Clears any existing whitelist and disables whitelisting.

Specified by:

disableWhitelist in interface BrowserUpProxy

addHeader

public void addHeader(java.lang.String name,
                      java.lang.String value)

Description copied from interface: BrowserUpProxy

Adds a new HTTP header to every request. If the header already exists on the request, it will be replaced with the specified header.

Specified by:

addHeader in interface BrowserUpProxy

Parameters:

name - name of the header to add

value - new header's value

removeHeader

public void removeHeader(java.lang.String name)

Description copied from interface: BrowserUpProxy

Removes a header previously added with BrowserUpProxy.addHeader(String name, String value).

Specified by:

removeHeader in interface BrowserUpProxy

Parameters:

name - previously-added header's name

removeAllHeaders

public void removeAllHeaders()

Description copied from interface: BrowserUpProxy

Removes all headers previously added with BrowserUpProxy.addHeader(String name, String value).

Specified by:

removeAllHeaders in interface BrowserUpProxy

getAllHeaders

public java.util.Map<java.lang.String,java.lang.String> getAllHeaders()

Description copied from interface: BrowserUpProxy

Returns all headers previously added with BrowserUpProxy.addHeader(String name, String value).

Specified by:

getAllHeaders in interface BrowserUpProxy

Returns:

Map<header name, header value>

setHostNameResolver

public void setHostNameResolver(AdvancedHostResolver resolver)

Description copied from interface: BrowserUpProxy

Sets the resolver that will be used to look up host names. To chain multiple resolvers, wrap a list of resolvers in a ChainedHostResolver.

Specified by:

setHostNameResolver in interface BrowserUpProxy

Parameters:

resolver - host name resolver

getHostNameResolver

public AdvancedHostResolver getHostNameResolver()

Description copied from interface: BrowserUpProxy

Returns the current host name resolver.

Specified by:

getHostNameResolver in interface BrowserUpProxy

Returns:

current host name resolver

waitForQuiescence

public boolean waitForQuiescence(long quietPeriod,
                                 long timeout,
                                 java.util.concurrent.TimeUnit timeUnit)

Description copied from interface: BrowserUpProxy

Waits for existing network traffic to stop, and for the specified quietPeriod to elapse. Returns true if there is no network traffic for the quiet period within the specified timeout, otherwise returns false.

Specified by:

waitForQuiescence in interface BrowserUpProxy

Parameters:

quietPeriod - amount of time after which network traffic will be considered "stopped"

timeout - maximum amount of time to wait for network traffic to stop

timeUnit - TimeUnit for the quietPeriod and timeout

Returns:

true if network traffic is stopped, otherwise false

setChainedProxy

public void setChainedProxy(java.net.InetSocketAddress chainedProxyAddress)

Instructs this proxy to route traffic through an upstream proxy. Note: Using setChainedProxyManager(ChainedProxyManager) will supersede any value set by this method. A chained proxy must be set before the proxy is started, though it can be changed after the proxy is started.

Specified by:

setChainedProxy in interface BrowserUpProxy

Parameters:

chainedProxyAddress - address of the upstream proxy

getChainedProxy

public java.net.InetSocketAddress getChainedProxy()

Description copied from interface: BrowserUpProxy

Returns the address and port of the upstream proxy.

Specified by:

getChainedProxy in interface BrowserUpProxy

Returns:

address and port of the upstream proxy, or null of there is none.

setChainedProxyManager

public void setChainedProxyManager(org.littleshoot.proxy.ChainedProxyManager chainedProxyManager)

Allows access to the LittleProxy ChainedProxyManager for fine-grained control of the chained proxies. To enable a single chained proxy, BrowserUpProxy.setChainedProxy(InetSocketAddress) is generally more convenient. Note: The chained proxy manager must be enabled before calling start().

Parameters:

chainedProxyManager - chained proxy manager to enable

setThreadPoolConfiguration

public void setThreadPoolConfiguration(org.littleshoot.proxy.impl.ThreadPoolConfiguration threadPoolConfiguration)

Configures the Netty thread pool used by the LittleProxy back-end. See ThreadPoolConfiguration for details.

Parameters:

threadPoolConfiguration - thread pool configuration to use

addFirstHttpFilterFactory

public void addFirstHttpFilterFactory(org.littleshoot.proxy.HttpFiltersSource filterFactory)

Description copied from interface: BrowserUpProxy

Adds a new filter factory (request/response interceptor) to the beginning of the HttpFilters chain. Usage note: The actual filter (interceptor) instance is created on every request by implementing the HttpFiltersSource.filterRequest(io.netty.handler.codec.http.HttpRequest, io.netty.channel.ChannelHandlerContext) method and returning an HttpFilters instance (typically, a subclass of HttpFiltersAdapter). To disable or bypass a filter on a per-request basis, the filterRequest() method may return null.

Specified by:

addFirstHttpFilterFactory in interface BrowserUpProxy

Parameters:

filterFactory - factory to generate HttpFilters

addLastHttpFilterFactory

public void addLastHttpFilterFactory(org.littleshoot.proxy.HttpFiltersSource filterFactory)

Description copied from interface: BrowserUpProxy

Adds a new filter factory (request/response interceptor) to the end of the HttpFilters chain. Usage note: The actual filter (interceptor) instance is created on every request by implementing the HttpFiltersSource.filterRequest(io.netty.handler.codec.http.HttpRequest, io.netty.channel.ChannelHandlerContext) method and returning an HttpFilters instance (typically, a subclass of HttpFiltersAdapter). To disable or bypass a filter on a per-request basis, the filterRequest() method may return null.

Specified by:

addLastHttpFilterFactory in interface BrowserUpProxy

Parameters:

filterFactory - factory to generate HttpFilters

addResponseFilter

public void addResponseFilter(ResponseFilter filter)

Note: The current implementation of this method forces a maximum response size of 2 MiB. To adjust the maximum response size, or to disable aggregation (which disallows access to the HttpMessageContents), you may add the filter source directly: addFirstHttpFilterFactory(new ResponseFilterAdapter.FilterSource(filter, bufferSizeInBytes));

Specified by:

addResponseFilter in interface BrowserUpProxy

Parameters:

filter - filter instance

addRequestFilter

public void addRequestFilter(RequestFilter filter)

Note: The current implementation of this method forces a maximum request size of 2 MiB. To adjust the maximum request size, or to disable aggregation (which disallows access to the HttpMessageContents), you may add the filter source directly: addFirstHttpFilterFactory(new RequestFilterAdapter.FilterSource(filter, bufferSizeInBytes));

Specified by:

addRequestFilter in interface BrowserUpProxy

Parameters:

filter - filter instance

getRewriteRules

public java.util.Map<java.lang.String,java.lang.String> getRewriteRules()

Description copied from interface: BrowserUpProxy

Returns all rewrite rules currently in effect. Iterating over the returned Map is guaranteed to return rewrite rules in the order in which the rules are actually applied.

Specified by:

getRewriteRules in interface BrowserUpProxy

Returns:

Map<URL-matching regex, replacement expression>

removeRewriteRule

public void removeRewriteRule(java.lang.String urlPattern)

Description copied from interface: BrowserUpProxy

Removes an existing rewrite rule whose urlPattern matches the specified pattern.

Specified by:

removeRewriteRule in interface BrowserUpProxy

Parameters:

urlPattern - rewrite rule pattern to remove

isStopped

public boolean isStopped()

getCurrentHarPage

public HarPage getCurrentHarPage()

addHttpFilterFactory

public void addHttpFilterFactory(org.littleshoot.proxy.HttpFiltersSource filterFactory)

getFilterFactories

public java.util.List<org.littleshoot.proxy.HttpFiltersSource> getFilterFactories()

setMitmDisabled

public void setMitmDisabled(boolean mitmDisabled)
                     throws java.lang.IllegalStateException

Description copied from interface: BrowserUpProxy

Completely disables MITM for this proxy server. The proxy will no longer intercept HTTPS requests, but they will still be pass-through proxied. This option must be set before the proxy is started; otherwise an IllegalStateException will be thrown.

Specified by:

setMitmDisabled in interface BrowserUpProxy

Parameters:

mitmDisabled - when true, MITM capture will be disabled

Throws:

java.lang.IllegalStateException - if the proxy is already started

setMitmManager

public void setMitmManager(org.littleshoot.proxy.MitmManager mitmManager)

Description copied from interface: BrowserUpProxy

Sets the MITM manager, which is responsible for generating forged SSL certificates to present to clients. By default, BrowserUp Proxy uses the ca-certificate-rsa.cer root certificate for impersonation. See the documentation at ImpersonatingMitmManager and ImpersonatingMitmManager.Builder for details on customizing the root and server certificate generation.

Specified by:

setMitmManager in interface BrowserUpProxy

Parameters:

mitmManager - MITM manager to use

setTrustAllServers

public void setTrustAllServers(boolean trustAllServers)

Description copied from interface: BrowserUpProxy

Disables verification of all upstream servers' SSL certificates. All upstream servers will be trusted, even if they do not present valid certificates signed by certification authorities in the JDK's trust store. This option exposes the proxy to MITM attacks and should only be used when testing in trusted environments.

Specified by:

setTrustAllServers in interface BrowserUpProxy

Parameters:

trustAllServers - when true, disables upstream server certificate verification

setTrustSource

public void setTrustSource(com.browserup.bup.mitm.TrustSource trustSource)

Description copied from interface: BrowserUpProxy

Sets the TrustSource that contains trusted root certificate authorities that will be used to validate upstream servers' certificates. When null, disables certificate validation (see warning at BrowserUpProxy.setTrustAllServers(boolean)).

Specified by:

setTrustSource in interface BrowserUpProxy

Parameters:

trustSource - TrustSource containing root CAs, or null to disable upstream server validation

findMostRecentEntry

public java.util.Optional<HarEntry> findMostRecentEntry(java.util.regex.Pattern url)

Description copied from interface: BrowserUpProxy

Search the entire log for the most recent entry whose request URL matches the given url.

Specified by:

findMostRecentEntry in interface BrowserUpProxy

Parameters:

url - Regular expression match of URL to find. URLs are formatted as: scheme://host:port/path?querystring. Port is not included in the URL if it is the standard port for the scheme. Fragments (example.com/#fragment) should not be included in the URL. If more than one URL found, return the most recently requested URL. Pattern examples: - Match a URL with "http" or "https" protocol, "example.com" domain, and "/index.html" exact file path, with no query parameters: "^(http|https)://example\\.com/index\\.html$" - Match a URL with "http" protocol, "example.com" domain, "/customer" exact path, followed by any query string: "^http://example\\.com/customer\\?.*" - Match a URL with "http" protocol, "example.com" domain, "/products" path, and exactly 1 UUID query parameter named "id": "^http://example\\.com/products\\?id=[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{12}$"

Returns:

HarEntry for the most recently requested URL matching the given url pattern.

findEntries

public java.util.Collection<HarEntry> findEntries(java.util.regex.Pattern url)

Description copied from interface: BrowserUpProxy

Search the entire log for entries whose request URL matches the given url.

Specified by:

findEntries in interface BrowserUpProxy

Parameters:

url - Regular expression match of URL to find. URLs are formatted as: scheme://host:port/path?querystring. Port is not included in the URL if it is the standard port for the scheme. Fragments (example.com/#fragment) should not be included in the URL. If more than one URL found, use the most recently requested URL. Pattern examples: - Match a URL with "http" or "https" protocol, "example.com" domain, and "/index.html" exact file path, with no query parameters: "^(http|https)://example\\.com/index\\.html$" - Match a URL with "http" protocol, "example.com" domain, "/customer" exact path, followed by any query string: "^http://example\\.com/customer\\?.*" - Match a URL with "http" protocol, "example.com" domain, "/products" path, and exactly 1 UUID query parameter named "id": "^http://example\\.com/products\\?id=[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{12}$"

Returns:

A list of HarEntry for any requests whose URL matches the given url pattern, or an empty list if none match.

assertMostRecentUrlResponseTimeWithin

public AssertionResult assertMostRecentUrlResponseTimeWithin(java.util.regex.Pattern url,
                                                             long time)

Specified by:

assertMostRecentUrlResponseTimeWithin in interface BrowserUpProxy

isMitmDisabled

public boolean isMitmDisabled()

setUseEcc

public void setUseEcc(boolean useEcc)

addBrowserUpFilters

protected void addBrowserUpFilters()

Adds the basic BrowserUp-proxy filters, except for the relatively-expensive HAR capture filter.

addHarCaptureFilter

protected void addHarCaptureFilter()

Enables the HAR capture filter if it has not already been enabled. The filter will be added to the end of the filter chain. The HAR capture filter is relatively expensive, so this method is only called when a HAR is requested.