Review notes for the remainder of AMQP 1.0 spec working draft

["Steve Huston" <shuston@riverace.com>]

The remainder of my notes from reviewing the AMQP 1.0 spec working draft
are below.

As before, there are two sections: "Easy" are mostly copyediting things.
"Questionable" are more technical questions I had which I think should be
answered/corrected/clarified/etc.

-Steve

--
Steve Huston, Riverace Corporation
Total Lifecycle Support for Your Networked Applications
http://www.riverace.com 



(These start at part 2, section 7 - the first part was sent to the TC on
Nov 22 so the remainder is here)

These are also marked in the PDF paper copy. Here they're also classified
according to how easy it is to fix (usually copyediting things) and how
important it is (protocol things).

Page numbers used are from the PDF copy.

"The Chicago Manual of Style" is the standard I used for copy editing.


Easy:

Part 2, section 6.12, 13th para, 1st sentence: Change "...achieve
different guarantees, for example if the sending..." to "...achieve
different guarantees. For example, if the sending..."

Part 2, section 7: It may be a good idea to supply some introductory text
to explain what the XML fields mean (class="composite" source="list"
provides="frame")

Part 2, section 7.1, hostname: Remove "dns" from first sentence? It's not
going to be used to do a lookup, and use of a proxy may make it useful to
specify some name other than one registered in DNS.

Part 2, section 7.1, hostname, 2nd para, last sentence: "... what a
different value to those already..." should be "... what a different value
from that already..." and "specific" should be "specified" (but I think
I've seen the "specified" change reported already).

Part 2, section 7.1, max-frame-size, last sentence: Remove "large" at the
end.

Part 2, section 7.1, idle-time-out: "time-out" should be "timeout". "eg,"
should be "e.g.,".  Near "close the connection with an error ..." should
maybe cross reference section 4.3 to clarify the intention is to close the
AMQP connection, not the TCP connection (at least immediately).

Part 2, section 7.1, incoming-locales, 3rd sentence: "The receiving
partner will chose..." should be "The receiving partner will choose..."

Part 2, section 7.1, offered-capabilities: Remove "the" from description
"the extension capabilities" - "the" isn't used on most of the
descriptions, so remove it to be consistent.

Part 2, section 7.1, desired-capabilities: Remove "the" from description
"the extension capabilities" - "the" isn't used on most of the
descriptions, so remove it to be consistent.
Also, there's more vertical space between the name and descriptive
paragraph than for the other items
Also, 1st sentence: add comma after "i.e."
Also, it may be good to specify (if I understand this correctly) that the
sender MUST NOT use a capability it does not list in desired-capabilities.

Part 2, section 7.3, name: Add comma after "e.g."

Part 2, section 7.3, handle: Recommend adding a descriptive phrase (others
have one in italics) and a descriptive sentence about what the handle is
before restricting it. Suggest basing this on the first two sentences in
section 6.2.

Part 2, section 7.3, role: Recommend adding a descriptive sentence for
role, esp  noting that it's a sender/receiver distinction.

Part 2, section 7.3, unsettled, 1st para, last sentence: "See 6.13
Resuming Deliveries" should be "See section 6.13".

Part 2, section 7.3, unsettled, 2nd para, 1st sentence: capitalize MAY.
Also, "(see amqp-error)" should be "(see section 8.15)"

Part 2, section 7.3, initial-delivery-count: Add a short descriptive
phrase (others have one in italics) and a descriptive sentence about what
the initial-delivery-count is before restricting it. Also, "See 6.7 Flow
Control" should be "See section 6.7".

Part 2, section 7.4, next-incoming-id, 2nd sentence: should be "This value
MUST be set unless the sender has not yet received the begin frame for the
session."

Part 2, section 7.4, next-incoming-id, 3rd sentence: "See 5.6 Session Flow
Control" should be "See section 5.6"

