QPID-2920: Update new-cluster-plan.txt and new-cluster-design.txt.

Refined comments on live upgrade in design and plan.

git-svn-id: https://svn.apache.org/repos/asf/qpid/branches/qpid-2920-active@1182815 13f79535-47bb-0310-9956-ffa450edef68

2 files changed, 32 insertions, 22 deletions

diff --git a/qpid/cpp/design_docs/new-cluster-design.txt b/qpid/cpp/design_docs/new-cluster-design.txt
index a162ea68ec..aaf8cd6488 100644
--- a/qpid/cpp/design_docs/new-cluster-design.txt
+++ b/qpid/cpp/design_docs/new-cluster-design.txt
@@ -83,20 +83,21 @@ context.
 
 ** A new cluster design.
 
-Clearly defined interface between broker code and cluster plug-in.
+1. Clearly defined interface between broker code and cluster plug-in.
 
-Replicate queue events rather than client data.
-- Broker behavior only needs to match per-queue.
-- Smaller amount of code (queue implementation) that must behave predictably.
-- Events only need be serialized per-queue, allows concurrency between queues
+2. Replicate queue events rather than client data.
+ - Only requires consistent enqueue order.
+ - Events only need be serialized per-queue, allows concurrency between queues
+ - Allows for replicated and non-replicated queues.
 
-Use a moving queue ownership protocol to agree order of dequeues.
-No longer relies on identical state and lock-step behavior to cause
-identical dequeues on each broker.
+3. Use a lock protocol to agree order of dequeues: only the broker
+   holding the lock can acqiure & dequeue.  No longer relies on
+   identical state and lock-step behavior to cause identical dequeues
+   on each broker.
 
-Use multiple CPG groups to process different queues in parallel. Use a
-fixed set of groups and hash queue names to choose the group for each
-queue.
+4. Use multiple CPG groups to process different queues in
+   parallel. Use a fixed set of groups and hash queue names to choose
+   the group for each queue.
 
 *** Requirements
 
@@ -295,20 +296,23 @@ flow control is sufficient for qpid.
 ** Live upgrades
 
 Live upgrades refers to the ability to upgrade a cluster while it is
-running, with no downtime. Each brokers in the cluster is shut down,
-and then re-started with a new version of the broker code.
+running, with no downtime. Brokers are shut down and re-start brokers
+in the cluster is shut down, and then re-started with a new version of
+the broker code.
 
 To achieve this
 - Cluster protocl XML file has a new element <version number=N> attached
   to each method. This is the version at which the method was added.
-- New versions can only add methods, existing methods cannot be changed.
+- New versions can add methods, existing methods cannot be changed.
 - The cluster handshake for new members includes the protocol version
   at each member.
 - The cluster's version is the lowest version among its members.
-- A newer broker can join and older cluster. When it does, it must restrict 
-  itself to speaking the older version protocol.
+- A newer broker can join and older cluster but not vice versa.
+- A newer broker in an old cluster must speak the old protocol for the
+  benefit of older brokers. It can also use newer controls which
+  will be ignored by old broekrs.
 - When the cluster version increases (because the lowest version member has left)
-  the remaining members may move up to the new version.
+  the remaining members may switch to using only the new version.
 
 
 * Design debates
diff --git a/qpid/cpp/design_docs/new-cluster-plan.txt b/qpid/cpp/design_docs/new-cluster-plan.txt
index 32e3f710e7..b22f7a1f31 100644
--- a/qpid/cpp/design_docs/new-cluster-plan.txt
+++ b/qpid/cpp/design_docs/new-cluster-plan.txt
@@ -227,22 +227,28 @@ The old cluster has workarounds in the broker code that can be removed.
 - [ ] drop security workarounds: cluster code now operates after message decoding.
 - [ ] drop connection tracking in cluster code.
 - [ ] simper inconsistent-error handling code, no need to stall.
+
 ** TODO [#C] Support for live upgrades.
 
 Allow brokers in a running cluster to be replaced one-by-one with a new version.
+(see new-cluster-design for design notes.)
 
 The old cluster protocol was unstable because any changes in broker
 state caused changes to the cluster protocol.The new design should be
 much more stable.
 
-Points to implement: 
-- Brokers should ignore unknown controls (with a warning) rather than an error.
-- Limit logging frequency for unknown control warnings.
-- Add a version number at front of every CPG message. Determines how the
-  rest of the message is decoded. (allows for entirely new encodings e.g. AMQP 1.0)
+Points to implement in anticipation of live upgrade:
+- Prefix each CPG message with a version number and length.
+  Version number determines how to decode the message.
+- Brokers ignore messages that have a higher version number than they understand.
 - Protocol version XML element in cluster.xml, on each control.
 - Initial status protocol to include protocol version number.
 
+New member udpates: use the store encode/decode for updates, use the
+same backward compatibility strategy as the store. This allows for
+adding new elements to the end of structures but not changing or
+removing new elements.
+
 ** TODO [#C] Support for AMQP 1.0.
 
 * Testing