Paddy Byers feedback

[mattheworiordan]

@paddybyers feedback:

---

I have lots of editorial /style comments on the text but I’m not going to go through them here. We can address the details of the text once we’ve settled the technical content, so these are my high-level comments.

I agree with the other comments that this document is partly trying to be an API spec (but independent of language) and partly a protocol spec (but independent of transport and encoding). The opening description needs to make it clear how this specification is positioned - ie it is a generic specification which can be used to create a concrete API specification by supplying a language binding, and a concrete protocol specification by supplying a transport binding.

I would prefer that the API specification part would be written using an existing (ie externally-specified) IDL; this means that we don’t have to define an IDL, and might also mean that we don’t have to also specify particular language bindings because they exist as part of the IDL definition.
I don’t really understand the role of the history and object storage plugin APIs. Why aren’t these just part of the library API (possibly optional)? I think it would be an implementation detail of a particular library implementation if it admits multiple providers of history or object storage for a given transport binding.

I agree that settling on terminology is important but I’m not a fan of the payload/headers terms proposed by Julien - I think that’s too suggestive of HTTP. We could reuse terminology of the IDL - eg using WebIDL terminology a DataFrame is an Interface with a series of Attributes; the Library is an Interface with a series of Operations. It would be preferable, however, if we are able to admit implementations where encoded objects or deltas were carried in the body of an AMQP message, say, and other attributes in headers.

I don’t see why a DataFrame containing a delta can’t also contain a dataUri - just because the delta is the 5th update in a sequence, that doesn’t automatically mean you have to reconstruct from history by getting all of the deltas and the same base object - in certain applications you can have a means to retrieve the specific object at any arbitrary serial. Also, I don’t see why you can’t have a deltaUri - ie the message is a pushed indication that there is a change, but the change itself can be obtained via a deltaUri.

I agree with the comments re the delta algorithm vs format. The protocol depends on there being an agreed meaning of the delta format. The algorithm to determine the delta doesn’t need to be specified, and in many applications the algorithm itself may be proprietary or have IP restrictions.
You’ve mentioned the RON format, which is specifically a format for commutative updates to CRDTs - whereas this specification currently only supports totally ordered updates. I wonder if we could allow for future extension of this spec to support CRDTs and commutative updates; it would mean allowing the version field to be generalised from the totally-ordered numbers it is now, to a value from a type that has a partial order. Although we’re not going to define that now, we could perhaps mention that as an intended future direction, and to be compatible with that we could even rename “delta” to “update”.

The RON link is out of date - it is now https://github.com/gritzko/ron

Re UIDs - I don’t agree with forcing them to be v4 UUIDs - I think there is value in them also being allowed to be URIs, or any ID whose uniqueness is guaranteed by the underlying storage mechanism without requiring translation.

I think we should be precise when we define the Transport Requirements. The transport should guarantee at least once delivery. Out of order delivery is more problematic - I think it is too restrictive for us to prohibit it entirely but if it is allowed then what are we saying? Right now it’s not clear what we’re saying. Either it’s permitted, and we say how it is handled, or it’s not permitted. I don’t think it makes sense in a spec like this to say we advise against it - at least, that’s non-normative implementation/deployment guidance, not part of the normative spec.