I've written up the following document:
https://fedorahosted.org/matahari/wiki/Requests
to describe the XML documents sent to and returned from Matahari over virtio-serial.
Please take a few minutes to review and provide feedback on this format.
On Mon, Jun 07, 2010 at 10:20:06AM -0400, Darryl L. Pierce wrote:
I've written up the following document:
https://fedorahosted.org/matahari/wiki/Requests
to describe the XML documents sent to and returned from Matahari over virtio-serial.
Please take a few minutes to review and provide feedback on this format.
Looks fine. Just a couple comments.
Does the reqid need to be a string? Would an integer be sufficient?
Also, is the reqid a client identifier only? Or is there more to it? A client id seems reasonable. I'm not sure why we would need anything more than that. That said, when I first saw "reqid" I thought it intended to identify the type of request. Since this is not the case, would "id" or "client_id" be a better name for that var?
Ryan
On Tue, Jun 08, 2010 at 12:39:28PM -0500, Ryan O'Hara wrote:
On Mon, Jun 07, 2010 at 10:20:06AM -0400, Darryl L. Pierce wrote:
I've written up the following document:
https://fedorahosted.org/matahari/wiki/Requests
to describe the XML documents sent to and returned from Matahari over virtio-serial.
Please take a few minutes to review and provide feedback on this format.
Looks fine. Just a couple comments.
Does the reqid need to be a string? Would an integer be sufficient?
Either is fine. It just needs to be client-side unique so that the client can map the response to the right place.
Also, is the reqid a client identifier only? Or is there more to it? A client id seems reasonable. I'm not sure why we would need anything more than that. That said, when I first saw "reqid" I thought it intended to identify the type of request. Since this is not the case, would "id" or "client_id" be a better name for that var?
We can't use "id", that's a reserved attribute in XML. I don't like "client_id" since that sounds like an identifier for the client and not for the request. "reqid" is short and I'm fine with expanding it to "request-id" to make it clearer what it is, and to ensure the name clearly says what the value is.
On Jun 8, 2010, at 10:31 PM, Darryl L. Pierce wrote:
On Tue, Jun 08, 2010 at 12:39:28PM -0500, Ryan O'Hara wrote:
On Mon, Jun 07, 2010 at 10:20:06AM -0400, Darryl L. Pierce wrote:
I've written up the following document:
https://fedorahosted.org/matahari/wiki/Requests
to describe the XML documents sent to and returned from Matahari over virtio-serial.
Please take a few minutes to review and provide feedback on this format.
Looks fine. Just a couple comments.
Does the reqid need to be a string? Would an integer be sufficient?
Either is fine. It just needs to be client-side unique so that the client can map the response to the right place.
I'd go with a string, then you can put UUIDs in there.
Also, is the reqid a client identifier only? Or is there more to it? A client id seems reasonable. I'm not sure why we would need anything more than that. That said, when I first saw "reqid" I thought it intended to identify the type of request. Since this is not the case, would "id" or "client_id" be a better name for that var?
We can't use "id", that's a reserved attribute in XML.
Really? I use it all the time.
I don't like "client_id" since that sounds like an identifier for the client and not for the request. "reqid" is short and I'm fine with expanding it to "request-id" to make it clearer what it is, and to ensure the name clearly says what the value is.
request-id or req-id would be my vote
-- Darryl L. Pierce, Sr. Software Engineer @ Red Hat, Inc. Delivering value year after year. Red Hat ranks #1 in value among software vendors. http://www.redhat.com/promo/vendor/
Matahari mailing list Matahari@lists.fedorahosted.org https://fedorahosted.org/mailman/listinfo/matahari
On Wed, Jun 09, 2010 at 11:39:15AM +0200, Andrew Beekhof wrote:
Either is fine. It just needs to be client-side unique so that the client can map the response to the right place.
I'd go with a string, then you can put UUIDs in there.
Also, is the reqid a client identifier only? Or is there more to it? A client id seems reasonable. I'm not sure why we would need anything more than that. That said, when I first saw "reqid" I thought it intended to identify the type of request. Since this is not the case, would "id" or "client_id" be a better name for that var?
We can't use "id", that's a reserved attribute in XML.
Really? I use it all the time.
I didn't mean that we couldn't _use_ "id", but that "id" has a predefined intent within XML:
I would rather not try to use it for a secondary purpose. Attributes are free to add to XML, so we can put our own into our document.
I don't like "client_id" since that sounds like an identifier for the client and not for the request. "reqid" is short and I'm fine with expanding it to "request-id" to make it clearer what it is, and to ensure the name clearly says what the value is.
request-id or req-id would be my vote
I prefer the former. If nobody objects, I'll update the wiki accordingly.
On Jun 7, 2010, at 4:20 PM, Darryl L. Pierce wrote:
I've written up the following document:
https://fedorahosted.org/matahari/wiki/Requests
to describe the XML documents sent to and returned from Matahari over virtio-serial.
Please take a few minutes to review and provide feedback on this format.
I would lean towards dropping the <args> scaffolding. We had them in pacemaker originally but removed them later because they didn't add any value and were annoying when packing and unpacking messages.
Also, I'm not sure about:
<response name="hostname">webserver01.priv.virt.mydomain.org</response>
Will all response elements have obvious names?
What about returning tuples? Some of the searches in the cluster and packaging sections need to return tuples like: (filename, linenum) and (provider, type)
On Wed, Jun 09, 2010 at 11:59:00AM +0200, Andrew Beekhof wrote:
I've written up the following document:
https://fedorahosted.org/matahari/wiki/Requests
to describe the XML documents sent to and returned from Matahari over virtio-serial.
Please take a few minutes to review and provide feedback on this format.
I would lean towards dropping the <args> scaffolding. We had them in pacemaker originally but removed them later because they didn't add any value and were annoying when packing and unpacking messages.
Fair point. Though I still would rather err on the side of using a container tag when multiples of a tag are returned. Then the rules for return different types of tags (such as a <value> and an <array> if we go down that path) are in the <responses> tag and not the <matahari> tag.
Also, I'm not sure about:
<response name="hostname">webserver01.priv.virt.mydomain.org</response>
Will all response elements have obvious names?
I modeled the XML along the lines of SOAP. Each value returned is mapped to a name so the client can extract them, since more than one value can be returned as you mention below.
What about returning tuples? Some of the searches in the cluster and packaging sections need to return tuples like: (filename, linenum) and (provider, type)
This would be solved when we tackle how we return arrays. I have a solution in mind that should answer both this question and the previous one about arrays.
<matahari request-id="abc123" type="response"> <responses> <response name="hostname">web.farkledoodle.com</response> <response name="addresses" response-type="array"> <element>192.168.1.1</element> <element>192.168.1.2</element> </response> <response name="interfaces" response-type="array"> <element> <value name="name">eth0</value> <value name="mac">00:11:22:33</value> </element> <element> <value name="name">eth1</value> <value name="mac">11:22:33:44</value> </element> </response> </array> </responses> </matahari>
In the above example, an array is identified by the response-type attribute. By default this value is "scalar" and only the child text tag is the value. But if the response-type is "array" then one of more element tags are parsed and the child text for those are the values of the array.
In the case of an array of tuples, then each element tag can have one or more value tags that are the name to value mapping for those tuples. So that would solve the above case where you name filename and linenum, or provider and type, returned within an array.
Thoughts?
I used "value" for the tag within the element tag to avoid recursion. But maybe we _want_ to have that type of deep nesting of values? That would allow us to model larger object graphs as needed without imposing any artificial limitation now. Maybe rather than <responses> and <response> we could use <values> and <value> instead?
On Jun 9, 2010, at 3:36 PM, Darryl L. Pierce wrote:
On Wed, Jun 09, 2010 at 11:59:00AM +0200, Andrew Beekhof wrote:
I've written up the following document:
https://fedorahosted.org/matahari/wiki/Requests
to describe the XML documents sent to and returned from Matahari over virtio-serial.
Please take a few minutes to review and provide feedback on this format.
I would lean towards dropping the <args> scaffolding. We had them in pacemaker originally but removed them later because they didn't add any value and were annoying when packing and unpacking messages.
Fair point. Though I still would rather err on the side of using a container tag when multiples of a tag are returned. Then the rules for return different types of tags (such as a <value> and an <array> if we go down that path) are in the <responses> tag and not the <matahari> tag.
Sure. I think this is what they're doing for the REST stuff and being consistent is good.
Also, I'm not sure about:
<response name="hostname">webserver01.priv.virt.mydomain.org</response>
Will all response elements have obvious names?
I modeled the XML along the lines of SOAP. Each value returned is mapped to a name so the client can extract them, since more than one value can be returned as you mention below.
ok
What about returning tuples? Some of the searches in the cluster and packaging sections need to return tuples like: (filename, linenum) and (provider, type)
This would be solved when we tackle how we return arrays. I have a solution in mind that should answer both this question and the previous one about arrays.
<matahari request-id="abc123" type="response"> <responses> <response name="hostname">web.farkledoodle.com</response> <response name="addresses" response-type="array"> <element>192.168.1.1</element> <element>192.168.1.2</element> </response> <response name="interfaces" response-type="array"> <element> <value name="name">eth0</value> <value name="mac">00:11:22:33</value> </element> <element> <value name="name">eth1</value> <value name="mac">11:22:33:44</value> </element> </response> </array> </responses> </matahari>
In the above example, an array is identified by the response-type attribute. By default this value is "scalar" and only the child text tag is the value. But if the response-type is "array" then one of more element tags are parsed and the child text for those are the values of the array.
In the case of an array of tuples, then each element tag can have one or more value tags that are the name to value mapping for those tuples. So that would solve the above case where you name filename and linenum, or provider and type, returned within an array.
Thoughts?
Apart from dropping the response-type field, I think its pretty good. For consistency though, it might be preferable to always use the third form - even when returning a single hostname. This would simplify the packing and unpacking logic.
So: <response name="hostlist"> <element> <value name="hostname">web.farkledoodle.com</value> </element> </response>
instead of: <response name="hostname">web.farkledoodle.com</response>
Now "//value[@name=hostname]" works regardless of how many results come back or if other data was also included.
I used "value" for the tag within the element tag to avoid recursion. But maybe we _want_ to have that type of deep nesting of values?
Do you have a particular use case in mind? I think avoiding recursion, at least initially, would be a good thing.
That would allow us to model larger object graphs as needed without imposing any artificial limitation now. Maybe rather than <responses> and <response> we could use <values> and <value> instead?
-- Darryl L. Pierce, Sr. Software Engineer @ Red Hat, Inc. Delivering value year after year. Red Hat ranks #1 in value among software vendors. http://www.redhat.com/promo/vendor/
On Thu, Jun 10, 2010 at 12:02:41PM +0200, Andrew Beekhof wrote:
I used "value" for the tag within the element tag to avoid recursion. But maybe we _want_ to have that type of deep nesting of values?
Do you have a particular use case in mind? I think avoiding recursion, at least initially, would be a good thing.
None initially, but I'm more thinking ahead to representing a object graph of some arbitrary depth. Yeah, I think you're right and avoiding it for the time being (without designing it away) is the best bet.
On Thu, Jun 10, 2010 at 12:02:41PM +0200, Andrew Beekhof wrote:
<matahari request-id="abc123" type="response">
Thinking this over, I think the request-id element needs to be something outside of the request message itself. If the payload, for whatever reason, fails CRC validation then there's no way to map the error message back to the client since that request-id isn't guaranteed to be accurate.
I think instead we should have the ID be a part of the message coming from client: the stream would send the starter marker, the request ID, the CRC value, then the length and the payload.
On Thu, Jun 10, 2010 at 5:30 PM, Darryl L. Pierce dpierce@redhat.com wrote:
On Thu, Jun 10, 2010 at 12:02:41PM +0200, Andrew Beekhof wrote:
<matahari request-id="abc123" type="response">
Thinking this over, I think the request-id element needs to be something outside of the request message itself. If the payload, for whatever reason, fails CRC validation then there's no way to map the error message back to the client since that request-id isn't guaranteed to be accurate.
I think instead we should have the ID be a part of the message coming from client: the stream would send the starter marker, the request ID, the CRC value, then the length and the payload.
makes sense
matahari@lists.fedorahosted.org
-
Andrew Beekhof -
Andrew Beekhof -
Darryl L. Pierce -
Ryan O'Hara