Part 2, section 7.4, incoming-window, 2nd sentence: "See 5.6 Session Flow
Control" should be "See section 5.6"

Part 2, section 7.4, next-outgoing-id, 2nd sentence: "See 5.6 Session Flow
Control" should be "See section 5.6"

Part 2, section 7.4, outgoing-window, 2nd sentence: "See 5.6 Session Flow
Control" should be "See section 5.6"

Part 2, section 7.4, delivery-count, 4th para: "See 6.7 Flow Control"
should be "See section 6.7"

Part 2, section 7.4, link-credit, 1st para, 4th sentence: "See 6.7 Flow
Control" should be "See section 6.7"

Part 2, section 7.4, available, 1st para, 4th sentence: "See 6.7 Flow
Control" should be "See section 6.7"

Part 2, section 7.4, drain, 1st para, 4th sentence: "See 6.7 Flow Control"
should be "See section 6.7"

Part 2, section 7.4, echo, 2nd para, 1st sentence: "...state to be echoed,
however the receiver MAY fulfil this..." should be "...state to be echoed;
however, the receiver MAY fulfill this..."
Also, "...flow performative carrying link specific state" should be
"...flow performative carrying link-specific state"

Part 2, section 7.5, delivery-tag, 2nd sentence: "multi transfer" should
be "multi-transfer"

Part 2, section 7.5, settled: Does "first" and "subsequent" transfers
refer to multi-transfer messages, or to resuming? Also, 2nd para, 1st
sentence: add comma after "i.e."

Part 2, section 7.5, more: "That is a receiver..." add comma after "is".

Part 2, section 7.5, state, 2nd sentence: "deliveries are resumed after a
resuming a link." delete first "a"
Also, 2nd sentence, add comma after "i.e."

Part 2, section 7.6, 2nd para after XML, 1st sentence: add comma after
"i.e."

Part 2, section 7.7, 1st para after XML, 2nd sentence: "un-maps" should be
"unmaps"

Part 2, section 7.7, closed: should be "See section 6.6."

Part 2, section 8.10, 2nd sentence: Remove comma after "arithmetic"

Part 2, section 8.16, hostname, 2nd sentence "suring" should be "during"

Part 3, section 2, 2nd para: "annotated message" should not be italicized.

Part 3, section 2, 3rd para: "bare message" should not be italicized.

Part 3, section 2, 3rd para: insert "three" before "sections" and insert a
colon after "sections"

Part 3, section 2, message diagram should have a Figure label.

Part 3, section 2, 4th para, 2nd sentence: insert comma after "That is"

Part 3, section 2, 4th para, 3rd sentence: Change "may not" to "MUST NOT"?

Part 3, section 2, 5th para bullets, "The body...": "either" should be
"one of the following three choices" (either refers to two)

Part 3, section 2.1, 1st para after XML, 2nd sentence: What are the
default values to be assumed, or where are they described?

Part 3, section 2.1, ttl: Quotes around "live" are both close quotes.
First one should be an open quote. (`` in latex, I believe)
Also, last sentence: insert comma after "i.e."

Part 3, section 2.1, first-acquirer: Add reference to section 3.1?
(acquiring has not been discussed before this point)

Part 3, section 2.3, 1st para, 3rd sentence: Add comma after "e.g."

Part 3, section 2.3, 2nd para, 1st sentence: change comma before "however"
to a semi-colon; add comma after "however"
Also, change "however it" to "however, in"

Part 3, section 2.3, 2nd para, 2nd sentence: "some annotation" should be
"some annotations" (add an s)
Also, after "purpose" change hyphen to an em-dash and "may be being" to
"could be"

Part 3, section 2.4, 1st para after XML, 2nd sentence: change to "The
properties section is part of the bare message; therefore, if
retransmitted by an intermediary, it MUST remain unaltered."

