OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

amqp message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: AMQP 1.0 working draft comments


Fellow AMQPers,

At the most recent AMQP TC meeting I agreed to review the current working
draft spec. I have completed about half, through part 2, section 6. The
results are below for discussion at today's TC meeting. They are broken
into 3 categories:

Easy: mostly grammar, spelling, punctuation, formatting... easy stuff, but
not technical.

Questionable: Questions about content, missing info, etc. More
substantive.

Not easy: things that would take longer to address, but not technical
issues.

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


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.

I assume someone checked names and companies in Acknowledgements - I did
not.

Easy:

Page 1, Abstract:
First para, first sentence: "internet protocol" should not be capitalized,
nor should "business messaging."
4th sentence: insert comma between "efficient" and "binary" and between
"binary" and "peer-to-peer"

Page 1, Status:
1st sentence: spell out "Technical Committee"

Part 0, sect 1, 1st sentence: "internet protocol" and "business messaging"
should not be capitalized.

Part 0, sect 1, 2nd para:
1st sentence replace with "AMQP is comprised of several layers."
(Use third person consistently)
2nd sentence replace with "The lowest level contains an efficient, binary,
peer-to-peer protocol for transporting messages between two processes over
a network.
3rd sentence "The next level contains" instead of "Secondly we define"

Part 0, sect 1.1 "keywords" should be "key words" per RFC 2119

Part 0, sect 1.3 heading "Non-normative" instead  of "Non Normative"

Part 1, sect 1.1:
char "a single Unicode character"
uuid "a universally unique identifier as defined..."
string "a sequence of Unicode characters"

Part 1, sect 1.2, 1st para, last line "... within the application's
domain, and in messaging applications these custom types..." (remove ",
in" and comma after "applications")

Part 1, sect 1.2, 2nd para, 2nd sentence: "A descriptor" - do not
italicize. Also, remove comma between "custom type" and "and".
3rd sentence: "... is actually a representation of the custom type" - do
not italicize.

Part 1, sect 2.1 - 2.4: All the entries in "Description" columns should be
non-italicized. All entries in "Category" columns specifying a "n byte
value" should by hyphenated, e.g., 1-byte value, 0-byte value, 4-byte
value, etc.

Part 1, sect 2, pg 15 - format code diagram should have a Figure label.
(sub)category table should have a Table label.

Part 1, sect 2.1: diagram should have a Figure label.

Part 1, sect 2.1, pg 16 - should be a page break before Type: ulong

Part 1, sect 2.2: diagram should have a Figure label.

Part 1, sect 2.3: diagram should have a Figure label.

Part 1, sect 2.4: diagram should have a Figure label.

Part 1, sect 2.5: Table should have a Table label.

Part 1, sect 2.2 Type: symbol. Should have a normative reference to ASCII.
American National Standard for Information Systems - Coded Character Sets
- 7-Bit American National Standard Code for Information Interchange (7-Bit
ASCII), ANSI X3.4-1986, American National Standards Institute, Inc., March
26, 1986

Part 1, sect 2.3, Type: map, 2nd para, 3rd sentence: replace dash between
"ordered" and that is", with a comma. Insert comma after "that is."

Part 1, sect 2.4: Assume it is invalid to specify a 0x4 subcategory in the
element constructor. Maybe note this?

Part 1, sect 3, 1st para, 2nd sentence: "well-known" (insert hyphen
between "well" and "known").

Part 1, sect 3, 4th para, 4th (last) sentence: Replace "should be" with
"MUST".

Part 2, throughout: Network, Node, Link, Terminus, Termini, Source,
Target, Message, Container, Broker, Producer, Consumer, Queue, Frame,
Session, Connection, Channel, Endpoint,  - none of these should be
capitalized except if used as the first word of a sentence.

Part 2, sect 1, 1st sentence: Replace "The" with "An" (there isn't just
one AMQP network). Same correction in 3rd para, 1st sentence; also in 5th
para, 1st sentence.

Part 2, sect 1: diagrams (4) should have Figure labels.

Part 2, sect 1, 2nd para, 2nd sentence: should be "Each link attaches to a
node at a terminus."

