Usage

Ekko Proxy has an easy and intuitive client made by engineers for engineers.

Create a Ekko Proxy instance

To create a proxy click the Create Proxy navigation link. You should now see the Create Ekko Proxy page below where you can enter the proxy details to setup a new Ekko Proxy instance.

ekkoproxy settings screen

The fields on the Proxy Settings page are described below:

Field Description
Listening Port * The port number [1 - 65535] that the Ekko Proxy should be listening on for incoming messages. Clients connect to this port on the host where Ekko Proxy server is hosted be it on a localhost PC / laptop or on a remote server.

Note when the field looses focus, then previously saved settings will be automatically loaded, if any exist. Alternatively pressing enter will also load any saved settings and move focus to the 'CREATE PROXY' button where pressing enter again will create the Ekko Proxy instance. Lastly its also possible to drag & drop an existing proxy settings file (e.g. EkkoProxySettings_1080.json) on to this screen to fill in the fields.
Target Host * The host / ip of the target server where the requests will forwarded to in passthrough or record mode.
Target Port * The port number [1 - 65535] of the target server where the requests will forwarded to in passthrough or record mode.
Output Directory * The directory to where the Ekko Proxy instance should store recordings. Can be a full path or relative.

Note this field may be read-only if a fixed output directory has been specified on the command line when starting the Ekko Proxy server.
Description An optional description of the proxy that will be displayed on the proxy view.
If not set it will default to 'The Ekko Proxy Stub Server is started|stopped'
HTTPS If checked, the HTTPS protocol will be used to connect to the target server.
Certificate File An SSL certificate can be specified if required for the HTTPS connection.
Certificate Password An SSL certificate password can be specified if required for the SSL certificate.
Output Format The format to use when writing the saving and displaying requests and responses.
Operation Mode The operation mode of the Ekko Proxy instance.
See Operation modes section for details.
Use RegEx Expressions If checked, the expressions in the 'Organising Recordings' and 'Normalise Recordings' tables should be regular expressions otherwise they should be XPath expressions.
Organising Recordings If you want to organise the recorded requests and responses into various sub-folders based on information in the requests, then you can specify XPath or Regular expressions here to select the information from the requests and use to create sub-folders under the output directory.

Note the order of the expressions determine the order of the sub-folders.

See Organising recordings for more details.

: Adds a new row to the table.
: Launches the Expressions test dialog.
: Use request URI in output path. If selected, the request url will be part of the output folder path where the requests and responses are saved to. For example if the 'Output Directory' is set to C:\temp and a request is having a path of /foo/bar then the requests and responses for this web service will be saved in C:\temp\foo\bar.
Normalise Recordings The filename key for a request and response pair is made up of hashed request information. There may be parts of the request that are unique per request e.g. a transaction id, session id or timestamp etc. which would prevent playback mode from working as the filename key would never be the same. To solve this you can specify XPath or Regular expressions here that will remove any matching fields in the request e.g. //ServiceRequest/SessionId before constructing the recorded filename key.

Note when using XPath expressions you can only exclude request information from the request body. If you need to exclude information from the URI, query string or headers (if 'Include HTTP headers in filename key' option is selected) then please use Regular expressions instead.

See Normalise recordings for more details.

: Adds a new row to the table.
: Launches the Expressions test dialog.
: Include HTTP headers in filename key. If selected, the HTTP request headers are included in the key for the saved requests and responses.

Note if there are request headers that vary per request for a service then you should either not use this option or use regular expressions in the 'Normalise Recordings' table to exclude them as otherwise playback would not work.
CREATE PROXY Clicking the button (or pressing enter when focused) will create the new Ekko Proxy instance, provided there are no validation errors.

An example of a filled Settings screen can be found below:

ekkoproxy settings screen filled

Note you can also drag & drop an existing proxy settings file (e.g. EkkoProxySettings_1080.json) on to this screen to fill it in.

Operation modes

Ekko Proxy has four different operation modes:

  • Passthrough - in this mode all requests and responses going through the proxy will be passed directly to the target server.
  • Record - this mode will save all requests and responses going through the proxy to the target server.
  • Playback - in the playback mode Ekko Proxy will respond with a recorded response, if one exists, otherwise it will pass the request to the target server and respond with the servers response.
  • Playback or Record - in the playback or record mode Ekko Proxy will respond with a recorded response, if one exists, otherwise it will pass the request to the target server and record the response so that when the same request is seen again it will be played back from thereon.
  • Playback on Error - this mode will only playback a saved response (provided one exists) if a HTTP error status of 500 or above is received from the target server. If a recording does not exist the original error response is sent.
