<commit_before>.. _timelock-server-configuration:

Timelock Server Configuration
=============================

The Timelock Server configuration file is written in YAML and is located at ``var/conf/timelock.yml``.
It has three main configuration blocks: ``clients``, ``cluster``, and ``algorithm``. We will discuss how each of
these may be configured in turn, as well as additional configuration parameters.

.. contents::
   :local:

Clients
-------

The ``clients`` block is a list of strings which corresponds to client namespaces that the server will respond to.
At least one client must be configured for the Timelock Server to work. Querying an endpoint for a client that does not
exist will result in a 404.

   .. code:: yaml

      clients:
        - tom
        - jerry

A single Timelock Server or cluster of Timelock Servers can support multiple AtlasDB clients. When querying a
Timelock Server, clients must supply a namespace for which they are requesting timestamps or locks in the form of a
path variable. There are no guarantees of relationships between timestamps requested from different namespaces.

   .. code:: bash

      curl -XPOST localhost:8080/tom/timestamp/fresh-timestamp
      curl -XPOST localhost:8080/jerry/timestamp/fresh-timestamp # no guarantees of any relationship between the values

This is done for performance reasons: consider that if we maintained a global timestamp across all clients, then
requests from each of these clients would need to all be synchronized.

Cluster
-------

The ``cluster`` block is used to identify the servers which make up a Timelock Service cluster. An example is as
follows:

   .. code:: yaml

      cluster:
        localServer: http://palantir.com:8700
        servers:
          - http://palantir.com:8700
          - http://palantir.com:8701

.. list-table::
   :widths: 5 40
   :header-rows: 1

   * - Property
     - Description

   * - localServer
     - A string following the form ``protocol://hostname:port`` which matches the host on which this config exists.

   * - servers
     - A list of strings following the form ``protocol://hostname:port`` identifying the hosts in this Timelock
       Service cluster. Note that this list must include the ``localServer``.

Algorithm
---------

We have currently implemented the consensus algorithm required by the Timelock Server using the Paxos algorithm.
Currently, this is the only supported implementation, though there may be more in the future.
We first identify an algorithm by its ``type`` field.

Paxos Configuration
~~~~~~~~~~~~~~~~~~~
<commit_msg>Expunge protocol from cluster example<commit_after>.. _timelock-server-configuration:

Timelock Server Configuration
=============================

The Timelock Server configuration file is written in YAML and is located at ``var/conf/timelock.yml``.
It has three main configuration blocks: ``clients``, ``cluster``, and ``algorithm``. We will discuss how each of
these may be configured in turn, as well as additional configuration parameters.

.. contents::
   :local:

Clients
-------

The ``clients`` block is a list of strings which corresponds to client namespaces that the server will respond to.
At least one client must be configured for the Timelock Server to work. Querying an endpoint for a client that does not
exist will result in a 404.

   .. code:: yaml

      clients:
        - tom
        - jerry

A single Timelock Server or cluster of Timelock Servers can support multiple AtlasDB clients. When querying a
Timelock Server, clients must supply a namespace for which they are requesting timestamps or locks in the form of a
path variable. There are no guarantees of relationships between timestamps requested from different namespaces.

   .. code:: bash

      curl -XPOST localhost:8080/tom/timestamp/fresh-timestamp
      curl -XPOST localhost:8080/jerry/timestamp/fresh-timestamp # no guarantees of any relationship between the values

This is done for performance reasons: consider that if we maintained a global timestamp across all clients, then
requests from each of these clients would need to all be synchronized.

Cluster
-------

The ``cluster`` block is used to identify the servers which make up a Timelock Service cluster. An example is as
follows:

   .. code:: yaml

      cluster:
        localServer: palantir.com:8700
        servers:
          - palantir.com:8700
          - palantir.com:8701

.. list-table::
   :widths: 5 40
   :header-rows: 1

   * - Property
     - Description

   * - localServer
     - A string following the form ``hostname:port`` which matches the host on which this config exists.

   * - servers
     - A list of strings following the form ``hostname:port`` identifying the hosts in this Timelock
       Service cluster. Note that this list must include the ``localServer``.

Algorithm
---------

We have currently implemented the consensus algorithm required by the Timelock Server using the Paxos algorithm.
Currently, this is the only supported implementation, though there may be more in the future.
We first identify an algorithm by its ``type`` field.

Paxos Configuration
~~~~~~~~~~~~~~~~~~~

{'fraction_non_alphanumeric': 0.0863239573229874, 'fraction_numerical': 0.010475266731328807, 'mean_word_length': 3.433361994840929, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '538002', 'n_tokens_mistral': 1342, 'n_tokens_neox': 1257, 'n_words': 646}