Part 2, section 1, 4th para. Replace with "Nodes exist within a container.
A container is either a broker or a client application. Each container may
hold many nodes. Examples of AMQP nodes are producers, consumers, and
queues. Producers and consumers are the elements within a client
application that generate and process messages. Queues are entities within
a broker that store and forward messages."
Q on this... do queues only exist in brokers? Do brokers ever
produce/consume messages? The URL diagram implies no such restriction.

Part 2, section 1, 5th para, 1st sentence: "Specification" should not be
capitalized.

Part 2, section 1, last paragraph, 2nd sentence: remove "Performatives"
after "section 7".

Part 2, sect 2: diagram should have a Figure label.

Part 2, section 2, 1st para, 2nd sentence: the quotes around AMQP are both
close quotes - the opening one should be an open quote. Same issue on
"client" and "server" in 4th para, 1st sentence.

Part 2, section 2, 3rd para, 1st sentence: insert "actively" before
"opened"; replace "TCP Session" with "TCP connection."

Part 2, section 2, last sentence: Remove "Security Layers" after "section
1".

Part 2, sect 3: diagram should have a Figure label.

Part 2, sect 3.1: diagram should have a Figure label.

Part 2, section 3.1, DOFF description, 3rd sentence: insert "an" between
"data offset is" and "unsigned". Insert comma after "unsigned". 4th
sentence, insert hyphen between "8" and "byte" to make "mandatory 8-byte
frame header"

Part 2, section 3.1, TYPE description, 5th sentence: Remove parentheses;
remove "SALS" after"section 3".

Part 2, section 3.2, 1st para. Remove "Transport" after "section 1". 3rd
sentence, remove "Performatives" after "section 7".

Part 2, section 3.2, 2nd paragraph: Replace "time-out" with "timeout".
Replace "See 4.5 Idle Time-out of a Connection." with "(see section 4.5)"
immediately after preceding "interval" inside the closing period.

Part 2, sect 3.2: diagram should have a Figure label.

Part 2, sect 4: diagrams (2) should have Figure labels.

Part 2, section 4, 3rd para, 2nd sentence: remove quotes from "same".

Part 2, section 4, 4th para, last sentence: remove "Sessions" after "see
section 5".

Part 2, sect 4.1: diagram should have a Figure label.

Part 2, sect 4.2: diagram should have a Figure label.

Part 2, section 4.2, 1st para, 3rd sentence: "a priori" should be in
italics.

Part 2, sect 4.3: diagram should have a Figure label.

Part 2, sect 4.4: diagram should have a Figure label.

Part 2, section 4.5, heading: replace Time Out with Timeout
throughout text in that section: replace time-out with timeout

Part 2, section 4.5, 8th para, 1st sentence: Replace time-out's with
timeout.

Part 2, section 4.5, 4th para, 1st sentence: Replace "is any" with "is in"
addition...

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

