Hi, everyone. I've been using the draft management spec to develop some
command line tools[1], and I've got some questions and comments. These
comments are based on working draft 8 of the spec[2].
Thanks,
Justin
[1] https://github.com/ssorj/bailey (Watch out! It's a work in progress.)
[2]
https://www.oasis-open.org/committees/document.php?document_id=52425&wg_abbrev=amqp
# Use of AMQP application-properties
Given that values in AMQP 1.0 application properties cannot be lists or
maps (yikes--I didn't know that), I feel it's inadvisable to use
application properties to define requests. We'd be better off using
properties in the message body. Otherwise, we'll have to define standard
string encodings in every instance where we want to use a non-scalar type.
# Application properties and studlyCaps
The spec calls for studlyCaps for standard property names, whereas an
earlier draft had hyphenated names. FWIW, I prefer the latter, since it’s
in line with the core AMQP spec.
# QUERY and pagination
There doesn’t appear to be a way to query for the total count without
fetching all the values. Without that, you can’t build a data efficient
page-navigation UI that offers links to each page (or just the last page).
Requests using offset and count should perhaps instead use offset and
“limit”. That’s more familiar to those who have used SQL, and it correctly
signals that the number returned may be less than the number requested. In
my view, the request should use “limit”, and the response should use
“count”.
Also, if we’re doing paging we need to do sorting as well. Otherwise, A
client UI cannot build a sortable paginated table without pulling down
everything.
# Request-response
There’s a note in section 4 that multiple response messages may be produced
for a single request. How should a client determine whether the response
is complete?
# GET-MGMT-NODES
The text says the response message must contain “a list of addresses of
other Management Nodes”. Perhaps this should more explicitly prohibit
listing the currently-in-communication management node (or drop the word
"other").
# [DE]REGISTER
What is the intended use of this? That is, what new behavior do you get
when something is registered?
# Ping
I’d like to see a standard PING or ECHO operation on $management. I can
simulate it by using an arbitrary operation, but that seems less than
straightforward for implementors.
# Clerical stuff
3.3.3.1: Awkward phrasing: “so if any of the changes cannot be applied, the
entire operation should not be applied and to multiple values changed this
MUST result in a failure response”
3.4.1: Typo: “this operation supports pagination <though> which a request”
3.4.1: Awkward phrasing: “A result set of size N <can be considered to
containing elements>”
# Odds and ends
- 2.3: Should this reference the AMQP definition of a “node”?
- 3.1: It would be nice to mention that locales is a comma-separated list.
The RFC mentions it, but you have to dig down a bit.
- 3.3.1.2: What is a good example of a generic value made specific in an
UPDATE response?
- 3.3.3: Is the lack of attribute append a problem? Right now, there is
only replacing list values, and dueling actors could mean lost state.
command line tools[1], and I've got some questions and comments. These
comments are based on working draft 8 of the spec[2].
Thanks,
Justin
[1] https://github.com/ssorj/bailey (Watch out! It's a work in progress.)
[2]
https://www.oasis-open.org/committees/document.php?document_id=52425&wg_abbrev=amqp
# Use of AMQP application-properties
Given that values in AMQP 1.0 application properties cannot be lists or
maps (yikes--I didn't know that), I feel it's inadvisable to use
application properties to define requests. We'd be better off using
properties in the message body. Otherwise, we'll have to define standard
string encodings in every instance where we want to use a non-scalar type.
# Application properties and studlyCaps
The spec calls for studlyCaps for standard property names, whereas an
earlier draft had hyphenated names. FWIW, I prefer the latter, since it’s
in line with the core AMQP spec.
# QUERY and pagination
There doesn’t appear to be a way to query for the total count without
fetching all the values. Without that, you can’t build a data efficient
page-navigation UI that offers links to each page (or just the last page).
Requests using offset and count should perhaps instead use offset and
“limit”. That’s more familiar to those who have used SQL, and it correctly
signals that the number returned may be less than the number requested. In
my view, the request should use “limit”, and the response should use
“count”.
Also, if we’re doing paging we need to do sorting as well. Otherwise, A
client UI cannot build a sortable paginated table without pulling down
everything.
# Request-response
There’s a note in section 4 that multiple response messages may be produced
for a single request. How should a client determine whether the response
is complete?
# GET-MGMT-NODES
The text says the response message must contain “a list of addresses of
other Management Nodes”. Perhaps this should more explicitly prohibit
listing the currently-in-communication management node (or drop the word
"other").
# [DE]REGISTER
What is the intended use of this? That is, what new behavior do you get
when something is registered?
# Ping
I’d like to see a standard PING or ECHO operation on $management. I can
simulate it by using an arbitrary operation, but that seems less than
straightforward for implementors.
# Clerical stuff
3.3.3.1: Awkward phrasing: “so if any of the changes cannot be applied, the
entire operation should not be applied and to multiple values changed this
MUST result in a failure response”
3.4.1: Typo: “this operation supports pagination <though> which a request”
3.4.1: Awkward phrasing: “A result set of size N <can be considered to
containing elements>”
# Odds and ends
- 2.3: Should this reference the AMQP definition of a “node”?
- 3.1: It would be nice to mention that locales is a comma-separated list.
The RFC mentions it, but you have to dig down a bit.
- 3.3.1.2: What is a good example of a generic value made specific in an
UPDATE response?
- 3.3.3: Is the lack of attribute append a problem? Right now, there is
only replacing list values, and dueling actors could mean lost state.