X-road mock proxy server
This is a mock or proxy or both servers for X-road services.
Why?
Usual X-road setup is following. You application communicates directly with X-road security server over http/https or TLS client certificate authentication.
![Usual setup Usual setup](https://github.com/aldas/xroad-mock-proxy/raw/d46a54df438a/docs/image/setup-usual.png)
This is all fine until you need to:
- a) test complex test cases in your system and need to custom responses from X-road (i.e. mock responses)
- b) use multiple X-road environments without modifying application code
Use case: I would like to use my default X-road server for all request except service X which I want to respond from my mock
![Mocking Xroad services Mocking Xroad services](https://github.com/aldas/xroad-mock-proxy/raw/d46a54df438a/docs/image/setup-as-router-mock.png)
Use case: I would like to use my Test X-road server for all request except service X,Y and Z which I want to respond from my DEV X-road server.
![Routing request to different X-road instances Routing request to different X-road instances](https://github.com/aldas/xroad-mock-proxy/raw/d46a54df438a/docs/image/setup-as-router.png)
Architecture
![components components](https://github.com/aldas/xroad-mock-proxy/raw/d46a54df438a/docs/image/achitecture.png)
This repo compiles into single application that has 2 different parts.
- proxy - acts as a router. Accepts requests from APP and routes request based on configured rules to different servers. Contains REST API for to see proxied requests/responses and
add/modify/remove proxying rules.
- mock - responds configured SOAP messages to requests. Contains REST API to dynamically add/modify/remove rules/tempalates for responses.
Features (goals)
The application should support/have:
- X-road security server with ClientCert authentication as a proxy target
- for serving proxy on HTTP or HTTPS or ClientCert authentication (as recommended for X-road)
- deciding server where to route request base on:
- requester IP
- request content (regex match)
- request X-road service name
- modifying proxied request body based on rules
- modifying proxied request response body based on rules
- REST API to add/modify/remove proxy rules
- REST API to add/modify/remove mock rules
- basic frontend for proxy:
- list of last N proxied requests/responses
- list of proxy rules
- add/modify/remove proxy rules
- basic frontend for mock:
- list of mock rules
- add/modify/remove mock rules
Non-goals
Configuration
See example .xroad-mock-proxy-example.yaml
Application is configured from configuration file (yaml) or env variables. By default configuration is read from .xroad-mock-proxy.yaml
from
current directory or read from file given with command line arg --config=
. For example: ./xroad-mock-proxy --config=/opt/app/myconf.yaml
Environment variables can be used to override yaml
values during application startup. All ENV variables need to have XMP_
prefix to work.
For example mock address in yaml is configured as
mock:
address: localhost:8082
to override it with ENV variable do
export XMP_MOCK_ADDRESS=localhost:6000
./xroad-mock-proxy
HOW TOs
- Systemd service setup
- Handling certificates
Development
Requirements
- Go 1.12 - programming language
make
or Docker - to build binaries
Build binary
Assuming you have go
and make
installed.
Check/lint/test and build binary
make check
make
Run binary
cp .xroad-mock-proxy-example.yaml .xroad-mock-proxy.yaml
# edit `.xroad-mock-proxy.yaml`
# start server
./xroad-mock-proxy
Build docker image
make docker
Run in Docker
make docker run-docker