This page shows how to configure JEAF Workload Proxy.

Configuration Files

Configuration of JEAF Workload Proxy basically consists of the following YAML configuration files:

Proxy Configuration
The so called proxy configuration contains all the configuration parameters for the proxy itself as well as the configuration of the proxy targets
Pipeline Configuration
The pipeline configuration defines the several pipelines that are used for request dispatching.

Proxy Configuration Parameters

Settings for Workload Container

The JEAF Workload Proxy Server consists of 2 containers. One to process “normal” workload request the other one is the management container. The following parameters are specific to the workload container.

Parameter	Default	Description
`port`	`8090`	Port that is used to server requests by the so called workload container. The workload container is used to server all kinds of non-management requests.
`minThreads`	`10`	Minimum amount of threads that are used by the workload container.
`maxThreads`	`50`	Maximum amount of threads that are used by the workload container.
`enableREST`	`true`	Enables the REST interface so that REST service can be used.
`enableWebServlets`	`true`	Enables the servlet interface so that Web servlets can be used.
`contextPath`	`/*`	Context path of the workload container.
`restPath`	`/rest/*`	Root path under which REST resources will be available.

Settings for Management Container

The JEAF Workload Proxy Server consists of 2 containers. One to process “normal” workload request the other one is the management container. The following parameters are specific to the management container.

Parameter	Default	Description
`enableManagementInterface`	`true`	Enables management interface.
`managementPort`	`8091`	Port under which the management interface is accessible.
`minManagementThreads`	`1`	Minimum amount of threads that are used for requests to the management interface. Depending on the used Java Runtime Environment it may happen that you need to increase minimum amount of management threads. In this case an exception will occur during startup.
`maxManagementThreads`	`8`	Maximum amount of threads that are used for requests to the management interface.
`managementPath`	`/*`	Context path under which the management interface will be available.

Common Settings for Proxy Server

Some of the parameters below are very similar to those of pipelines. so please be aware that here we are talking about the configuration of the proxy server itself and not of its pipelines. In general the resource requirements of the proxy server itself are rather low.

Parameter	Default	Description
`threadIdleTimeout`	`300000`	Idle time after which a thread will be stopped and removed from pool. Timeout is defined in milliseconds.
`initialQueueSize`	`100`	Initial size of queue that is used to store requests until they are dispatched to the matching pipelines.
`maxQueueSize`	`0`	Maximum size of queue that is used to store requested until they are really processed. 0 means that the initial size is also the maximum -1 means that queue is unlimited. It strong recommended to not use this as it might crash the whole server in case of high loads or DoS attacks.
`queueGrowSize`	`100`	Size of which the request queue should be increased until the maximum is reached.
`inputBufferSize`	`8192`	Size of input buffer in bytes that is used when request data is read.
`outputBufferSize`	`32768`	Size of output buffer in bytes that is used when response data is written.
`httpIOIdleTimeout`	`30000`	HTTP I/O timeout of the HTTP connector. This timeout comes into play if a client does not consume further response data for a certain amount of time.
`sendServerVersion`	`false`	Enables sending the server version as a response header field. It's recommended to not enable this info for security reasons. By default information about server version is not send in response header for security reasons.
`sendXPoweredBy`	`false`	Enables sending the server version as a response header field. It's recommended to not enable this info for security reasons. By default information about server version is not send in response header for security reasons.
`gracefulShutdown`	`true`	Enables graceful shutdown behavior. Graceful shutdown means that request that are already processed will be finished but new ones will not be accepted.
`gracefulShutdownTimeout`	`30000`	Timeout for graceful shutdown. If this timeout is exceeded then running threads will be killed.
`stopServerOnError`	`true`	Defines if server should be stopped when a `java.lang.Error` occurs.
`traceUncaughtErrors`	`true`	Defines if uncaught `java.lang.Error` should be traced.
`stopServerOnRuntimeException`	`false`	Defines if server should be stopped when a `java.lang.RuntimeException` occurs.
`traceUncaughtRuntimeExceptions`	`false`	Defines if uncaught `java.lang.RuntimeException` should be traced.
`enableJMX`	`false`	Defines if JMX should be enabled or not. By default JMX is disabled to prevent security issues. By default JMX is disabled for security reasons.

