Installation

Install Ekko Proxy, a simple service virtualization utility that can be used to monitor, record, playback or mock web service and database messages, by simply downloading and running it as per instructions below.

Did you know that virtualizing critical APIs can drastically help reduce dependencies and delays during the delivery pipeline.

Prerequisites

Ekko Proxy is packaged as a 'fat' jar and only requires Java 8 or later to run on your local machine or server.

Download

Ekko Proxy can be downloaded from here and from github. The Ekko Proxy JDBC driver, needed by a client application to connect to a JDBC proxy instance, can be downloaded from here: ekkoproxyjdbc-1.5.jar or found following the github link.

Running

Once downloaded Ekko Proxy can be run from the command line:

 $ java -jar ekkoproxy-1.6.jar

If you indend to use the JDBC database proxies then you will need to add your JDBC driver to the classpath. This can be done as per below example:

 $ java -Dloader.path=C:/Apps/oracle/ -Dloader.main=com.lcasoft.ekkoproxy.EkkoProxyApplication -jar target/ekkoproxy-1.6.jar org.springframework.boot.loader.PropertiesLauncher

The loader.path should be set to the location of where your JDBC driver is e.g. ojdbc14-10.2.0.2.jar

Application settings

The following application startup settings can be overridden on the command line and more than one can be specified at a time. E.g. setting a different server port can be done like this:

$ java -jar ekkoproxy-1.6.jar --server.port=8081

Setting	Description
server.port	Sets server port to access the application on. Defaults to 4040.
ekkoproxy.output.directory	Sets the output directory for any recorded messages. If set, users will not be able to specify it in the Ekko Proxy UI. Can be a relative or full path. If it does not exist then it will be created. E.g. --ekkoproxy.ui.output.directory=C:\\foo\\ekkoproxy or --ekkoproxy.ui.output.directory=./recordings
ekkoproxy.events.max	Sets the maximum number of messages (i.e. in memory history), per proxy, that can be viewed at anyone time. Defaults to 100. Note without a license this setting is ignored and a more limited number of messages are displayed.
ekkoproxy.http.connection.timeout	Sets the time (in milliseconds) to establish the connection with the remote host. Defaults to 0. Note a timeout value of zero is interpreted as the platform default which is usually anything from 20 seconds to minute depending on the operating system. Also you cannot specify a connection timeout that increases the platform default; you can only use it to decrease it from the platform default.
ekkoproxy.http.socket.timeout	Sets the time (in milliseconds) waiting for data – after establishing the connection; maximum time of inactivity between two data packets. A timeout value of zero is interpreted as an 'infinite' timeout. Defaults to 0.
ekkoproxy.threadpool.corePoolSize	The core pool size is the minimum number of threads always kept alive for request handling. Defaults to -1. Zero and negative values have special meaning as per below: 0 = means a pool size equal to the number of available processors. -1 = means a pool size equal to the number of available processors * 2. -2 = means a pool size equal to the number of available processors * 3. -3 = means a pool size equal to the number of available processors + 1. -4 = means a pool size equal to the number of available processors + 2. -5 = means available processors +3 and -6 would be +4 and so forth.
ekkoproxy.threadpool.maxPoolSize	The maximum number of active threads in the pool at anyone time. Defaults to 200. Zero and negative values work in the same way as the corePoolSize setting.
ekkoproxy.threadpool.keepAliveTime	The number of milliseconds the pool will keep idle/extra threads (above the core pool size) alive for. Defaults to 60000 (1 minute).
ekkoproxy.threadpool.queueSize	The maximum queue size for incoming requests when all possible request processing threads are in use. Any requests received when the queue is full will be refused. A value of zero means the queue is unbounded and requests would effectively never be rejected and you could run out of resources if requests keep coming in at a higher rate than they can be processed. Defaults to 100.
ekkoproxy.threadpool.prestartCoreThreads	Starts all core threads, causing them to be idly wait for work. Defaults to false.
server.tomcat.max-threads	The size of the thread pool of the embedded Tomcat web server. Defaults to 200. Note this is usually more than enough however if forwarding is being used extensively then it may be necessary to increase this number.
ekkoproxy.log.mock.miss	If true mock server misses will be logged with details of miss and nearest possible mock. Useful for debugging why a mock may not be triggering as expected. Defaults to false.
ekkoproxy.log.message.inout	If true the request & response message headers and content will be printed in the application log. Defaults to true.
ekkoproxy.log.message.inout.maxSize	Max request & response message size being logged. Only applicable if 'ekkoproxy.log.message.inout' is true. Defaults to 10240.
ekkoproxy.jdbc.maxRows	Sets the max rows to be fetched from the DB. Defaults to 10000. Note as the proxy processes the full result-set for display and recording/playback there needs to be limit to the number of rows stored in memory and on disk.
ekkoproxy.jdbc.fetchSize	Sets the statement/result-set fetch size. Defaults to 1000.
ekkoproxy.jdbc.connectionPooling	If true then DB connections created via a DriverManager (as opposed to DataSource) will be pooled using Apache commons dbcp2. Defaults to false.
ekkoproxy.jdbc.rmi.enabled	If true an RMI server will be created for the JDBC proxies allowing the EkkoProxyDriver to use RMI if specified in driver url. Defaults to true. Note when off only http can be used by the EkkoProxyDriver. RMI has better performance but can be harder to setup in firewalled environments due to it's port usage.

