public interface BrowserMobProxy
Modifier and Type | Method and Description |
---|---|
void |
abort()
Like
stop() , shuts down the proxy server and no longer accepts incoming connections, but does not wait for any existing
network traffic to cease. |
void |
addFirstHttpFilterFactory(org.littleshoot.proxy.HttpFiltersSource filterFactory)
Adds a new filter factory (request/response interceptor) to the beginning of the HttpFilters chain.
|
void |
addHeader(String name,
String value)
Adds a new HTTP header to every request.
|
void |
addHeaders(Map<String,String> headers)
Adds the specified HTTP headers to every request.
|
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)
Adds a new RequestFilter that can be used to examine and manipulate the request before sending it to the server.
|
void |
addResponseFilter(ResponseFilter filter)
Adds a new ResponseFilter that can be used to examine and manipulate the response before sending it to the client.
|
void |
addWhitelistPattern(String urlPattern)
Adds a URL-matching regular expression to an existing whitelist.
|
void |
autoAuthorization(String domain,
String username,
String password,
AuthType authType)
Enables automatic authorization for the specified domain and auth type.
|
void |
blacklistRequests(String urlPattern,
int statusCode)
Adds a URL-matching regular expression to the blacklist.
|
void |
blacklistRequests(String urlPattern,
int statusCode,
String httpMethodPattern)
Adds a URL-matching regular expression to the blacklist.
|
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(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(Set<CaptureType> captureTypes)
Enables the specified HAR capture types.
|
Har |
endHar()
Stops capturing traffic in the HAR.
|
Map<String,String> |
getAllHeaders()
Returns all headers previously added with
addHeader(String name, String value) . |
Collection<BlacklistEntry> |
getBlacklist()
Returns all blacklist entries currently in effect.
|
InetSocketAddress |
getChainedProxy()
Returns the address and port of the upstream proxy.
|
InetAddress |
getClientBindAddress()
Returns the address of the network interface on which the proxy is listening for client connections.
|
Har |
getHar()
Retrieves the current HAR.
|
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.
|
Map<String,String> |
getRewriteRules()
Returns all rewrite rules currently in effect.
|
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.
|
Collection<String> |
getWhitelistUrls()
Returns the URL-matching regular expressions currently in effect.
|
boolean |
isStarted()
Returns true if the proxy is started and listening for connections, otherwise false.
|
boolean |
isWhitelistEnabled()
Returns true if the whitelist is enabled, otherwise false.
|
Har |
newHar()
Starts a new HAR file with the default page name (see
newPage() . |
Har |
newHar(String initialPageRef)
Starts a new HAR file with the specified initialPageRef as the page name and page title.
|
Har |
newHar(String initialPageRef,
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(String pageRef)
Starts a new HAR page using the specified pageRef as the page name and the page title.
|
Har |
newPage(String pageRef,
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
addHeader(String name, String value) . |
void |
removeHeader(String name)
Removes a header previously added with
addHeader(String name, String value) . |
void |
removeRewriteRule(String urlPattern)
Removes an existing rewrite rule whose urlPattern matches the specified pattern.
|
void |
rewriteUrl(String urlPattern,
String replacementExpression)
Adds a rewrite rule for the specified URL-matching regular expression.
|
void |
rewriteUrls(Map<String,String> rewriteRules)
Replaces existing rewrite rules with the specified patterns and replacement expressions.
|
void |
setBlacklist(Collection<BlacklistEntry> blacklist)
Replaces any existing blacklist with the specified blacklist.
|
void |
setChainedProxy(InetSocketAddress chainedProxyAddress)
Sets an upstream proxy that this proxy will use to connect to external hosts.
|
void |
setConnectTimeout(int connectionTimeout,
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(Set<CaptureType> captureTypes)
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,
TimeUnit timeUnit)
Maximum amount of time to allow a connection to remain idle.
|
void |
setLatency(long latency,
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,
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 |
setTrustAllServers(boolean trustAllServers)
Disables verification of all upstream servers' SSL certificates.
|
void |
setTrustSource(TrustSource trustSource)
Sets the
TrustSource that contains trusted root certificate authorities that will be used to validate
upstream servers' certificates. |
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,
InetAddress bindAddress)
Starts the proxy on the specified port.
|
void |
start(int port,
InetAddress clientBindAddress,
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.
|
void |
stopAutoAuthorization(String domain)
Stops automatic authorization for the specified domain.
|
boolean |
waitForQuiescence(long quietPeriod,
long timeout,
TimeUnit timeUnit)
Waits for existing network traffic to stop, and for the specified quietPeriod to elapse.
|
void |
whitelistRequests(Collection<String> urlPatterns,
int statusCode)
Whitelists URLs matching the specified regular expression patterns.
|
void start()
IllegalStateException
- if the proxy has already been startedvoid start(int port)
port
- port to listen onIllegalStateException
- if the proxy has already been startedvoid start(int port, InetAddress bindAddress)
port
- port to listen onbindAddress
- address of the network interface on which the proxy will listen for connections and also attempt to connect to upstream servers.IllegalStateException
- if the proxy has already been startedvoid start(int port, InetAddress clientBindAddress, InetAddress serverBindAddress)
port
- port to listen onclientBindAddress
- address of the network interface on which the proxy will listen for connectionsserverBindAddress
- address of the network interface on which the proxy will connect to upstream serversIllegalStateException
- if the proxy has already been startedboolean isStarted()
void stop()
IllegalStateException
- if the proxy has not been started.void abort()
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.IllegalStateException
- if the proxy has not been startedInetAddress getClientBindAddress()
int getPort()
IllegalStateException
- if the proxy has not been startedInetAddress getServerBindAddress()
Har getHar()
Har newHar()
newPage()
. Enables HAR capture if it was not previously enabled.Har newHar(String initialPageRef)
initialPageRef
- initial page name of the new HAR fileHar newHar(String initialPageRef, String initialPageTitle)
initialPageRef
- initial page name of the new HAR fileinitialPageTitle
- initial page title of the new HAR filevoid setHarCaptureTypes(Set<CaptureType> captureTypes)
CaptureType
data types. CaptureType
provides several
convenience methods to retrieve commonly-used capture settings.
Note: HAR capture must still be explicitly enabled via newHar()
or newHar(String)
to begin capturing
any request and response contents.captureTypes
- HAR data types to capturevoid setHarCaptureTypes(CaptureType... captureTypes)
CaptureType
data types. CaptureType
provides several
convenience methods to retrieve commonly-used capture settings.
Note: HAR capture must still be explicitly enabled via newHar()
or newHar(String)
to begin capturing
any request and response contents.captureTypes
- HAR data types to captureEnumSet<CaptureType> getHarCaptureTypes()
void enableHarCaptureTypes(Set<CaptureType> captureTypes)
captureTypes
- capture types to enablevoid enableHarCaptureTypes(CaptureType... captureTypes)
captureTypes
- capture types to enablevoid disableHarCaptureTypes(Set<CaptureType> captureTypes)
captureTypes
- capture types to disablevoid disableHarCaptureTypes(CaptureType... captureTypes)
captureTypes
- capture types to disableHar newPage()
newHar()
or newHar(String)
is called, and increments on every subsequent call to newPage()
or
newHar(String)
. Populates the HarPageTimings.onLoad
value based on the amount of time
the current page has been captured.IllegalStateException
- if HAR capture has not been enabled via newHar()
or newHar(String)
Har newPage(String pageRef)
HarPageTimings.onLoad
value based on the amount of time the current page has been captured.pageRef
- name of the new pageIllegalStateException
- if HAR capture has not been enabled via newHar()
or newHar(String)
Har newPage(String pageRef, String pageTitle)
HarPageTimings.onLoad
value based on the amount of time the current page has been captured.pageRef
- name of the new pagepageTitle
- title of the new pageIllegalStateException
- if HAR capture has not been enabled via newHar()
or newHar(String)
Har endHar()
HarPageTimings.onLoad
value for the current page
based on the amount of time it has been captured.void setReadBandwidthLimit(long bytesPerSecond)
bytesPerSecond
- maximum bandwidth, in bytes per secondvoid setWriteBandwidthLimit(long bytesPerSecond)
bytesPerSecond
- maximum bandwidth, in bytes per secondvoid setLatency(long latency, TimeUnit timeUnit)
latency
- minimum latency, or 0 for no minimumtimeUnit
- TimeUnit for the latencyvoid setConnectTimeout(int connectionTimeout, TimeUnit timeUnit)
connectionTimeout
- maximum time to wait to establish a connection to a server, or 0 to wait indefinitelytimeUnit
- TimeUnit for the connectionTimeoutvoid setIdleConnectionTimeout(int idleConnectionTimeout, TimeUnit timeUnit)
idleConnectionTimeout
- maximum time to allow a connection to remain idle, or 0 to wait indefinitely.timeUnit
- TimeUnit for the idleConnectionTimeoutvoid setRequestTimeout(int requestTimeout, TimeUnit timeUnit)
requestTimeout
- maximum time to wait for an HTTP response, or 0 to wait indefinitelytimeUnit
- TimeUnit for the requestTimeoutvoid autoAuthorization(String domain, String username, String password, AuthType authType)
domain
- domain automatically send authorization information tousername
- authorization usernamepassword
- authorization passwordauthType
- authorization typevoid stopAutoAuthorization(String domain)
domain
- domain to stop automatically sending authorization information tovoid rewriteUrl(String urlPattern, String replacementExpression)
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 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
urlPattern
- URL-matching regular expressionreplacementExpression
- an expression, which may optionally contain capture groups, which will replace any URL which matches urlPatternvoid rewriteUrls(Map<String,String> rewriteRules)
rewriteUrl(String, String)
for details on the format of the rewrite rules.rewriteRules
- Map<urlPattern, replacementExpression>
Map<String,String> getRewriteRules()
Map<URL-matching regex, replacement expression>
void removeRewriteRule(String urlPattern)
urlPattern
- rewrite rule pattern to removevoid clearRewriteRules()
void blacklistRequests(String urlPattern, int statusCode)
urlPattern
- URL-matching regular expression to blackliststatusCode
- HTTP status code to returnvoid blacklistRequests(String urlPattern, int statusCode, String httpMethodPattern)
blacklistRequests(String, int)
for details on the URL the urlPattern will match.urlPattern
- URL-matching regular expression to blackliststatusCode
- HTTP status code to returnhttpMethodPattern
- regular expression matching a request's HTTP methodvoid setBlacklist(Collection<BlacklistEntry> blacklist)
blacklist
- new blacklist entriesCollection<BlacklistEntry> getBlacklist()
void clearBlacklist()
void whitelistRequests(Collection<String> urlPatterns, int statusCode)
urlPatterns
- URL-matching regular expressions to whitelist; null or an empty collection will enable an empty whiteliststatusCode
- HTTP status code to return to clients when a URL matches a patternvoid addWhitelistPattern(String urlPattern)
urlPattern
- URL-matching regular expressions to whitelistIllegalStateException
- if the whitelist is not enabledvoid enableEmptyWhitelist(int statusCode)
statusCode
- HTTP status code to return to clients on all requestsvoid disableWhitelist()
Collection<String> getWhitelistUrls()
int getWhitelistStatusCode()
boolean isWhitelistEnabled()
void addHeaders(Map<String,String> headers)
headers
- Map<header name, header value>
to append to every request.void addHeader(String name, String value)
name
- name of the header to addvalue
- new header's valuevoid removeHeader(String name)
addHeader(String name, String value)
.name
- previously-added header's namevoid removeAllHeaders()
addHeader(String name, String value)
.Map<String,String> getAllHeaders()
addHeader(String name, String value)
.Map<header name, header value>
void setHostNameResolver(AdvancedHostResolver resolver)
ChainedHostResolver
.resolver
- host name resolverAdvancedHostResolver getHostNameResolver()
boolean waitForQuiescence(long quietPeriod, long timeout, TimeUnit timeUnit)
quietPeriod
- amount of time after which network traffic will be considered "stopped"timeout
- maximum amount of time to wait for network traffic to stoptimeUnit
- TimeUnit for the quietPeriod and timeoutvoid setChainedProxy(InetSocketAddress chainedProxyAddress)
chainedProxyAddress
- address and port of the upstream proxy, or null to remove an upstream proxyInetSocketAddress getChainedProxy()
void addFirstHttpFilterFactory(org.littleshoot.proxy.HttpFiltersSource filterFactory)
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.
Note: This method is only available in the LittleProxy-based implementation of BrowserMob Proxy. The legacy ProxyServer
implementation will not use the HTTP filters. You must use the addRequestInterceptor() and addResponseInterceptor() methods in
LegacyProxyServer
when using the legacy ProxyServer implementation.filterFactory
- factory to generate HttpFiltersvoid addLastHttpFilterFactory(org.littleshoot.proxy.HttpFiltersSource filterFactory)
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.
Note: This method is only available in the LittleProxy-based implementation of BrowserMob Proxy. The legacy ProxyServer
implementation will not use the HTTP filters. You must use the addRequestInterceptor() and addResponseInterceptor() methods in
LegacyProxyServer
when using the legacy ProxyServer implementation.filterFactory
- factory to generate HttpFiltersvoid addResponseFilter(ResponseFilter filter)
filter
- filter instancevoid addRequestFilter(RequestFilter filter)
filter
- filter instancevoid setMitmDisabled(boolean mitmDisabled)
mitmDisabled
- when true, MITM capture will be disabledIllegalStateException
- if the proxy is already startedvoid setMitmManager(org.littleshoot.proxy.MitmManager mitmManager)
ImpersonatingMitmManager
and ImpersonatingMitmManager.Builder
for details on customizing the root and server certificate generation.mitmManager
- MITM manager to usevoid setTrustAllServers(boolean trustAllServers)
trustAllServers
- when true, disables upstream server certificate verificationvoid setTrustSource(TrustSource trustSource)
TrustSource
that contains trusted root certificate authorities that will be used to validate
upstream servers' certificates. When null, disables certificate validation (see warning at setTrustAllServers(boolean)
).trustSource
- TrustSource containing root CAs, or null to disable upstream server validationCopyright © 2016. All Rights Reserved.