First draft of some clustering documentation

With pretty namespacing and class documentation

doc/clustering.rst

@@ -1,2 +1,161 @@
+.. vim: set ts=3 sw=3 et :
+
+.. php:namespace:: Predis
+
 Clustering
 ----------
+
+A "cluster" is a group of Redis servers that collectively provide a shared
+namespace. In a cluster, data is not shared between Redis instances; instead,
+each server is used to serve a portion of the keys.
+
+In broad terms, this is done by identifying the key part of each Predis command
+to be run on the clustered connection. This key is then used to distribute
+commands among the underlying connections.
+
+Clustering has obvious advantages. As you add Redis instances to your
+cluster, your available space increases. At the same time, commands should be
+distributed between the nodes, meaning each individual node has to service
+less requests.
+
+
+Distribution Strategy
+=====================
+
+Exactly how keys are split across a cluster is specified by a
+:term:`distribution strategy`. There are two distribution strategy classes shipped
+with Predis. What they have in common is that they try to manage the task of
+adding and removing servers from the cluster cleverly.
+
+When a server is added or removed, the distribution strategy takes care of
+ensuring that as few keys as possible have to be moved between the remaining
+servers. When you remove a server from a clustered connection of ten servers,
+ideally you'd only like 10% of your keys to be newly missing.
+
+This is broadly known as "`consistent hashing`_".
+
+.. _consistent hashing: https://en.wikipedia.org/wiki/Consistent_hashing
+
+Configuring a Cluster
+=====================
+
+Recall that the `Client` constructor takes two types of argument: a
+set of connection parameters, and a set of options::
+
+   $client = new Predis\Client($connection, $options);
+
+You only need to do one thing differently to set up a clustered client:
+identify multiple connections. You can also, optionally, configure your cluster
+with the ``cluster`` client option.
+
+Configuring Multiple Connections
+''''''''''''''''''''''''''''''''
+
+Passing information about multiple connections is as simple as wrapping them
+all in an array::
+
+   $client = new Predis\Client(array(
+       array(
+           'host'     => '127.0.0.1',
+           'port'     => 6379,
+           'database' => 2,
+           'alias'    => 'first'
+       ),
+       array(
+           'host'     => '127.0.0.1',
+           'port'     => 6379,
+           'database' => 3,
+           'alias'    => 'second',
+       )
+   ), $options);
+
+You can still use the URI syntax to configure the connections::
+
+   $client = new Predis\Client(array(
+       'tcp://127.0.0.1:6370?alias=first&db=0',
+       'tcp://127.0.0.1:6370?alias=second&db=1'
+   ), $options);
+
+.. note::
+
+   When you want to pass information about multiple connections, Predis expects
+   you'll do so with a numeric array, indexed from 0. If you've removed
+   connections from your array (perhaps after catching a
+   `Predis\\CommunicationException`), you can use array_values() to reindex it.
+
+   If your connection array does not have a value at [0], Predis
+   will assume you're trying to configure a single connection with an
+   associative array.
+
+The ``cluster`` Client Option
+'''''''''''''''''''''''''''''
+.. php:namespace:: Predis\Connection
+
+You can optionally confiugre your client's clustering by using the ``cluster``
+client option. This option can take a few different types of value. It can take
+the special strings ``"predis"`` or ``"redis"`` to switch between the two
+built-in cluster connection classes `PredisCluster` and
+`RedisCluster` respectively::
+
+   $client = new Predis\Client(array(
+       // ...
+   ), array('cluster' => 'predis'));
+
+If the value is any other string, it's expected to be the fully qualified name
+of a class implementing `ClusterConnectionInterface`.
+
+Finally, you can also configure the option with a callable. This callable is
+expected to return an instance of `ClusterConnectionInterface`. The two
+built-in clustered connection types both accept a
+`Predis\\Cluster\\Distribution\\DistributionStrategyInterface` instance as
+their first argument, allowing you to configure that as well::
+
+   $client = new Predis\Client(array(
+       // ...
+   ), array(
+      'cluster' => function () {
+         $strategy = new Predis\Cluster\Distribution\KetamaPureRing();
+         return new Predis\Connection\PredisCluster($strategy);
+      }
+   ));
+
+Connection Classes
+""""""""""""""""""
+
+.. php:class:: PredisCluster
+
+  ``PredisCluster`` is a simple Predis-native clustered connection implementation.
+
+  This form of clustered connection does *not* provide redundancy. If your application
+  makes requests for 100 different keys, with the default distribution strategy
+  these keys are likely to be spit across all the servers in your pool.
+
+.. php:class:: RedisCluster
+
+  ``RedisCluster`` is a clustered connection implementation intended for use with
+  Redis Cluster. Redis Cluster is not yet finalized, but it already includes some
+  pretty cool features. Nodes in a Redis Cluster arrangement configure
+  themselves to deal with changes in availability.
+
+Disallowed Commands
+===================
+
+Some commands just don't make sense to run on a clustered connection. For
+example, the ``INFO`` command returns information about the server on which
+it's run, so running it on a cluster would be meaningless.
+
+If you try to run one of these commands, you'll get a
+``Predis\\NotSupportedException``.
+
+Running Commands on Nodes
+=========================
+
+`PredisCluster` and :php:class:`RedisCluster` both
+implement `\\IteratorAggregate`, so you can easily run commands against the
+individual Redis servers in a cluster::
+
+   $hosts = array();
+   foreach ($client->getConnection() as $shard) {
+       $hosts[] = $shard->info();
+   }
+

doc/glossary.rst

@@ -0,0 +1,11 @@
+.. vim: set ts=3 sw=3 et :
+
+Glossary
+--------
+
+.. glossary::
+   :sorted:
+
+   distribution strategy
+      In a clustered connection, the distribution strategy determines which
+      subconnection a command is sent.