Part 3, section 2.4, content-encoding, throughout: "Content-Encoding"
should not be capitalized, except when starting a sentence where it can be
"Content-encoding".
Also, 5th para, "Content-encoding MUST not be set..." should be
"Content-encoding MUST NOT be set..."

Part 3, section 2.4, group-id, group-sequence: No mention of groups before
this point; add a reference to where groups are discussed.

Part 3, section 2.5, 2nd para: insert comma after "that is" and remove
parentheses.

Part 3, section 3, 3.1: There's only one subsection so there shouldn't be
a division. Should be section 3 "Distribution Node Message States"
Also, 1st para, 1st sentence: "distribution node" is not defined - it
should be. Without that knowledge the rest of the section is difficult to
understand.
Also, 1st para, 2nd sentence: change comma before "however" to a
semi-colon and add a comma after "however"

Part 3, section 3.1, 3rd para, 3rd sentence: add comma after "e.g."
Also, "default-outcome" - this isn't defined - where does it come from?

Part 3, section 4, 1st and 3rd para: "delivery-state" should be "delivery
state"

Part 3, section 4.4, 1st para, 2nd sentence: add comma after "i.e."
Also, 4th sentence: change comma after "frames have been sent" to an
em-dash
Also, 5th sentence: "time bound" should be "time-bound"

Part 3, section 4.5, 1st para, 4th sentence: change comma after "frames
have been sent" to an em-dash
Also, 5th sentence: "time bound" should be "time-bound" and add comma
after "e.g."

Part 3, section 4.6, 1st sentence: "In Part 2: 6.13 Resuming Deliveries"
should be "Part 2 section 6.13 provides" and delete "was provided" at the
end of the sentence.

Part 3, section 4.6, all the diagrams should have Figure labels.

Part 3, section 4.6, 3rd para, 2nd sentence (same in 6th para, 2nd
sentence and 8th para, 2nd sentence): Quotes around "at least once" and
"at most once" are both close quotes; change leading one to an open quote.
Also, should "at most once" be "exactly once"? at-most-once can be 0,
which could result in a lost message which need not be retransmitted.
Also, change comma before "however" to semi-colon and add comma after.
(3rd para and 8th para)

Part 3, section 4.6, 8th para, 3rd sentence: should insert "have" between
"not" and "enough"?
Also, "MAY take some action..." what might that action be?

Part 3, section 4.6, 14th para, 2nd sentence: change "since we know" to
"since it is known" and "we have no need" to "there is no need".

Part 3, section 4.6, 15th para, 1st sentence: change "we have to assume"
to "it must be assumed".

Part 3, section 4.6, 18th para: should "state Receivedsection-number=0" be
"state Received, section number=0"?

Part 3, section 5.1, 1st para, 2nd sentence: Refer to singular filter in
the definition: "A filter can be thought of as a function which takes a
message as input and returns a boolean value:"

Part 3, section 5.1, 1st para, 2nd sentence: "filter" should not be
italicized.
Also, add comma after "e.g."

Part 3, section 5.2: Refers to "Source" capitalized, whereas 5, 5.1 did
not, and neither does 5.3. Suggest not capitalizing it in 5.2.

Part 3, section 5.2, 3rd para, 1st sentence: add comma after "i.e."

Part 3, section 5.2, 3rd para, 2nd sentence: "and thus anyway ineligible
for transfer" - remove "anyway"

Part 3, section 5.3, 1st para, 2nd sentence: first quote on "minimal"
should be an open quote.

Part 3, section 5.3, expiry-policy: Should be "See section 5.6."

Part 3, section 5.3, dynamic-node-properties, 4th sentence: should be "See
section 5.9."

Part 3, section 5.3, filter, 1st sentence: Should be "See section 5.8."

Part 3, section 5.3, default-outcome, last sentence: Add comma after
"e.g."

Part 3, section 5.3, outcomes, last sentence: Add comma after "e.g." and
change first quote on "amqp:accepted:list" to an open quote.

