Configure the SSE Proxy

SSE Proxy configuration parameters are defined in a YAML file. YAML is a simple markup format in which hierarchical relationships are represented by indentation. For example:

data:
  somevalue: "a string"
  othervalues:
    - value: 0
    - value: 1

Some elements in a YAML hierarchy may be contain arrays of values (like othervalues in the example above). The names of all such array elements are preceded by a hyphen.

The SSE Proxy configuration file supports interpolating environment variables using the following syntax: ${variable}. Default values can also be provided using the following syntax: ${variable:-default}.

In the description below, forward slashes (/) are used to represent hierarchical relationships when referring to parameters. For instance, the parameters in the example given above would be referred to as data/somevalue and data/othervalues/- value.

The SSE Proxy is designed to support multiple back-end services. The backends element therefore contains an array of - uri elements, each representing a different service.

To configure the SSE Proxy:

Log in as root.
If you installed SSE Proxy using the old-style method, create a symbolic link to the installation's configuration folder from /etc/escenic:
```
# cd /etc/escenic
# ln -s /opt/escenic/sse-proxy-[l-version]/configuration sse-proxy
```
Open /etc/escenic/sse-proxy/sse-proxy.yaml in an editor.
Set the following parameters:
server/applicationConnectors/type and server/applicationConnectors/port

These parameters determine the protocol and port number clients must use to access the SSE Proxy. If you are only intending to make use of one SSE Proxy then the default settings of http and 9080 can usually be used. If you will be running several proxies in the same domain, then each proxy must listen on a different port, so you will need different server/applicationConnectors/port values on each proxy.

server/adminConnectors/type and server/adminConnectors/port

These parameters determine the protocol and port number clients must use to access the SSE Proxy's admin UI. The admin UI is a simple set of pages containing diagnostics information about the operation of the SSE Proxy. If you are only intending to make use of one SSE Proxy then the default settings of http and 9081 can usually be used. If you will be installing several proxies, then each proxy must listen on a different port, so you will need different server/adminConnectors/port values on each proxy.

backends

A container for an array of uri elements, each defining a back-end service to be fronted by this SSE Proxy.

backends/- uri

The URI of the back-end service. To connect to a Content Store running on editorial.example.com, for example, you would need to specify http://editorial.example.com/webservice/escenic/changelog/sse.

backends/- uri/credentials/username and backends/- uri/credentials/password

The authentication credentials that the SSE Proxy should supply to access this back-end service (typically, a Content Store web service), if required. Authentication is not always required – it is required for access to the Content Store web service's change log event stream, but not for access to the Live Center event stream. If authentication is not required, then you can ignore these parameters. Read-only access is sufficient for accessing the Content Store change log event stream. It's probably a good idea to create a special CUE user with read-only access for use by the SSE Proxy.

backends/- uri/inactivityThreshold

In some cases it is possible for back-end connections to fail without the SSE Proxy being informed. This parameter makes it possible to recover from such situations. If the back-end service is silent for longer than the specified threshold, then the connection is assumed to be broken. The SSE Proxy then terminates the connection and starts a new one. The default value is 600 seconds (that is, 10 minutes).

backends/- uri/httpHeaders
A list of custom headers to be specified when initiating a connection to this back-end service. Each header must be specified as a child key:value setting, for example:
```
backends:
  - uri: http://example.com/webservice/sse
    ...
    httpHeaders:
      my-first-header: my-first-value
      my-second-header: my-second-value
```
cors/*
These parameters determine how cross-origin HTTP requests should be handled.

The default settings will "work" out-of-the box, but the cors/allowedOrigins setting is not secure. You should change it to only accept requests from your back-end services' domains. To support CUE running on https://editorial.example.com/cue-web/, for example, set allowedOrigins to "http://www.example.com". If you are using SSE Proxy to support multiple back-end services in different domains, then you can specify multiple origins by separating the domain URIs with commas. For example:
```
cors
  allowedOrigins: "http://www.example.com, http://www.otherexample.com"
```
The other parameters in this group should not need modifying in most cases.
logging/*

These parameters are set up to direct all log messages from various sources to the console. If you want to change this, you can find out how to do so by consulting the Dropwizard documentation.

ulimit
Defines a the maximum number of clients the proxy will handle. This limit will be enforced in Java space.

The recommended value of this property is 1000 lower than the ulimit defined on the OS level. This is to ensure that internal operations such as logging, classloading and opening connections to the configured backends still work even though the server is overloaded with incoming connections. The OS defined ulimit can be found by invoking
```
$ ulimit -n
```
The number of requests rejected due to this setting can be monitored by looking at the com.escenic.sse.proxy.connections-rejected meter in the admin page.

Setting this property is optional, but recommended.
reconnectInterval

The initial number of seconds to wait before reconnecting to a disconnected back end. If the reconnection attempt fails then SSE Proxy backs off by waiting twice as long before it makes another attempt. The interval keeps being doubled until either a connection is established or maxReconnectInterval (see below) is reached. The default value is 10 seconds.

maxReconnectInterval

A maximum size for reconnectInterval. The default value is 60 seconds. If a connection fails and cannot be re-established, then by default reconnectInterval will increase in size as follows: 10, 20, 40, 60, 60, ... etc.

heartbeatInterval
Heartbeat events are distributed to clients periodically to ensure that:
- Connections are kept open
- Dangling connections get closed
This parameter determines how frequently heartbeats are sent. The default value is 25 seconds. This means that a heartbeat will be sent to a client 25 seconds after the last event (of whatever kind) was sent. In other words, if there is a frequent stream of ordinary events, then no heartbeats will need to be sent.
clientReconnectInterval

Browsers attempt to reconnect to an SSE endpoint roughly 3 seconds after the connection is closed, but other clients may have different defaults. The SSE Proxy can, however, control this reconnect interval by including a retry field specifying the required interval in all the events it sends out. To do this, set clientReconnectInterval to a value greater than 0. The default value is 0, which means that clients can choose their own reconnect interval. If you set it to 2, for example, then all clients will be required to reconnect after 2 seconds.

cacheSize

The SSE Proxy is able to cache events received from its back ends. The cache contents are used when a client reconnects to an SSE endpoint after a break and needs to catch up with the events it has missed. In this situation, the SSE Proxy will be able to send the missing events without querying the back end if they are still in the cache, thus reducing load on the back-ends it supports.

The default value is 10000, which should be sufficient for most purposes. You might want to increase it for an SSE Proxy that supports a large number of back ends, or where client connections are poor.
Save your changes.