Byte Buffer Pool Configuration

JEAF Workload Proxy has a set pools where byte buffers are cached. These byte buffers are used to store incoming requests during processing. Each byte buffer pool will have a set of byte buffers with a specific size. You can define the minimum and maximum size of the byte buffers. For minBufferSize, maxBufferSize and all multiples of 2 in between an own pool will be created.

Working with byte buffer pools has the advantage that less garbage will be produced. The buffer sizes and the size of each pool has to be configured according to the behavior of your services.

Parameter	Default	Description
`poolSize`	`20`	Size of each pool with byte buffers.
`minBufferSize`	`128`	Size of the smallest byte buffers.
`maxBufferSize`	`16k`	Size of the largest byte buffers (default 16k bytes). Larger byte buffers will not be pooled.

Pipeline Configuration

The actual pipeline configurations are stored in another YAML configuration file.

Parameter	Default	Description
`pipelineConfigurationFile`	mandatory	Location of configuration file that contains the pipeline definitions. Path can either be absolute or relative to this file.

Proxy Target Configuration

The following configuration parameters are used to configure all the proxy targets. Of course its possible to define multiple proxy targets here.

Parameter	Default	Description
`name`	mandatory	Name for the proxy target
`targetServer`	mandatory	URL of the target server
`requestTypeCategory`	mandatory	Type of request that are processed by the target. The value controls the possible mechanisms that are available to dispatch the request to the matching pipelines. Possible values are: `SOAP` and `REST`
`requestURI`	mandatory	Request URI that is used to detect that an incoming request on the workload proxy should be sent to this proxy target
JEAF Workload Proxy uses Apaches HTTP Client to communicate with the proxy target. For each proxy target there is a separate connection pool, which can be configured using the parameters below
`maxIdleConnections`	`20`	Maximum amount of idle connections in the connection pool
`keepAliveDuration`	`60000`	Keep alive duration for connection to proxy target (in milliseconds)
`validateAfterInactivityDuration`	`10000`	Parameter configures the time period in milliseconds after which a connection is validated before it is taken from the pool again.
`maxRetries`	`1`	Maximum amount of retries before a call to the proxy target is considered to be failed.
`retryInterval`	`100`	Interval in milliseconds after which the proxy target is called again in case that retries are configured.
`responseTimeout`	`10000`	Response timeout in milliseconds for calls to proxy target. Please be aware that this is a very sensitive parameter and needs to be fine-tuned for your purposes. the response timeout has a very strong influence on the behavior of your service to the outside world and also influences pipeline configuration values.
`connectTimeout`	`10000`	Timeout in milliseconds to establish connections to the proxy target. As connections are pooled this parameter should not have a too strong influence on the overall behavior. However please ensure that it fits to your environment.
JEAF Workload proxy also makes use of a so called circuit breaker for each proxy target. The parameters below can be used to configure it.
`failureRateThreshold`	`30`	Failure rate threshold (percent of requests) defines which amount of failed request must be exceeded due to technical problems that the circuit breaker opens and no further request will be sent to the proxy target. Value must between `0` and `100`.
`durationInOpenState`	`1000`	Duration in milliseconds that the circuit breaker stays open until request will be sent to the proxy target again. The value must be zero or greater.
`slowRequestDuration`	`10000`	Configures the duration in milliseconds above which calls are considered as slow and increase the slow calls percentage. The value must be zero or greater.
`slowRequestRateThreshold`	`30`	Configures the slow request threshold in percentage. The circuit breaker considers a call as slow when the call duration is greater than `slowCallDuration`. When the percentage of slow calls is equal to or greater than the threshold, the circuit breaker transitions to open and starts short-circuiting calls. Value must between `0` and `100`.
`permittedCallsInHalfOpenState`	`5`	Configures the number of permitted calls when the circuit breaker is half open. The value must be zero or greater.
`slidingWindowSizeSeconds`	`5`	Configures the size of the sliding window in seconds which is used to record the outcome of calls when the circuit breaker is closed. The value must be greater than `0`.
Key Resolution Rules When requests are received by JEAF Workload Proxy for a specific target then they are dispatched to a pipeline that is responsible to take care about its processing (or rejection). Currently key resolution rules are only supported for SOAP requests. In case of REST, dispatching is only possible based on the URI. In case of SOAP at least 1 key resolution rule is expected per proxy target.
`requestKey`	mandatory	Key for unique identification of a request type. This key will be used when dispatching requests to pipelines as pipelines are responsible for 1 or more request keys.
`xpathExpression`	optional	XPath expression that is used to evaluate if a request matches to this request key. If there is no XPath expression defined for a key resolution rule then this rule is the default rule.