Part 3, section 5.4, 1st para, 2nd sentence: first quote on "minimal"
should be an open quote.

Part 3, section 5.4, durable: "or not state at all." should be "or no
state at all."

Part 3, section 5.4, expiry-policy: Should be "See section 5.6."

Part 3, section 5.4, dynamic-node-properties, 4th sentence: should be "See
section 5.9."

Part 3, section 5.5, 2nd sentence: Remove " value" from the end.

Part 3, section 5.8, 1st para, 2nd sentence: "ether" should be "either".

Part 3, section 5.8, 1st para, 5th sentence: Add comma after "i.e."

Part 3, section 5.9, 1st sentence: remove hyphen between "Node" and
"used".

Part 3, section 5.9, supported-dist-modes, 2nd para, 2nd sentence: Add
comma after "That is". Remove "as" after "defined"

Part 4, section 1, 2nd para, 2nd sentence; 3rd para, 1st and 2nd
sentences; section 2, 1st para, 2nd sentence; section 2, 4th para, 3rd
sentence; section 3, 2nd para, 3rd sentence: "transaction resource" and
"transaction controller" should not be italicized (only at their first
mention).

Part 4, section 1, 3rd para, 2nd, 3rd, 5th sentences: "control link"
should not be capitalized (only at first mention).

Part 4, section 2: why is "coordinator" bold courier font? The first use
in 1st para should be italicized; other uses should be normal body font.

Part 4, section 2, 2nd para, 4th sentence: Should "outcome of the declare
at the receiver." be "outcome of the declare from the receiver."?

Part 4, section 2, 2nd para, last sentence: Is there a prescribed error
for this condition?

Part 4, section 4, 1st sentence: "Part 3: 3.1 Message States" should be
"Part 3, section 3.1"

Part 4, section 4, all 3 bullets in 1st para: Add comma after "i.e."

Part 4, section 4, 3rd para, 2nd sentence: "Part 3: section 4 Delivery
State of the messaging specification" - remove "Delivery State of the
messaging specification"

Part 4, section 4, 4th para, 1st sentence: Add comma after "i.e."
Also, remove "both"

Part 4, section 4.1, 2nd para: Remove parens from around "successfully"

Part 4, section 4.1, 3rd para, 2nd sentence: Add comma after "That is"

Part 4, section 4.2, 1st para, 3rd sentence: change "non discharged" to
"non-discharged" and do not italicize.

Part 4, section 4.2, 3rd para, 2nd sentence: Change "controller initiated"
to "controller-initiated" and "resource initiated" to
"resource-initiated".
Also, change hyphen between "controller" and "i.e." to an em-dash and add
a comma after "i.e.".

Part 4, section 4.3: all the italicized words should not be.

Part 4, section 4.3, 4th para, 1st sentence: add a comma after "i.e." and
a comma after the closing paren.

Part 4, section 4.3, 4th para, 2nd sentence: "complete the sending" should
be "complete sending" ?

Part 4, section 4.4, 2nd sentence: transpose "therefore" and "can"

Part 4, section 4.4.2, 1st sentence: Change "Here we consider" to "This
section considers"

Part 4, section 4.4.2, 2nd sentence: Change "see Transactional
Acquisition" to "see section 4.4.3"

Part 4, section 5.1, capabilities, last sentence: Should be "See section
5.7."

Part 4, section 5.2, global-id, 1st sentence: "MUST be associated work
with" should be "MUST be associated with".
2nd sentence: "txn-id will associated work with" should be "txn-id will be
associated with"
3rd sentence: Coordinator should not be capitalized.

Part 5, section 1: "tunneled" should be "carried", or "over" should be
"through" (one carries over and tunnels through). "carried over" is the
more correct one here, in my opinion, as tunneling implies a change in
protocol (tunnel ipv6 through ipv4, for example).

Part 5, section 1, 2nd para, 3rd sentence: Should be "Therefore, section 3
defines the frames necessary for SASL to function."