Part 2, section 4.5, 5th para, 2nd sentence: Replace "can" with "MUST" or
"may" (if it's not a protocol requirement). Replace "up to channel-max"
with "up to the maximum negotiated channel number" (haven't seen
channel-max yet).

Part 2, section 4.5, 8th para, 1st sentence: Add comma after "e.g."

Part 2, section 4.6, don't speak in 2nd person:
HDR_RCVD: In this state the connection header has been received from the
peer but a connection header has not been sent.
HDR_SENT: In this state the connection header has been sent to the peer
but no connection header has been received.
OPEN_PIPE: In this state both the connection header and the open frame
have been sent but nothing has been received.
OC_PIPE: In this state, the connection header, open frame, any pipelined
connection traffic, and the close frame have been sent but nothing has
been received.
OPEN_RCVD: In this state connection headers have been exchanged. An open
frame has been received from the peer but an open frame has not been sent.
OPEN_SENT: In this state connection headers have been exchanged. An open
frame has been sent to the peer but not open frame has yet been received.
CLOSE_PIPE: In this state connection headers have been exchanged. An open
frame, any pipelined connection traffic, and the close frame have been
sent but no open frame has yet been received from the peer.
OPENED:    just transpose "both" and "been"
CLOSE_RCVD: In this state a close frame has been received indicating that
the peer has initiated an AMQP close. There should be no further frames
arriving on the connection; however, frames can still be sent. If desired,
an implementation MAY do a TCP half-close at this point to shut down the
read side of the connection.
CLOSE_SENT: In this state a close frame has been sent to the peer. (next
sentence unchanged). If desired, an implementation MAY do a TCP half-close
to shut down the write side of the connection.
DISCARDING: (no change)
END: (no change)

Part 2, section 4.7: the state diagram should have a "Figure" label, and
the following table should have a "Table" label.

Part 2, sect 5: diagram should have a Figure label.

Part 2, sect 5.1: diagram should have a Figure label.

Part 2, sect 5.2: diagram should have a Figure label.

Part 2, sect 5.3: diagram should have a Figure label.

Part 2, section 5.4, 1st para, 2nd sentence: Replace "hearing" with
"receiving"

Part 2, sect 5.4: diagram should have a Figure label.

Part 2, section 5.5, figure 2.4: it would be nice if this figure were
formatted the same as the connection state diagram in section 4.7.

Part 2, section 5.5, last sentence: replace "when" with "after"; replace
"is in" with "transitions to"; period after "state". Remove remainder of
sentence. A thing that is nonexistent does not have a state; also, there's
no mention of a nonexistent state.


Part 2, section 5.6, next-incoming-id: replace "implicit" with "expected".

Part 2, section 5.6, next-outgoing-id: Replace 1st sentence with "The
next-outgoing-id is the transfer-id to assign to the next transfer frame."

Part 2, section 5.6, remote-outgoing-window, 2nd sentence, "fo" should be
"of"

Part 2, section 5.6, receiving a flow: change "as well as copy" to "and it
MUST update"

Part 2, section 6, 1st para, last sentence: "deliver state" should not be
capitalized. Same in 2nd and 4th paragraphs.

Part 2, section 6, 2nd para, 2nd sentence: change to "Therefore, there are
two types of endpoint: senders and receivers."

Part 2, section 6.1, 2nd para: Replace "e.g." with "i.e.," (note comma)

Part 2, section 6.1, 3rd para, 2nd sentence: add comma after "i.e."

Part 2, section 6.1: there should not be a paragraph break between the
current 2nd and 3rd paragraphs.

Part 2, section 6.2: diagram should have a Figure label

Part 2, section 6.3, 6th para, last sentence: "acceptable, or if not,
detach." should be "acceptable, or, if not, detach the link."

Part 2, section 6.3, 7th para, 2nd sentence: "pre-empt" should be
"preempt"

Part 2, section 6.4, diagrams (2) should have Figure labels.

Part 2, section 6.7: all except math formula and mentions of the items in
the formula - don't italicize the item names (delivery-count, link-credit,
available)

Part 2, section 6.7, delivery-limit isn't positively defined.

Part 2, section 6.7, 1st para, 3rd sentence: Remove "when" (either that or
complete the phrase). Also, "link-credit" should not be italicized - it's
not a new term about to be defined - it's an entry in the state list
below.

Part 2, section 6.7, delivery-count, 1st sentence: remove "(at the Sender)
or received (at the Receiver)" The following sentence states the
receiver's value is always calculated so it's confusing to say when it is
incremented.
Also, it would be good to state what delivery-count _is_ - it's never
stated,  but must be inferred from the way it is handled.

Part 2, section 6.7, link-credit, 4th para, add comma after "i.e." (2
times)

Part 2, section 6.7, 1st para after the states list: add comma after
"i.e."

Part 2, section 6.7, 1st para after the states list: "... it is illegal to
send more messages." should be "...a sender MUST NOT send more messages."

Part 2, section 6.7, diagrams (3) should have Figure labels.

Part 2, section 6.8, diagrams (2) should have Figure labels.

Part 2, section 6.9, diagram should have a Figure label.

Part 2, section 6.10, diagram should have a Figure label.

Part 2, section 6.10, 2nd sentence: "in-flight" should be "in flight"

Part 2, section 6.12, 3rd para, last sentence: add '.' between "etc" and
","

