diff options
Diffstat (limited to 'proto.pod')
-rw-r--r-- | proto.pod | 135 |
1 files changed, 91 insertions, 44 deletions
@@ -1,23 +1,36 @@ -Objective: Connect two (or more) Tanja servers together. +=head1 Introduction -Multiple serialization formats: json, gob and possibly others. +This document defines a protocol to link two servers together with the intent +that they become part of the same network. The protocol is run on top of a +reliable bidirectional and stream-oriented connection, such as UNIX sockets or +TCP. -Assumes a point-to-point connection-based transport mechanism (e.g. UNIX -sockets and TCP). -=head1 HANDSHAKE +=head1 Handshake - server: ver,1,0 ser,json,gob - client: ver,1.0 ser,json +Since the server/client terminoligy is confusing in the context of Tanja, as +this protocol links two I<Servers> with each other, I'll not use those terms in +this document. Instead, we have the I<connecting server> that opens the +connection to the I<listening server>. Which server connected to the other only +matters for the discussion in the handshake part of the protocol, later this +distinction vanishes. -After a client has connected, the server sends the first message. This message -is a space-separated list of parameters, followed by a newline character (\n). -Parameters may themselves contain multiple items by separating them with -commas. Parameters must be self-describing, the order in which they appear does -not matter. The client then replies with a similar message. +After the connection has been established, the listening server is the first to +send a message. This message is a space-separated list of parameters, followed +by a newline character (\n). Parameters may themselves contain multiple items +by separating them with commas. Parameters must be self-describing, the order +in which they appear does not matter. Upon receiving this, the connecting +server then replies with a similar message. + +The following is an example handshake, where I<listen> is the listening server +(the one that has been connected to) and I<connect> is the server that started +the connection. + + listen: ver,1,0 ser,json,gob + connect: ver,1.0 ser,json Currently defined parameters are: @@ -25,35 +38,61 @@ Currently defined parameters are: =item ver -Protocol version, 1 is the major version and 0 the minor. Minor versions are -used for backward-compatible additions to the protocol, whereas major version -changes indicate incompatibilities. If a server supports multiple major -versions, it can list these in the same ver parameter as, for example: -C<ver,1.5,2.3>. Since minor releases are always backward-compatible, only the -most recent supported version has to be listed. +Protocol version, Formatted as a decimal number, followed by a dot and another +decimal number. The first number is the major version and the second the minor. +Minor versions are used for backward-compatible additions to the protocol, +whereas major version changes indicate incompatibilities. If the listening +server supports multiple major versions, it can list these in the same ver +parameter by separating them with a comma. For example: C<ver,1.5,2.3>. Since +minor releases are always backward-compatible, only the highest supported minor +version has to be listed. + +The connecting server replies with the version that will be used for the rest +of the connection (e.g. C<ver,1.0>). Most likely this will be the highest +version supported by both servers. -The client replies with the version that will be used (e.g. C<ver,1.0>), most -likely with the highest version supported by both client and server. +This document describes protocol version C<1.0>, which is currently the only +version available. =item ser -Serialization format. The server may indicate support for multiple -serialization formats, e.g. with C<ser,json,gob>. The client then decides which -format to use and indicates this in the reply (e.g. C<ser,json>). +Serialization format. The listening server may indicate support for multiple +serialization formats separated by a comma. For example C<ser,json,gob>. The +connecting server then decides which format to use and indicates this in the +reply (e.g. C<ser,json>). Accepted serialization formats are defined below. =back -=head1 MESSAGES +=head1 Messages After the handshake, messages are exchanged asynchronously. There is no -distinction anymore between the server and the client. The message format -described here is purely conceptual, see the serialization formats below for -actual encoding of these messages. +distinction anymore between the connecting and listening server. The message +format described here is purely conceptual, see the serialization formats below +for actual encoding of these messages. + + +=head2 Pattern synchronisation + +Each side of the link operates in one of two modes: One in which the sender of +tuples is not aware of the patterns that the receiver is interested in, and one +in which the pattern list of the receiver is synchronised with the sender. The +initial mode is the one without synchronisation of patterns. The side that is +responsible for sending the tuples dictates which mode to use. + +I<TODO:> This explanation is awfully vague, and so are the descriptions below. =over +=item PATTERNSYNC [on|off] + +Request the other side of the connection to either enable or disable +synchronisation of its pattern list. If synchronisation is disabled, no +REGISTER or UNREGISTER messages will be sent. + +I<TODO:> Note about sending the initial list. + =item REGISTER $pid $pattern Indicates that the sender of the message is interested in receiving tuples @@ -65,6 +104,10 @@ When a REGISTER message is received with a $pid that has already been used before, this should be taken as a sequence of C<UNREGISTER $pid> followed by the REGISTER command. +=item REGDONE + +I<TODO> + =item UNREGISTER $pid Indicates that the sender of the message is not interested anymore in receiving @@ -74,6 +117,13 @@ An UNREGISTER message with a $pid not known to the receiver (e.g. it has already been UNREGISTER'ed or has never been REGISTER'ed previously) should be ignored. +=back + + +=head2 Tuple communication + +=over + =item TUPLE $tid $tuple Passes a tuple from the sending side to the receiving side. Every tuple is only @@ -81,34 +131,31 @@ sent once, even if the other side has registered multiple patterns for which the tuple matches. $tid is a positive number between 0 and C<2^31-1>. If the sending side is not -interested in responses to this tuple (at least, not through a response -channel), then $tid is 0. Any other value is a means to identify the return -channel for this tuple among other active return channels. This allows replies -to this tuple to be sent back with the RESPONSE message. Every TUPLE message -with $tid>0 B<must> be replied to either with a corresponding CLOSE or a -disconnect. (Note, however, that there isn't a strict bound on when this CLOSE -has to occur) +interested in replies to this tuple (at least, not through a return-path), then +$tid is 0. Any other value is a means to identify the return-path for this +tuple among other active return-paths. This allows replies to this tuple to be +sent back with the REPLY message. Every TUPLE message with $tid>0 B<must> be +replied to either with a corresponding CLOSE or a disconnect. (Note, however, +that there isn't a strict time bound on when this CLOSE has to occur) -It is not an error to receive a TUPLE message for a tuple that does not match -any of the patterns registered with REGISTER. +=item REPLY $tid $tuple -=item RESPONSE $tid $tuple - -Send back a response tuple as reply to a TUPLE with the corresponding $tid. +Send back a reply tuple over the return-path identified with $tid. =item CLOSE $tid -Close a response channel. +Close the return-path identified with $tid. =back Either side may close the connection at any point. It is not necessary for to -send CLOSE on open channels or UNREGISTER for registered patterns when this +send CLOSE on open return-paths or UNREGISTER for registered patterns when this happens, things should be cleaned up automatically. -=head1 SERIALIZATION FORMATS + +=head1 Serialization formats =head2 JSON @@ -150,7 +197,7 @@ element is the tuple. [3,0,["variable","set","listen",false]] -=item RESPONSE +=item REPLY Message type 4. Exact same encoding as TUPLE. @@ -194,7 +241,7 @@ of the messages. tuple Tuple } - type msgResponse struct { + type msgReply struct { tid int pattern Pattern } |