From e76235b675f7816e79128446236eac81f5a6ec0a Mon Sep 17 00:00:00 2001 From: Ben Nemec Date: Mon, 10 Dec 2018 23:43:28 +0000 Subject: [PATCH] More explicitly document driver connection strings If you're not intimately familiar with RFC 1808 it can be a bit tricky to write tooz connection strings. In addition, some drivers do not document the options that they recognize in a connection string. This can force a user to read the driver code in order to figure out how to configure tooz to use said driver, which should not be the case. This change more explicitly documents the format of the connection string, including which parts of an RFC 1808 URI it recognizes, and the options that can be passed. It also clarifies which parts of the connection string are optional (possibly because they have defaults) and which must always be included. Note that not every possible configuration is documented. For example, the postgres driver supports multiple methods of configuring the connection host and port. For consistency, I only documented the one that matches the other drivers. This should be sufficient to allow a user to write a working connection string. This change also wires the etcd3 and etcd3gw drivers into the doc index since they were missing before. Change-Id: I66e54433115f27fb54badc2173f8f6044c49aacb --- doc/requirements.txt | 2 ++ doc/source/reference/index.rst | 12 ++++++++++++ doc/source/user/drivers.rst | 33 +++++++++++++++++++++++++++++++++ tooz/drivers/consul.py | 20 ++++++++++++++++---- tooz/drivers/etcd.py | 15 +++++++++++++++ tooz/drivers/etcd3.py | 16 ++++++++++++++++ tooz/drivers/etcd3gw.py | 16 ++++++++++++++++ tooz/drivers/file.py | 7 +++++++ tooz/drivers/ipc.py | 4 ++++ tooz/drivers/memcached.py | 17 +++++++++++++++++ tooz/drivers/mysql.py | 6 ++++++ tooz/drivers/pgsql.py | 4 ++++ tooz/drivers/redis.py | 8 ++++++++ tooz/drivers/zookeeper.py | 4 ++++ 14 files changed, 160 insertions(+), 4 deletions(-) diff --git a/doc/requirements.txt b/doc/requirements.txt index c286519f..c870932b 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -10,3 +10,5 @@ redis>=2.10.0 # MIT psycopg2>=2.5 # LGPL/ZPL PyMySQL>=0.6.2 # MIT License pymemcache!=1.3.0,>=1.2.9 # Apache 2.0 License +etcd3>=0.6.2 # Apache-2.0 +etcd3gw>=0.1.0 # Apache-2.0 diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst index 15b7d570..830a5961 100644 --- a/doc/source/reference/index.rst +++ b/doc/source/reference/index.rst @@ -20,6 +20,18 @@ Etcd .. autoclass:: tooz.drivers.etcd.EtcdDriver :members: +Etcd3 +~~~~~ + +.. autoclass:: tooz.drivers.etcd3.Etcd3Driver + :members: + +Etcd3gw +~~~~~~~ + +.. autoclass:: tooz.drivers.etcd3gw.Etcd3Driver + :members: + File ~~~~ diff --git a/doc/source/user/drivers.rst b/doc/source/user/drivers.rst index 3d3fdd3c..c03d9de9 100644 --- a/doc/source/user/drivers.rst +++ b/doc/source/user/drivers.rst @@ -198,6 +198,38 @@ The etcd driver is a driver providing only distributed locks (for now) and is based on the `etcd server`_ supported key/value storage and associated primitives. +Etcd3 +----- + +**Driver:** :py:class:`tooz.drivers.etcd3.Etcd3Driver` + +**Characteristics:** :py:attr:`tooz.drivers.etcd3.Etcd3Driver.CHARACTERISTICS` + +**Entrypoint name:** ``etcd3`` + +**Summary:** + +The etcd3 driver is a driver providing only distributed locks (for now) +and is based on the `etcd server`_ supported key/value storage and +associated primitives. + +Etcd3 Gateway +------------- + +**Driver:** :py:class:`tooz.drivers.etcd3gw.Etcd3Driver` + +**Characteristics:** +:py:attr:`tooz.drivers.etcd3gw.Etcd3Driver.CHARACTERISTICS` + +**Entrypoint name:** ``etcd3+http`` + +**Summary:** + +The etcd3gw driver is a driver providing only distributed locks (for now) +and is based on the `etcd server`_ supported key/value storage and +associated primitives. It relies on the `GRPC Gateway`_ to provide HTTP access +to etcd3. + Consul ------ @@ -231,3 +263,4 @@ Characteristics .. _PostgreSQL database server: http://postgresql.org .. _MySQL database server: http://mysql.org .. _redis-sentinel: http://redis.io/topics/sentinel +.. _GRPC Gateway: https://github.com/grpc-ecosystem/grpc-gateway diff --git a/tooz/drivers/consul.py b/tooz/drivers/consul.py index f9fd559c..f5cfd9bd 100644 --- a/tooz/drivers/consul.py +++ b/tooz/drivers/consul.py @@ -91,10 +91,22 @@ class ConsulDriver(coordination.CoordinationDriver): needed to make Consul being used as an option for Distributed Locking. The data is stored in Consul's key-value store. - To configure the client to your liking please refer - http://python-consul.readthedocs.org/en/latest/. Few options like 'ttl' - and 'namespace' will be passed as part of the options. 'ttl' governs the - duration till when the session holding the lock will be active. + The Consul driver connection URI should look like:: + + consul://HOST[:PORT][?OPTION1=VALUE1[&OPTION2=VALUE2[&...]]] + + If not specified, PORT defaults to 8500. + Available options are: + + ================== ======= + Name Default + ================== ======= + ttl 15 + namespace tooz + ================== ======= + + For details on the available options, refer to + http://python-consul.readthedocs.org/en/latest/. .. _python-consul: http://python-consul.readthedocs.org/ .. _consul: https://consul.io/ diff --git a/tooz/drivers/etcd.py b/tooz/drivers/etcd.py index 87c77feb..45bacca0 100644 --- a/tooz/drivers/etcd.py +++ b/tooz/drivers/etcd.py @@ -203,6 +203,21 @@ class EtcdDriver(coordination.CoordinationDriver): This driver uses etcd provide the coordination driver semantics and required API(s). + + The Etcd driver connection URI should look like:: + + etcd://[HOST[:PORT]][?OPTION1=VALUE1[&OPTION2=VALUE2[&...]]] + + If not specified, HOST defaults to localhost and PORT defaults to 2379. + Available options are: + + ================== ======= + Name Default + ================== ======= + protocol http + timeout 30 + lock_timeout 30 + ================== ======= """ #: Default socket/lock/member/leader timeout used when none is provided. diff --git a/tooz/drivers/etcd3.py b/tooz/drivers/etcd3.py index 619f60ab..be3015ad 100644 --- a/tooz/drivers/etcd3.py +++ b/tooz/drivers/etcd3.py @@ -115,6 +115,22 @@ class Etcd3Driver(coordination.CoordinationDriverCachedRunWatchers, This driver uses etcd provide the coordination driver semantics and required API(s). + + The Etcd driver connection URI should look like:: + + etcd3://[HOST[:PORT]][?OPTION1=VALUE1[&OPTION2=VALUE2[&...]]] + + If not specified, HOST defaults to localhost and PORT defaults to 2379. + Available options are: + + ================== ======= + Name Default + ================== ======= + protocol http + timeout 30 + lock_timeout 30 + membership_timeout 30 + ================== ======= """ #: Default socket/lock/member/leader timeout used when none is provided. diff --git a/tooz/drivers/etcd3gw.py b/tooz/drivers/etcd3gw.py index c229e6be..eedaf6f6 100644 --- a/tooz/drivers/etcd3gw.py +++ b/tooz/drivers/etcd3gw.py @@ -166,6 +166,22 @@ class Etcd3Driver(coordination.CoordinationDriverWithExecutor): This driver uses etcd provide the coordination driver semantics and required API(s). + + The Etcd driver connection URI should look like:: + + etcd3+http://[HOST[:PORT]][?OPTION1=VALUE1[&OPTION2=VALUE2[&...]]] + + If not specified, HOST defaults to localhost and PORT defaults to 2379. + Available options are: + + ================== ======= + Name Default + ================== ======= + protocol http + timeout 30 + lock_timeout 30 + membership_timeout 30 + ================== ======= """ #: Default socket/lock/member/leader timeout used when none is provided. diff --git a/tooz/drivers/file.py b/tooz/drivers/file.py index aaef57b3..2ffa0a37 100644 --- a/tooz/drivers/file.py +++ b/tooz/drivers/file.py @@ -186,6 +186,13 @@ class FileDriver(coordination.CoordinationDriverCachedRunWatchers, missing some functionality but in the future these not implemented API(s) will be filled in. + The File driver connection URI should look like:: + + file://DIRECTORY[?timeout=TIMEOUT] + + DIRECTORY is the location that should be used to store lock files. + TIMEOUT defaults to 10. + General recommendations/usage considerations: - It does **not** automatically delete members from diff --git a/tooz/drivers/ipc.py b/tooz/drivers/ipc.py index f5d67a36..50885dc5 100644 --- a/tooz/drivers/ipc.py +++ b/tooz/drivers/ipc.py @@ -141,6 +141,10 @@ class IPCDriver(coordination.CoordinationDriverWithExecutor): semantics and required API(s). It **is** missing some functionality but in the future these not implemented API(s) will be filled in. + The IPC driver connection URI should look like:: + + ipc:// + General recommendations/usage considerations: - It is **not** distributed (or recommended to be used in those diff --git a/tooz/drivers/memcached.py b/tooz/drivers/memcached.py index 3892e221..ad409d1e 100644 --- a/tooz/drivers/memcached.py +++ b/tooz/drivers/memcached.py @@ -190,6 +190,23 @@ class MemcachedDriver(coordination.CoordinationDriverCachedRunWatchers, all of the coordination driver API(s). It stores data into memcache using expiries and `msgpack`_ encoded values. + The Memcached driver connection URI should look like:: + + memcached://[HOST[:PORT]][?OPTION1=VALUE1[&OPTION2=VALUE2[&...]]] + + If not specified, HOST defaults to localhost and PORT defaults to 11211. + Available options are: + + ================== ======= + Name Default + ================== ======= + timeout 30 + membership_timeout 30 + lock_timeout 30 + leader_timeout 30 + max_pool_size None + ================== ======= + General recommendations/usage considerations: - Memcache (without different backend technology) is a **cache** enough diff --git a/tooz/drivers/mysql.py b/tooz/drivers/mysql.py index cbeea8d7..269ec574 100644 --- a/tooz/drivers/mysql.py +++ b/tooz/drivers/mysql.py @@ -114,6 +114,12 @@ class MySQLDriver(coordination.CoordinationDriver): missing some functionality but in the future these not implemented API(s) will be filled in. + The MySQL driver connection URI should look like:: + + mysql://USERNAME:PASSWORD@HOST[:PORT]/DBNAME[?unix_socket=SOCKET_PATH] + + If not specified, PORT defaults to 3306. + .. _MySQL: http://dev.mysql.com/ """ diff --git a/tooz/drivers/pgsql.py b/tooz/drivers/pgsql.py index 1ad83dfd..6c60a208 100644 --- a/tooz/drivers/pgsql.py +++ b/tooz/drivers/pgsql.py @@ -174,6 +174,10 @@ class PostgresDriver(coordination.CoordinationDriver): missing some functionality but in the future these not implemented API(s) will be filled in. + The PostgreSQL driver connection URI should look like:: + + postgresql://[USERNAME[:PASSWORD]@]HOST:PORT?dbname=DBNAME + .. _PostgreSQL: http://www.postgresql.org/ """ diff --git a/tooz/drivers/redis.py b/tooz/drivers/redis.py index d3cf4f6d..5a5e771b 100644 --- a/tooz/drivers/redis.py +++ b/tooz/drivers/redis.py @@ -138,6 +138,14 @@ class RedisDriver(coordination.CoordinationDriverCachedRunWatchers, some notion of HA (values *can* be lost when a failover transition occurs). + The Redis driver connection URI should look like:: + + redis://[:PASSWORD@]HOST:PORT[?OPTION=VALUE[&OPTION2=VALUE2[&...]]] + + For a list of options recognized by this driver, see the documentation + for the member CLIENT_ARGS, and to determine the expected types of those + options see CLIENT_BOOL_ARGS, CLIENT_INT_ARGS, and CLIENT_LIST_ARGS. + To use a `sentinel`_ the connection URI must point to the sentinel server. At connection time the sentinel will be asked for the current IP and port of the master and then connect there. The connection URI for sentinel diff --git a/tooz/drivers/zookeeper.py b/tooz/drivers/zookeeper.py index e033c054..db57f19e 100644 --- a/tooz/drivers/zookeeper.py +++ b/tooz/drivers/zookeeper.py @@ -88,6 +88,10 @@ class KazooDriver(coordination.CoordinationDriverCachedRunWatchers): will be extracted from the coordinator url (or any provided options), so that a specific coordinator can be created that will work for you. + The Zookeeper coordinator url should look like:: + + zookeeper://[USERNAME:PASSWORD@][HOST[:PORT]][?OPTION1=VALUE1[&OPTION2=VALUE2[&...]]] + Currently the following options will be proxied to the contained client: ================ =============================== ====================