Part 5, section 1, 2nd para, last sentence: "Connection" should not be
capitalized.

Part 5, section 2, 1st sentence: "tunnel" should be "session". Also, add
"before commencing with TLS negotiation" at end of sentence.

Part 5, section 2, 2nd sentence: initial quote on "AMQP" should be an open
quote.

Part 5, section 2, 2nd para: Replace "TLS tunnel" with "TLS protocol"
Also, remove "Version Negotiation" from reference to section 2.

Part 5, section 2, 4th para, 2nd bullet, 2nd sentence: "differs to" should
be "differs from"

Part 5, section 2, 4th para, 4th bullet: Add comma after "i.e."
Also, "write-half" should be "write half"

Part 5, section 2.1, 1st sentence: "using tunnelling" should be "using the
above procedure"

Part 5, section 2.1, 2nd para, 1st sentence: "tunnel negotiation" should
be "initial TLS-invoking"

Part 5, section 2.1, 2nd para, 2nd sentence: Add comma after "e.g."

Part 5, section 3, 1st sentence: "tunnel" should be "layer"

Part 5, section 3, 2nd sentence: initial quote on "AMQP" should be an open
quote.

Part 5, section 3, 2nd para: "tunnel" should be "layer". Also, remove
"Version Negotiation" from the section 2 reference.

Part 5, section 3.1, 1st sentence: Remove "Framing" from section 3
reference.

Part 5, section 3.1, 2nd para, 3rd sentence: initial quote on "sasl-frame"
should be an open quote.
Also, remove extra space before period.

Part 5, section 3.2, 1st para: "Server" should not be capitalized.
Also, 2nd para: "Client" should not be capitalized.

Part 5, section 3.3.1, 1st sentence; sasl-server-mechanisms description;
section 3.2.2, 1st and 2nd sentences; section 3.3.5, 1st sentence; section
3.3.5, code description; section 3.3.6, 1st sentence: "sasl" should be
capitalized (SASL).

Part 5, section 3.3.2, mechanism, 2nd sentence: "Connection" should not be
capitalized.

Part 5, section 3.3.2, hostname, 2nd para, 1st sentence: insert "either"
after "field SHOULD"



Questionable:

Part 2, section 6.7 and section 7.4, delivery-count: It would be helpful
to explicitly state what is included in this count.

Part 2, section 7.3, para after XML, 2nd sentence: mentions "The opening
flag" but there is no opening flag described.

Part 2, section 7.3, snd-settle-mode, rcv-settle-mode: What is the effect
of a Sender/Receiver not honoring the requested mode? Since there's only
one attach sent in each direction, what's the intended use of this? Only
one side can learn the other's preference before sending its own attach.

Part 2, section 7.3, incomplete-unsettled: How does the incomplete map
become completed? Otherwise no messages can be sent.

Part 2, section 7.5, delivery-id: How would one know if a message with
delivery-id(2) is a mis-id'd continuation of delivery-id(1) or a new
message? By using the delivery-tag as well (if it's missing, it must be a
continuation)?

Part 2, section 7.5, settled: What is the desired/required behavior if the
values in different transfers of a multi-transfer message are different?

Part 2, section 7.5, state: It's unclear what values the state may have
and what makes a state terminal. Refer to part 3 section 4.

Part 3, section 2.10: Refers to allowed symbolic keys as starting with
both "x=" and "x-opt-" - which is right?
Also, quoted terms use close quotes at start and end; change the start to
open quotes (`` in latex, I believe)

Part 3, section 4.1: It's not clear how the boundaries between sections
are established. How does a sender mark sections, or a receiver know where
the boundaries are?

Part 3, section 4.3, error field: "will be placed" should be "MUST BE
placed" ?

Part 4, section 4.1, 2nd para: can a message only be available _after_ the
transaction has been discharged? Is the definition of "discharged" such
that the message is already made available?