diff options
author | Harald Musum <musum@yahoo-inc.com> | 2017-02-17 08:15:15 +0100 |
---|---|---|
committer | Harald Musum <musum@yahoo-inc.com> | 2017-02-17 08:15:15 +0100 |
commit | 69a94af3473bc5c9cc7b12de44968c6e7a170e1e (patch) | |
tree | 1295f88ee9521017da210cfd941e5aa3fe07abee /config | |
parent | 8434a5b10b6f14781433b282bb689ce7631df1f7 (diff) |
Config design doc moved to another repo
Diffstat (limited to 'config')
-rw-r--r-- | config/doc/java/batchConfigurer.png | bin | 58090 -> 0 bytes | |||
-rw-r--r-- | config/doc/java/classes.vsd | bin | 689152 -> 0 bytes | |||
-rw-r--r-- | config/doc/java/client.png | bin | 51749 -> 0 bytes | |||
-rw-r--r-- | config/doc/java/client_nodes.png | bin | 53964 -> 0 bytes | |||
-rw-r--r-- | config/doc/java/configHelper.png | bin | 70174 -> 0 bytes | |||
-rw-r--r-- | config/doc/java/proxy.png | bin | 59715 -> 0 bytes | |||
-rw-r--r-- | config/doc/java/proxy_error_configured.png | bin | 83742 -> 0 bytes | |||
-rw-r--r-- | config/doc/java/proxy_error_subscribe.png | bin | 77785 -> 0 bytes | |||
-rw-r--r-- | config/doc/java/proxy_interaction.png | bin | 72322 -> 0 bytes | |||
-rw-r--r-- | config/doc/java/proxy_reload.png | bin | 36370 -> 0 bytes | |||
-rw-r--r-- | config/doc/library-design.txt | 90 | ||||
-rw-r--r-- | config/doc/protocol-design.txt | 85 |
12 files changed, 0 insertions, 175 deletions
diff --git a/config/doc/java/batchConfigurer.png b/config/doc/java/batchConfigurer.png Binary files differdeleted file mode 100644 index 18adf8663ba..00000000000 --- a/config/doc/java/batchConfigurer.png +++ /dev/null diff --git a/config/doc/java/classes.vsd b/config/doc/java/classes.vsd Binary files differdeleted file mode 100644 index 9f5fa882790..00000000000 --- a/config/doc/java/classes.vsd +++ /dev/null diff --git a/config/doc/java/client.png b/config/doc/java/client.png Binary files differdeleted file mode 100644 index afd84114fa8..00000000000 --- a/config/doc/java/client.png +++ /dev/null diff --git a/config/doc/java/client_nodes.png b/config/doc/java/client_nodes.png Binary files differdeleted file mode 100644 index 20f29fac093..00000000000 --- a/config/doc/java/client_nodes.png +++ /dev/null diff --git a/config/doc/java/configHelper.png b/config/doc/java/configHelper.png Binary files differdeleted file mode 100644 index ef553eee485..00000000000 --- a/config/doc/java/configHelper.png +++ /dev/null diff --git a/config/doc/java/proxy.png b/config/doc/java/proxy.png Binary files differdeleted file mode 100644 index 91c767f0e4a..00000000000 --- a/config/doc/java/proxy.png +++ /dev/null diff --git a/config/doc/java/proxy_error_configured.png b/config/doc/java/proxy_error_configured.png Binary files differdeleted file mode 100644 index 279a7dac3bb..00000000000 --- a/config/doc/java/proxy_error_configured.png +++ /dev/null diff --git a/config/doc/java/proxy_error_subscribe.png b/config/doc/java/proxy_error_subscribe.png Binary files differdeleted file mode 100644 index 37b9f1d66a2..00000000000 --- a/config/doc/java/proxy_error_subscribe.png +++ /dev/null diff --git a/config/doc/java/proxy_interaction.png b/config/doc/java/proxy_interaction.png Binary files differdeleted file mode 100644 index e79dafcd48c..00000000000 --- a/config/doc/java/proxy_interaction.png +++ /dev/null diff --git a/config/doc/java/proxy_reload.png b/config/doc/java/proxy_reload.png Binary files differdeleted file mode 100644 index 0103643f9ab..00000000000 --- a/config/doc/java/proxy_reload.png +++ /dev/null diff --git a/config/doc/library-design.txt b/config/doc/library-design.txt deleted file mode 100644 index cbea6e283b2..00000000000 --- a/config/doc/library-design.txt +++ /dev/null @@ -1,90 +0,0 @@ -# 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 diff --git a/config/doc/protocol-design.txt b/config/doc/protocol-design.txt deleted file mode 100644 index ba7fd7d7538..00000000000 --- a/config/doc/protocol-design.txt +++ /dev/null @@ -1,85 +0,0 @@ -# Config protocol - -## Introduction - -This document describes the low-level config protocol based on fnet/rpc. - -## Overview of the protocol - -The protocol is stateless and similiar to HTTP GET and other REST -APIs, but implemented as remote procedure calls (RPC). A client -performs a method call get(), and a server returns a response if the -config has changed since the last time get() was called, or waits a -specified time before returning (unless the config changes before the -timeout is reached, in case it returns immediately). Since the -protocol is stateless, it is easy to use more than one config server -to serve config. It is also possible to use a (cacheing) proxy -between client and server. - -The figure below shows a simplified view of how an application *App* -uses the config library API to subscribe to a config. The protocol is -shown as *get()* call and *ret()* responses. Optionally, a proxy can -be used between client and the server. - -<img src='rpc-config-protocol.png' alt='RPC config protocol' /> - -In the figure above, the first parameter *X* is a designator for the -config to get, the second parameter is a generation number and the -third parameter *T* is a server timeout. - -The server (or proxy, if the client is using one) will generate a -response immediately if the config *X* has another (higher) generation -number than the one requested. If not, the server will create a timer -with timeout *T* and respond when the timer expires or the requested -config changes, whatever comes first. - -If the response was generated because the config changed, the config -payload will be included in the response and a change flag set to mark -that the response contains changed config. Else the change flag will -not be set (and no config payload included in the response). - -The client timeout (how long the client waits for an answer before -giving up), should be longer than the server timeout *T*. - - -## Implementation - -The implementation of get() is an RPC method called getConfig() with -the following signature: - - getConfig(String configId, String defName, String defVersion, String defMD5, String configMD5, long timeout) - -and the parameters: - -* *configId* - config id -* *defName* - config definition name -* *defVersion* - config definition version -* *defMD5* - config definition md5sum -* *configMD5* - config md5sum (the md5sum of the config payload) -* *timeout* - server timeout - -The fifth parameter, the config md5sum, is used instead of a -generation number. If a config is found, the md5sum of the config -payload will be returned in the response, so that subsequent calls to -getConfig() will use this new md5sum as *configMD5*. When getting -config the first time, this parameter will be an empty string. - - -The return parameters are: - - String configId, String defName, String defVersion, String defMD5, String configMD5, int changed, long generation, String payload) - -with the first 5 parameters being the same as the one in the -request. The rest are: - -* *changed* - a flag the will have a value of 1 if there is a config - *payload* in the response, or 0 else. -* *generation* - generation when the config was last changed (in milliseconds since 1970). -* *payload* - config payload. Will only have a value if *changed* is 1. - -The payload is the same as in the previous version of this protocol. - -The *generation* parameter can be used to check how old the config -is. In case of getting a new payload (*changed* is 1, this can be used -to check that the config returned has a newer timstamp thatn the last -returned from a config source (this |