===========
ZEO Clients
===========

To use a ZEO server, you need to connect to it using a ZEO client
storage.  You create client storages either using a Python API or
using a ZODB storage configuration in a ZODB storage configuration
section.

Python API for creating a ZEO client storage
============================================

To create a client storage from Python, use the ``ZEO.client``
function::

    import ZEO
    client = ZEO.client(8200)

In the example above, we created a client that connected to a storage
listening on port 8200 on local host.  The first argument is an
address, or list of addresses to connect to.  There are many additional
options, documented below that should be given as keyword arguments.

Addresses can be:

- A host/port tuple

- An integer, which implies that the host is '127.0.0.1'

- A unix domain socket file name.

Options:

cache_size
   The cache size in bytes. This defaults to a 20MB.

cache
   The ZEO cache to be used.  This can be a file name, which will
   cause a persistent standard persistent ZEO cache to be used and
   stored in the given name.  This can also be an object that
   implements ``ZEO.interfaces.ICache``.

   If not specified, then a non-persistent cache will be used.

blob_dir
   The name of a directory to hold/cache blob data downloaded from the
   server.  This must be provided if blobs are to be used.  (Of
   course, the server storage must be configured to use blobs as
   well.)

shared_blob_dir
   A client can use a network files system (or a local directory if
   the server runs on the same machine) to share a blob directory with
   the server.  This allows downloading of blobs (except via a
   distributed file system) to be avoided.

blob_cache_size
   The size of the blob cache in bytes.  IF unset, then blobs will
   accumulate. If set, then blobs are removed when the total size
   exceeds this amount.  Blobs accessed least recently are removed
   first.

blob_cache_size_check
   The total size of data to be downloaded to trigger blob cache size
   reduction. The default is 10 (percent).  This controls how often to
   remove blobs from the cache.

ssl
   An ``ssl.SSLContext`` object used to make SSL connections.

ssl_server_hostname
   Host name to use for SSL host name checks.

   If using SSL and if host name checking is enabled in the given SSL
   context then use this as the value to check.  If an address is a
   host/port pair, then this defaults to the host in the address.

read_only
   Set to true for a read-only connection.

   If false (the default), then request a read/write connection.

   This option is ignored if ``read_only_fallback`` is set to a true value.

read_only_fallback
   Set to true, then prefer a read/write connection, but be willing to
   use a read-only connection.  This defaults to a false value.

   If ``read_only_fallback`` is set, then ``read_only`` is ignored.

server_sync
   Flag, false by default, indicating whether the ``sync`` method
   should make a server request.  The ``sync`` method is called at the
   start of explicitly begin transactions.  Making a server requests assures
   that any invalidations outstanding at the beginning of a
   transaction are processed.

   Setting this to True is important when application activity is
   spread over multiple ZEO clients. The classic example of this is
   when a web browser makes a request to an application server (ZEO
   client) that makes a change and then makes a request to another
   application server that depends on the change.

   Setting this to True makes transactions a little slower because of
   the added server round trip.  For transactions that don't otherwise
   need to access the storage server, the impact can be significant.

wait_timeout
   How long to wait for an initial connection, defaulting to 30
   seconds.  If an initial connection can't be made within this time
   limit, then creation of the client storage will fail with a
   ``ZEO.Exceptions.ClientDisconnected`` exception.

   After the initial connection, if the client is disconnected:

   - In-flight server requests will fail with a
     ``ZEO.Exceptions.ClientDisconnected`` exception.

   - New requests will block for up to ``wait_timeout`` waiting for a
     connection to be established before failing with a
     ``ZEO.Exceptions.ClientDisconnected`` exception.

client_label
   A short string to display in *server* logs for an event relating to
   this client. This can be helpful when debugging.

disconnect_poll
   The delay in seconds between attempts to connect to the
   server, in seconds.  Defaults to 1 second.

Configuration strings/files
===========================

ZODB databases and storages can be configured using configuration
files, or strings (extracted from configuration files).  They use the
same syntax as the server configuration files described above, but
with different sections and options.

An application that used ZODB might configure it's database using a
string like::

  <zodb>
     cache-size 1000MB

     <filestorage>
       path /var/lib/Data.fs
     </filestorage>
  </zodb>

