[Bugs & Requests][Wiki]

6.6. Core Protocol Semantics

Conceptually, VOP is an asynchronous message passing protocol. This is reflected by the MESSAGE primitive, see above. However, Vobject interaction often requires longer series of message exchanges, as reflected by the INVOCATION and REQUEST primitives. VOP provides a correlation mechanism to implement these: When a peer receives a message marked with a nonce, it may respond by sending one or more reply messages. If any such reply messages are sent, the peer must mark the last of them with the same nonce as on the received message. There is no such requirement for the intermediary messages, they may have arbitrary nonce values, or even omit them. For better protocol readability however, the intermediary messages should have a nonce formed by concatenating the original nonce with a dash (-) and a sequence number. The sequence number should start at 1 for the first message and be incremented for every subsequent intermediary message.

Again for better protocol readability, message types and methods should follow this convention: All reply messages should be of the <update> type. Reply messages in INVOCATION style should use a method name consisting of the original method name extended by "-reply". Update messages in REQUEST style should use a method name consisting of the original method name extended by "-update". The latter form (and preferably the same method names) should also be used for cache update messages, which indicate that a peer has modified the state of a local Vobject through local method calls on it.

Sometimes a peer may not be able to comply to a received message, or determine that it violates access rights, policies, etc. In this case it should indicate an error to the requesting peer. For this purpose, it should send a reply message whose header conforms to the normal reply, in particular the nonce and method attributes. However, the body of the message must not contain the usual reply parameters, but instead must have the special parameter <error> as first child element. The value of the error parameter should be a human readable text describing the cause of the error. If no appropriate reply method exists, the peer should either ignore the incident, or treat it as a fatal protocol error.

A peer must indicate a fatal error by closing the offending connection, after sending any error replies as described above. If the fatal error was not caused by any message, the peer should send a special diagnostic error message instead. This message must be of the type <message>, and use the special method "core:error". The body must contain an <error> parameter containing a string describing the cause of the error.

When a peer received a message with unknown method, it should not send an error message, but ignore the offending message instead (except perhaps logging the incident). This allows some form of compatibility for unknown Vobject types, and also helps in reducing the effect of certain flooding attacks. Consequently, a caller that is waiting for reply messages could block forever. To prevent this, the messaging layer should use a timeout mechanism. If no reply message is received after a certain time (30 seconds), it should abort the exchange and indicate a protocol error to the caller.