The different operation modes are explained further in the below flow diagram:

Ekko Proxy operation modes

Organising recordings

The 'Organising Recordings' table along with the 'Use request URI in output path' field allows you to organise how the recordings are stored on disk under the 'Output Directory' path.

For example if you have set 'Output Directory' to C:\temp, selected the 'Use request URI in output path' option and you have the following SOAP request on the /SystemUtilitiesService URI:

<?xml version="1.0" encoding="UTF-8"?>
   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" ...>
   <soapenv:Body>
      <GetSystemFunctionsRequest xmlns="urn:LCASoft.SystemUtilities.V1">
         <Header>
            <ns1:Origin xmlns:ns1="urn:LCASoft.Schema.Header">app</ns1:Origin>
            <ns2:UserId xmlns:ns2="urn:LCASoft.Schema.Header">789012</ns2:UserId>
         </Header>
         <SystemFunctions>
            <ApplicationId>2</ApplicationId>
            <ApplicationType>3</ApplicationType>
            <SystemParameters>
               <SystemParameter>
                  <ParameterIdentifier>IsAvailable</ParameterIdentifier>
               </SystemParameter>
            </SystemParameters>
         </SystemFunctions>
      </GetSystemFunctionsRequest>
   </soapenv:Body>
</soapenv:Envelope>

