# Config library

## Introduction

The config library is used by Vespa applications to subscribe to
configuration from the Vespa config system.

The low-level <a href="protocol-design.html">config protocol</a> is
used for communication between the application and a config source.

The config library has Java and C++ implementations.
Implementation-specific issues are noted at the end of this document.


## Config API

The config API that are used by clients will be mostly unchanged from
previous versions of Vespa.

## Config subscriptions

A client application generates config code based on config definition
files as described in the user documentation.
An application will implement a Subscriber
interface with a *configure()* callback and call the generated code's
*subscribe()* method to get a particular config.  *subscribe()* will
not return until *configure()* has been called and the application is
configured, or some fatal error occured which will lead to an
exception being thrown.

The *subscribe()* call will add the client to the list of subscribers
for this config and create a new Subscription object if there does not
exist one already for this config.

The Subscription object is the central object for communication
between the client and the config source.  When such an object is
created it will lead to a *getConfig()* (see <a
href="protocol-design.html">config protocol</a> documentation) call.
The Subscription object will make sure that *getConfig()* is called
and waiting for a response throughout the application's lifetime.
That way, new config will be discovered when this method call returns,
which it will do immediately if the subscribed config changes at the
config source.  At the same time, since the server timeout defined in
the protocol can be set to a high number, generating unnecessary
network traffic by polling frequently is avoided.

When the *getConfig()* call returns, a new *getConfig()* call is
scheduled for execution at a later time.  If the response was
successful, this will happen immediately.  If there was an error the
delay until the call will be performed depends on the number of times
since last succesful execution, and if the application has been
configured already or not (we want to try more aggrressively if the
aplication has not been configured).  There is a maximum delay defined
for this scheduling.


## Config sources 

A config source can either be a config server or a config proxy.  The
default behavior for applications is to use one local config source, a
config proxy on localhost, port 19090.  It is possible to use one or
more other sources too, by setting the environment variable
VESPA\_CONFIG\_SOURCES (a comma-separated list of hostnames, with
optional port number, like _foo,bar_ or _foo:1234,bar:2345_).

### Selecting config source

The config library selects a config source when requesting config
(performing the *getConfig()* method call) in a way that makes all
config requests from one paricular Internet host address use the same
config source (unless it is suspended, i.e. down, inaccessible etc.).

A config source can experience both transient and fatal errors. The
config library (and config proxy) will when configured with several
sources suspend a source for a period of time, where the suspension
time is based on the type of error and the number of times the error
has happened.  A suspended config source will not be considered when
doing a new selection of config source, except if it is the only
source configured.

As an example, a transient failure that happens 5 times will lead to
the config source being suspended for 10 seconds the first time it
happens, 20 seconds the next time and so on.  A more permanent error
will lead to similar behavior, except the supension times will be
higher.  There is a maximum delay for both types of errors.


## C++ library

## Java library