Proxy Configuration Example

SimpleProxyConfiguration.yaml

Pipeline Configuration Parameters

Pipeline configuration file contains one or more pipeline definition. The following table describes all the configuration parameters that are supported for pipelines.

Parameter	Default	Description
`id`	mandatory	Unique ID of the pipeline.
`name`	optional	Name of the pipeline. If no name is provided then the ID will also be used as name.
`description`	optional	Description of the pipeline.
`coreThreads`	mandatory	The core thread size defines the standard size of the thread pool. The size of the thread will only be extended to the maximum size in case the the queue reaches its maximum size. For further details please refer to ThreadPoolExecutor.
`maxThreads`	`-1`	Maximum amount of threads that will be used by the pipeline. In standard working mode the pipeline will not use more threads then defined by `coreThreads`. Only when the queue reaches its limit max threads will be used. By default `maxThreads` will have the same size as `coreThreads`.
`threadPriority`	`5`	Valid values as defined by Java must be within `1` and `10`.
`maxThreadKeepAlive`	`60000`	Maximum time in milliseconds until threads that exceed the minimum pool size are kept alive if they are not used. Default is 60 seconds.
`queueType`	`FIFO`	Implementation type of the queue that is used to implement the workload pipeline. Currently `NOT_QUEUED` and `FIFO` are supported.
`maxQueueDepth`	`50`	Maximum size of the queue that is used for requests in case that all threads of the pipeline are currently occupied.
`maxLatency`	`-1`	Maximum latency in the defined `timeUnit` that is accepted due to queuing of requests. If the defined maximum time is exceeded then the request will be rejected. This value is similar to a connection wait timeout for JDBC connections.
`timeUnit`	`MILLISECONDS`	Time unit that is used for all time values. Default is `MILLISECONDS`.
`defaultPipeline`	`false`	Parameter define if this pipeline definition is the default pipeline. The default pipeline will be used if no other more specific pipeline could be found for a certain request type.
Keys for Pipelines A pipeline can be connected with multiple keys. JEAF Workload Proxy know two types of keys: Generic Keys and REST Keys. Generic keys result from key resolution rules that are define in a proxy target. Using the keys a request is dispatched to a pipeline with the matching key. REST Keys are directly created based on the received request using URI and HTTP method of the request.
`genericKeys`	optional	List contains one or more generic key. Entries are described in `{genericKeys}.key`.
`key`	mandatory	Name of the generic key. The key also should be defined for at least one of the proxy targets.
`restKeys`	optional	List contains one or more
`endpointURL`	mandatory	Endpoint URL of the REST Key.
`httpMethod`	optional	Optional HTTP method of the REST Key. Valid values are `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `CONNECT`, `OPTIONS` and `TRACE`

Pipeline Configuration Example

SimplePipelineConfiguration.yaml

Workload Proxy Configuration