In this example, we configured a ZODB database with a object cache
size of 1GB.  Inside the database, we configured a file storage.  The
``filestorage`` section provided file-storage parameters.  We saw a
similar section in the storage-server configuration example in `Server
configuration`_.

To configure a client storage, you use a ``clientstorage`` section,
but first you have to import it's definition, because ZEO isn't built
into ZODB.  Here's an example::

  <zodb>
     cache-size 1000MB

     %import ZEO

     <clientstorage>
       server 8200
     </clientstorage>
  </zodb>

In this example, we defined a client storage that connected to a
server on port 8200.

The following settings are supported:

cache-size
   The cache size in bytes, KB or MB. This defaults to a 20MB.
   Optional ``KB`` or ``MB`` suffixes can (and usually are) used to
   specify units other than bytes.

cache-path
   The file path of a persistent cache file

blob-dir
   The name of a directory to hold/cache blob data downloaded from the
   server.  This must be provided if blobs are to be used.  (Of
   course, the server storage must be configured to use blobs as
   well.)

shared-blob-dir
   A client can use a network files system (or a local directory if
   the server runs on the same machine) to share a blob directory with
   the server.  This allows downloading of blobs (except via a
   distributed file system) to be avoided.

blob-cache-size
   The size of the blob cache in bytes.  IF unset, then blobs will
   accumulate. If set, then blobs are removed when the total size
   exceeds this amount.  Blobs accessed least recently are removed
   first.

blob-cache-size-check
   The total size of data to be downloaded to trigger blob cache size
   reduction. The default is 10 (percent).  This controls how often to
   remove blobs from the cache.

read-only
   Set to true for a read-only connection.

   If false (the default), then request a read/write connection.

   This option is ignored if ``read_only_fallback`` is set to a true value.

read-only-fallback
   Set to true, then prefer a read/write connection, but be willing to
   use a read-only connection.  This defaults to a false value.

   If ``read_only_fallback`` is set, then ``read_only`` is ignored.

server-sync
   Sets the ``server_sync`` option described above.

wait-timeout
   How long to wait for an initial connection, defaulting to 30
   seconds.  If an initial connection can't be made within this time
   limit, then creation of the client storage will fail with a
   ``ZEO.Exceptions.ClientDisconnected`` exception.

   After the initial connection, if the client is disconnected:

   - In-flight server requests will fail with a
     ``ZEO.Exceptions.ClientDisconnected`` exception.

   - New requests will block for up to ``wait_timeout`` waiting for a
     connection to be established before failing with a
     ``ZEO.Exceptions.ClientDisconnected`` exception.

client-label
   A short string to display in *server* logs for an event relating to
   this client. This can be helpful when debugging.


Client SSL configuration
------------------------

An ``ssl`` subsection can be used to enable and configure SSL, as in::

  %import ZEO

  <clientstorage>
    server zeo.example.com8200
    <ssl>
    </ssl>
  </clientstorage>

In the example above, SSL is enabled in it's simplest form:

- The client expects the server to have a signed certificate, which the
  client validates.

- The server server host name ``zeo.example.com`` is checked against
  the server's certificate.

A number of settings can be provided to configure SSL:

certificate
  The path to an SSL certificate file for the client.  This is
  needed to allow the server to authenticate the client.

key
  The path to the SSL key file for the client certificate (if not
  included in the certificate file).

password-function
  A dotted name if an importable function that, when imported, returns
  the password needed to unlock the key (if the key requires a password.)

authenticate
  The path to a file or directory containing server certificates
  to authenticate.  (See the ``cafile`` and ``capath``
  parameters in the Python documentation for
  ``ssl.SSLContext.load_verify_locations``.)

  If this setting is used then certificate authentication is
  used to authenticate the server.  The server must be configured
  with one of the certificates supplied using this setting.

check-hostname
  This is a boolean setting that defaults to true. Verify the
  host name in the server certificate is as expected.

server-hostname
  The expected server host name.  This defaults to the host name
  used in the server address.  This option must be used when
  ``check-hostname`` is true and when a server address has no host
  name (localhost, or unix domain socket) or when there is more
  than one server and server hostnames differ.

  Using this setting implies a true value for the ``check-hostname`` setting.