tidy confirm docs

- make Basic.Ack more symmetric
- same meaning of Basic.Ack{delivery-tag=0, multiple=1} regardless of
  direction (NB: this means confirm counting should start at one, not
  zero, but that's a separate bug)
- the validity of the delivery-tag MUST be checked by the Basic.Ack
  recipient.
- define confirmation condition more succinctly
- remove "forget confirmed messages" rule since it is captured by the
  Basic.Ack rules.

Author: rade

docs/specs/amqp0-9-1.xml

@@ -2570,34 +2570,38 @@
 
     <method name = "ack" index = "80" label = "acknowledge one or more messages">
       <doc>
-        On the server side, this method acknowledges one or more
-        messages delivered via the Deliver or Get-Ok methods; the
-        client can ask to confirm a single message or a set of
-        messages up to and including a specific message.
+        When sent by the client, this method acknowledges one or more
+        messages delivered via the Deliver or Get-Ok methods.
+
+        When sent by server, this method acknowledges one or more
+        messages published with the Publish method on a channel in
+        confirm mode.
 
-        On the client side, this method acknowledges one or more
-        messages published to a channel in confirm mode; the client
-        may receive an acknowledgement for a single message or for a
-        set of message up to and including a specific message.
+        The acknowledgement can be for a single message or a set of
+        messages up to and including a specific message.
       </doc>
 
       <chassis name = "server" implement = "MUST" />
-      <chassis name="client" implement="MUST"/>
+      <chassis name ="client" implement = "MUST"/>
 
       <field name = "delivery-tag" domain = "delivery-tag" />
       <field name = "multiple" domain = "bit" label = "acknowledge multiple messages">
         <doc>
-          If set to 1, the delivery tag is treated as "up to and including", so that the
-          peer can acknowledge multiple messages with a single method. If set to zero,
-          the delivery tag refers to a single message. If the multiple field is 1, and the
-          delivery tag is zero, tells the server to acknowledge all outstanding messages.
+          If set to 1, the delivery tag is treated as "up to and
+          including", so that multiple messages can be acknowledged
+          with a single method. If set to zero, the delivery tag
+          refers to a single message. If the multiple field is 1, and
+          the delivery tag is zero, this indicates acknowledgement of
+          all outstanding messages.
         </doc>
         <rule name = "exists" on-failure = "precondition-failed">
           <doc>
-            The server MUST validate that a non-zero delivery-tag refers to a delivered
-            message, and raise a channel exception if this is not the case.  On a transacted
-            channel, this check MUST be done immediately and not delayed until a Tx.Commit.
-            Specifically, a client MUST not acknowledge the same message more than once.
+            A message MUST not be acknowledged more than once.  The
+            receiving peer MUST validate that a non-zero delivery-tag
+            refers to a delivered message, and raise a channel
+            exception if this is not the case. On a transacted
+            channel, this check MUST be done immediately and not
+            delayed until a Tx.Commit.
           </doc>
           <doc type = "scenario">
             TODO.
@@ -2858,24 +2862,24 @@
   <class name = "confirm" handler = "channel" index = "85" label = "work with confirms">
     <doc>
       The Confirm class allows publishers to put the channel in
-      confirm mode and be notified when messages have been handled by
-      the broker.  The intention is that all messages published on a
-      channel in confirm mode will be acknowledged at some point.  By
-      acknowledging a message the broker assumes responsibility for it
-      and indicates that it has done something it deems reasonable
-      with it.
+      confirm mode and susequently be notified when messages have been
+      handled by the broker.  The intention is that all messages
+      published on a channel in confirm mode will be acknowledged at
+      some point.  By acknowledging a message the broker assumes
+      responsibility for it and indicates that it has done something
+      it deems reasonable with it.
 
       Unroutable mandatory or immediate messages are acknowledged
-      right after the Basic.Return method.  Transient messages are
-      acknowledged as soon as they arrive on all the queues they were
-      routed to.  Persistent messages are acknowledged when all queues
+      right after the Basic.Return method. Messages are acknowledged
+      when all queues to which the message has been routed
       have either delivered the message and received an
-      acknowledgement (if required), or persisted the message.
+      acknowledgement (if required), or enqueued the message (and
+      persisted it if required).
 
-      Published messages are assigned ascending sequence numbers
-      (starting at 0, when the Confirm.Select method is used); these
-      sequence numbers are later used to identify messages in
-      Basic.Ack methods.
+      Published messages are assigned ascending sequence numbers,
+      starting at 0 when the Confirm.Select method is used. The server
+      confirms messages by sending Basic.Ack methods referring to these
+      sequence numbers.
     </doc>
 
     <rule name = "all messages acknowledged">
@@ -2885,7 +2889,7 @@
       </doc>
     </rule>
 
-    <rule name = "wait for all queues">
+    <rule name = "all queues">
       <doc>
         The server MUST acknowledge a message only after it was
         properly handled by all the queues it was delivered to.
@@ -2899,14 +2903,6 @@
       </doc>
     </rule>
 
-    <rule name = "forget confirmed messages">
-      <doc>
-        The server MUST NOT reference any messages it has already
-        confirmed.  Thus, clients can safely forget about confirmed
-        messages.
-      </doc>
-    </rule>
-
     <rule name = "time guarantees">
       <doc>
         No guarantees are made as to how soon a message is
@@ -2917,7 +2913,6 @@
 
     <doc type = "grammar">
       confirm            = C:SELECT S:SELECT-OK
-                         / S:ACK
     </doc>
 
     <chassis name = "server" implement = "SHOULD" />