And you wanted to store these and other requests of the SystemUtilitiesService under the method requested and the user id, as highlighted above, you could add the following XPaths to the 'Organising Recordings' table:

  1. local-name(//Envelope/Body/*[1])
  2. //UserId/text()

The order of the expressions determine the sub-folder order, which given all of the above would end up being:

C:
|_ temp
   |_ SystemUtilitiesService
      |_ GetSystemFunctionsRequest
         |_ 789012
               - 2c94b878a468ce4b3a9a2a3ea37df739_req.txt
               - 2c94b878a468ce4b3a9a2a3ea37df739_resp.txt

The *_req.txt and *_resp.txt files contain the recorded request and response respectively.

Likewise if you are working with JSON etc. you can use regular expressions instead pick out values e.g. \"UserId\":\s?\"(.*\)" would fetch the value of the UserId field. Please note the brackets used to select the value part only.

Note you can change the response content of a saved response file at any time to have the amended response played back on the next request for the resource.

The recorded requests can also be dragged & dropped on a Ekko Proxy (messages table part) to resend them provided the proxy is running in passthrough mode.

Normalise recordings

The 'Normalise Recordings' table allows for normalising recordings by removing any unwanted uniqueness thus enabling them to be played back.

For example given a SOAP request message like:

<?xml version="1.0" encoding="UTF-8"?>
   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" ...>
   <soapenv:Body>
      <GetSystemFunctionsRequest xmlns="urn:LCASoft.SystemUtilities.V1">
         <Header>
            <ns1:Origin xmlns:ns1="urn:LCASoft.Schema.Header">app</ns1:Origin>
            <ns2:UserId xmlns:ns2="urn:LCASoft.Schema.Header">789012</ns2:UserId>
            <ns3:TransactionId xmlns:ns2="urn:LCASoft.Schema.Header">3M4bSjb3jP4b2j3hL</ns3:TransactionId>
         </Header>
         <SystemFunctions>
            <ApplicationId>2</ApplicationId>
            .
            .
         </SystemFunctions>
      </GetSystemFunctionsRequest>
   </soapenv:Body>
</soapenv:Envelope>

In the example above the TransactionId is a unique identifier that differs per request, which if not excluded, would create a new recording every time and you would not be able to have it played back. So to overcome this scenario you can add expressions in the 'Normalise Recordings' table to exclude this, and any other data items like it, from the unique key used to identify a recording.

In this particular example adding //Header/TransactionId to the 'Normalise Recordings' table would be all that's needed to exclude the node from the recording key.

Note for XPath expressions you don't have to worry about namespaces.

Similarly regular expressions can be used to exclude unique information in the request body as well as the request URI. The latter cannot be done using XPath expressions.

For example given a REST GET request below:

http://localhost:3094/microservice/v1/books?bookId=112233&timestamp=123456789

You can exclude the unique timestamp query string parameter by adding a simple regular expression &timestamp=\d* to the 'Normalise Recordings' table.

Likewise if you need to exclude one or more unique fields in for example a JSON request body like below:

{
    "glossary": {
        "title": "example glossary",
        "GlossDiv": {
            "title": "S",
            "GlossList": {
                "GlossEntry": {
                    "ID": "ISO 8879:1986",
                    "CreatedDate": "2018-10-05T14:48:10.000Z",
                    .
                    .
                }
            }
        }
    }
}
        

Using a regular expression like \"CreatedDate\"\s?:\s?\".*\", would exclude the CreatedDate from being part of the recording key so that if the same message is sent again but with a different CreatedDate value it will still be played back.

Note as long as the value(s) that you don't want to include in the filename key are removed then it doesn't matter if the remaining message is valid JSON or XML as it's only used for the filename key generation.

Managing a Ekko Proxy instance

Once a Ekko Proxy instance has been created using the Settings page, a link to it will appear in the navigation bar from where it can be managed. Clicking that link will show the Ekko Proxy management screen as can be seen in the example below:

ekkoproxy management screen top part

Messages going through the proxy will appear in the table as shown above.

Fields and functions

The fields and functions of this part of the Proxy management view are as follows:

Field Description
Search The search field can be used to search the table showing the messages going through the Ekko Proxy instance. Pressing the Enter key or clicking the search button will initiate the search and filter the table showing only matches. The table header will show if it's filtered or not by displaying the filtered icon:
Link status A green link means the Ekko Proxy client is connected to the Ekko Proxy Server.
A red link means the Ekko Proxy client has been disconnected from the Ekko Proxy Server.
Target Host The host / ip of the target server where the requests will forwarded to in passthrough or record mode.
This can be edited only when the proxy is stopped.
Target Port The port number [1 - 65535] of the target server where the requests will forwarded to in passthrough or record mode.
This can be edited only when the proxy is stopped.
Operation Mode The operation mode of the Ekko Proxy instance. See the Operation modes section for a description of what the different modes of operation are.
This can be edited only when the proxy is stopped.
Pause / Resume Pressing the 'Pause' button will stop new messages from being displayed in the table whilst paused.
Pressing 'Resume' will refresh the table and it will again update automatically when new messages appear.

Note 'Pause' and 'Resume' only affects the view of the current client i.e. other clients viewing messages for the proxy will continue to see updates.
Stop / Play Pressing the 'Stop' button will stop the running proxy and any requests sent to it will not be able to connect. Pressing 'Play' starts the proxy again. Whilst stopped the 'Target Host', 'Target Port' and 'Operation Mode' fields can be modified allowing a change of target destination or operation mode.
Delay The 'Delay' button opens the Delay Settings dialog allowing for response delays to be set.
Compare The 'Compare' button provides the option to compare two requests or responses in the Compare dialog.

Note this button is only enabled when exactly two messages are selected.
Open The 'Open' button opens a recorded request and/or response in a new browser tab / window. The request and/or response needs to have been recorded i.e. saved before it can be opened in a separate window.

Note depending on browser settings, especially if opening both the request and response in one go, then you may need to enable pop-ups for the Ekko Proxy client as otherwise the action may be blocked by the browser.
Save The 'Save' button allows for saving / recording the requests and responses of the selected messages that are not already saved / recorded or played back i.e. messages that were passthrough messages.
Resend Resends the selected requests.
Clear Clears the selected messages from the table and in-memory Ekko Proxy server cache.
Delete Deletes the selected saved / recorded messages from disk.

Note this cannot be undone!

Messages table

The messages table displays the incoming requests/responses going through the proxy. Saved request recording files can also be dragged & dropped on this table to send these requests again (Note to reach the target server, the Ekko Proxy should not be in Playback mode).

The following describes the messages table columns:

Field Description
Time The timestamp of the message (HH:mm:ss.SSS dd-MM-yyyy).
Method The HTTP method of the message e.g. POST.
Status The HTTP status of the message e.g. 200 OK.
Mode The operation mode used to serve the message e.g. Playback.
Request URI The request URI of the HTTP message.
Filename The filename of the recording if the message was recorded or played back.
Duration The length of time it took to respond (mm:ss.SSS).
If a delay is set for the request then this time will include the delay time and a timer icon is displayed to indicate that it was a delayed response.

Note multiple messages can be selected by clicking the check box or by holding down the Ctrl key while clicking on a message row.


Example drag & drop of two request recordings on the messages table to send them again:

ekkoproxy messages table dnd

Request and response details

The second half of the Proxy management view shows the request and response details of a selected message as shown below.
The request details are editable allowing for a new request to be created or for amending an existing one. When creating a new request the details can either be entered manually or a saved request recording can be dragged & dropped in the Request Content area.

ekkoproxy management screen bottom part

The fields and functions of this part of the Proxy management view are:

Field Description
Request Content The content of the request body and headers if shown.
The field is editable allowing for it to be set or changed. Supports Drag & Drop of a request file from an existing recording.
Request Method The request HTTP method of the currently selected request, if any.
The field is editable allowing for it to be set or changed.
Request URI The request URI of the currently selected request, if any.
The field is editable allowing for it to be set or changed.
Send The 'Send' button will send / resend the current request content.
Show / Hide Shows / hides the request or response headers.
Response Content The content of the response and headers if shown.

Example drag & drop of a request recording on the Request Content area to fill it with the request details:

ekkoproxy messages table dnd

Manual stubbing

Manually stubbing of a request can currently be achieved by firing the request in question through the proxy and then saving / recording the request. This generates the request recording file e.g. 34af1895bca9eef210ae5836e0ae65be_req.txt in the Output Directory as per organising recording rules. Then you simply create a equivalent response file e.g. 34af1895bca9eef210ae5836e0ae65be_resp.txt and put the desired response status and content in that file. The format of the response file should follow the HTTP Specification which very simply put is:

Status line
Response headers (if any)
CRLF
Response Body (if any)

Example:

HTTP/1.1 200 OK
Content-Type: text/xml
Server: gSOAP/2.9

<?xml version="1.0" encoding="UTF-8"?>
   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" ...>
   <soapenv:Body>
      <GetSystemFunctionsRequest xmlns="urn:LCASoft.SystemUtilities.V1">
            .
            .
      </GetSystemFunctionsRequest>
   </soapenv:Body>
</soapenv:Envelope>

WireMock stubbing

Manual stubs can also be created using the Ekko Proxy Mock Editor which manages WireMock stubs that can be used by the proxy instances.

For more details see Ekko Proxy Mock Editor

Dialogs

Expressions test dialog

The Expressions test dialog allows you to verify what your RegEx or XPath expressions match what you are expecting.

In the example below two Filename key exclude XPath expressions are to be tested against a SOAP message:

ekkoproxy expressions test dialog, normalise mode

The expressions to be tested in the example are:

  • /Envelope/Header/RequestHeader/networkCode
  • /Envelope/Header/RequestHeader/applicationName

Clicking 'Test It' will result in the below test result:

ekkoproxy expressions test dialog result, normalise mode

This shows the difference with fields removed highlighted in red meaning these fields will not be considered as part of the recorded filename key. In the example above the same result could have been achieved with shorter expressions e.g. //RequestHeader/networkCode or even in one expression e.g. /Envelope/Header or //Header/RequestHeader removing the whole SOAP header instead - that is provided you didn't want to include any of the headers.

It's usually better to be specific unless you know you want to remove all SOAP headers for example for all the messages going though the proxy.

Note not all expressions have to match all messages - if an expression doesn't match it's simply ignored.

Another example would be when testing 'Organising Recordings' reqular expressions as in the example below:

ekkoproxy expressions test dialog, organise mode

The expressions to be tested in this example are:

  1. Channel:\s?(.*)
  2. \"name\"\s?:\s?\"(.*)\"

Clicking 'Test It' will result in the below test result:

ekkoproxy expressions test dialog result, organise mode

The result shows the matches as part of the file path that they will be part of. If the 'Output Directory' is set to say C:\temp then the final recording path would be C:\temp\myChannel\my_username or C:\temp\user\myChannel\my_username if 'Use Request URI in Output Path' was selected and the URI for the service is /user.

Delay settings dialog

The delay settings dialog allows for response delays to be set for requests who's responses are being played back.
The dialog will show requests currently displayed in the messages table or that has been previously set for the proxy.

ekkoproxy delay dialog

To set a delay choose the Request URI and Method, either from the dropdowns or the table, that you want to set/change and use the slider to set a minimum and maximum delay for the particular response.
The max delay slider on the right changes the max delay possible (up to 2 minutes). This also sets the scale of the delay slider itself allowing for either finer or more coarse-grained timings to be set.

Compare dialog

The compare dialog can show the differences between two selected requests or responses. The example below shows the differences between two requests.

ekkoproxy compare dialog

The compare dialog provides either a Unified View or Split View of the differences.

By default 20 lines of context is given though this can easily be changed in the 'Lines of context' dropdown.

< Go Back