Part 2, section 6.12, 5th para, 3rd sentence: Add comma after "e.g."

Part 2, section 6.12, 6th para, 2nd sentence: "disposition" should be
courier, bold.

Part 2, section 6.12, 6th para: insert "of" after "update its view"

Part 2, section 6.12, 9th para, 1st sentence: add comma after "e.g."

Part 2, section 6.12, 10th para, 1st sentence: add comma after "i.e."

Part 2, section 6.12, 14th para, 1st sentence: (don't speak in 1st person)
"Similarly, if we modify the basic scenario" change to "Similarly, if the
basic scenario is modified". Also, "we get an at-least-once guarantee."
should be "that yields an at-least-once guarantee."

Part 2, section 6.12, 15th para, 2nd sentence: "... sender settles before
his initial transmission." should be "sender settles before the initial
transmission."

Part 2, section 6.12, 16th para, 1st sentence: "pre-configured" should be
"preconfigured"

Questionable:

Part 1, sect 2.1: why are there multiple codes for some basic types?
1-byte unsigned integer: 0x50 (ubyte), 0x53 (smallulong) and 0x52
(smalluint)
1-byte signed integer: 0x51 (byte), 0x54 (smallint), 0x55 (smalllong)

Part 1, sect 2.1: "two's-complement" and "signed" seem to be used
interchangeably but they're not equivalent. Using both terms leaves open
the question of why, and casts doubt about what "signed" means (does it
mean 1's-complement?) Recommend specifying signed integer types as
"signed" and specify in the last sentence of section 2 (before section
2.1) that signed integer values are transmitted using two's-complement
representation, in network byte order.

Part 2, section 2, 3rd paragraph: says TCP server "MAY" elect to wait to
receive protocol version from client before sending its version. May want
to then clarify the list items below that imply the client sends a
protocol version first. For example, what if server sends AMQP 1.0.0
without waiting and client simultaneously sends AMQP 0.10.0? Maybe change
the "MAY" to "SHOULD"?

Part 2, Section 4.1, 6th (last) sentence: "After sending the open frame
each peer must..." yet section 4.2 gives a scenario where the "must" can
be violated. Change "must" to "SHOULD"? Also, same sentence, "... read its
partner's open frame and must..." - capitalize MUST.

Part 2, section 4.5, 6th para, 2nd sentence: replace "should not" with
"MUST NOT"?

Part 2, section 4.6: There's no description of HDR_EXCH state but it is in
the diagram in section 4.7

Part 2, section 6.12, 2nd para: mentions message state, but that hasn't
been defined and isn't nearby - what is it?

Part 2, section 6.12, 6th para: How can a message spontaneously attain a
terminal state? 

Part 2, section 6.12, 10th para, 2nd sentence: "In this case the Sender
should send..." - should "should" be "MUST" and "but not settle" be "and
MUST NOT settle"?


Not easy:

Part 0, Sect 1.2: [IEEE1003] title does not match that given on the
referenced web page. Single UNIX Specification (on the web site) is a
superset of 1003.1-2008. Which one is correct?

Part 0, Sect 1.3 Non-normative references:
[AMQPCONNCAP] URL doesn't exist
[AMQPCONNPROP] page body is empty
[AMQPDELANN] page body is empty
[AMQPFILTERS] page body is empty
[AMQPFOOTER] page body is empty
[AMQPLINKCAP] page is empty
[AMQPLINKPROP] page body is empty
[AMQPLINKSTATEPROP] URL doesn't exist
[AMQPMESSANN] page is empty
[AMQPSESSCAP] page body is empty
[AMQPSESSPROP] page has H1 but no icon, no body
[AMQPSOURCECAP] page displays HTML that does not render, but if it did it
would be an empty body
[AMQPTARGETCAP] page displays HTML that does not render, but if it did it
would be an empty body

There should be a glossary for technical terms.
atomic
binary
business messaging
network
octet
polymorphic
process
protocol
transaction

Part 2, section 6.7: This jumps right into details that are difficult to
understand until they've been completely read through a few times. It
would be good to add some high-level overview - a paragraph or two on the
concepts behind the details.




[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]