Connecting through a corporate proxy

If you configure a target server external to your organization you may need go through a corporate proxy if your organization uses one. In that case you can configure the settings for the corporate proxy by passing a command line argument as per below example:

 $ java -Dhttp.proxy=http://<username>:<password>@my.corporate.proxy:8080 -jar ekkoproxy-1.6.jar

Start proxies on startup

On start up of the application you can specify one or more proxies that you want to setup and start straightway.

The only prerequisite for this is that a settings file e.g. EkkoProxySettings_3099.json for each proxy exists already in the same working directory as the Ekko Proxy application itself. The settings file for a proxy is created automatically once a proxy has been created via the Ekko Proxy UI or Command line interface.

 $ java -jar ekkoproxy-1.6.jar --proxy=3099 --proxy=1080

Configuring SSL

If you need to have the Ekko Proxy running on a secure connection then you can configure the following SSL properties when starting it.

Setting	Description
server.ssl.key-store-type	The format used for the keystore. Would normally be PKCS12 but it could also be set to JKS in case it is a JKS file.
server.ssl.key-store	The full or relative path to the keystore containing the certificate.
server.ssl.key-store-password	Password used to access the certificate / key store.
server.ssl.key-alias	The alias that identifies the key in the key store.

Command line interface

Besides the web interface (see Accessing), Ekko Proxy can also be controlled on the command line using curl or similar to send commands.

Starting a proxy

Starting a proxy that's already has a settings file e.g. EkkoProxySettings_1080.json can be done like this:

 $ curl -i http://localhost:4040/cli/proxies/1080/start

If you want to create and start a proxy (i.e. it does not already have a saved settings file) then you can do:

 $ curl -i -X POST http://localhost:4040/cli/proxies \
-H "Content-Type: application/json" \
-d @- << 'EOF'
{
  "listenerPort" : 1080,
  "targetPort" : 80,
  "targetHost" : "ekkoproxy.eu-gb.mybluemix.net",
  "mode" : "playback",
  "outputDir" : "./recordings",
  "outputFormat" : "XML",
  "outputSubFolderExpressions" : [ "local-name(//Envelope/Body/*[1])", "(//UserID/text()|//Author/text())[last()]" ],
  "excludeExpressions" : [ "//Header/TraceId", "//Header/SessionId", "//ServiceRequest/userAgent" ],
  "expressionFormat" : "XPATH",
  "includeHeadersInHash" : false,
  "useRequestUriInOutputPath" : true,
  "targetHttps" : false,
  "sslCertificatePath" : "",
  "sslCertificatePassword" : "",
  "delays" : null,
  "description" : ""
}
EOF

Stopping a proxy

Stopping a running proxy is done as per below:

 $ curl -i http://localhost:4040/cli/proxies/1080/stop

Removing a proxy

The following command can be used to remove a proxy (it doesn't matter if it's stopped or started):

 $ curl -i http://localhost:4040/cli/proxies/1080/remove

Accessing

Once the application has started the Ekko Proxy management page can be accessed in a browser on either localhost:<server.port>, if running locally or <hostname>:<server.port>, if running on a server. E.g.

http://localhost:4040

Putting the above url in a browser like Chrome (recommended browser) or Firefox will load the Ekko Proxy application as per below screenshot:

License information and usage documentation can be viewed on this page. Further EkkoProxy application logs can viewed in the log file viewer by clicking the log search button

Usage scenarios

Ekko Proxy can be used in many different scenarios during the software development and testing cycles of an application. A couple of 'before and after' scenarios are shown below.

Classic client server scenario where the client application is directed at Ekko Proxy and Ekko Proxy is pointed to the target server / host:

Another scenario could be where you have a single page web application connecting to a middle tear using REST (JSON) and the middle tear connecting through to backend systems using SOAP (XML) or REST. In this scenario you could configure Ekko Proxy on two ports to intercept and possibly playback messages between the different layers:

Even if you have a mix of REST, SOAP etc. backend services you can simply setup multiple proxies on different ports to handle them.

Forwarding

Once an Ekko Proxy is running on a port then you can configure your application to go through the proxy by repointing the application service endpoints to <hostname>:<port> of where Ekko Proxy instance resides e.g. localhost:3080.

There can be situations where the port, that an Ekko Proxy is created on, cannot be exposed outside of that machine be it due to firewalls or cloud restrictions etc. In those cases requests can be 'forwarded' to the Ekko proxy/proxies using a special /forward/<port> path as in the example endpoints below:

http://localhost:4040/forward/3080/MyService
or
http://ekkoproxy.mybluemix.net/forward/3080/MyService

Note using this feature will consume threads from the main Tomcat thread pool rather than the individual Ekko Proxy thread pools.