diff options
-rw-r--r-- | proto.pod | 126 |
1 files changed, 83 insertions, 43 deletions
@@ -4,33 +4,24 @@ 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. - +TCP. The protocol makes no distinction between the side that connects and the +side that is connected to - both sides initiate communication simultaneusly +once the connection has been established. =head1 Handshake -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 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. +After the connection has been established, both sides immediately send a +handshake 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 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. +The following is an example handshake. - listen: ver,1,0 ser,json,gob - connect: ver,1.0 ser,json + A: ver,1,0 seri,gob,json sero,gob,json + B: ver,1.0 seri,storable,json sero,storable,json Currently defined parameters are: @@ -41,25 +32,71 @@ Currently defined parameters are: 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. - -This document describes protocol version C<1.0>, which is currently the only -version available. - -=item ser - -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. +whereas major version changes indicate incompatibilities. If a side supports +multiple major versions, it can list these in the same ver parameter by +separating them with a comma. Since minor releases are always +backward-compatible, only the highest supported minor version has to be listed. + +After both sides have received the others' handshake, the highest supported +version that both support will be used for further communication. If there is +no common major version supported by both ends, then the connection should be +closed. Examples: + + A: ver,1.0,2.4 + B: ver,1.3,2.2 + # Used protocol: 2.2 + + A: ver,1.0 + B: ver,1.2,2.0 + # Used protocol: 1.0 + + A: ver,1.5 + B: ver,2.1 + # No common major version, disconnect + +This document describes protocol version C<1.0>, which is the only version +available as of writing this document. + +=item seri and sero + +Supported serialization formats for incoming messages (I<seri>) and outgoing +messages (I<sero>). Multiple serialization formats may be delimited with a +comma. The I<seri> list should be ordered so that the most preferable format is +listed first and the least preferable format last. What is "preferable" is +defined by the implementation or even by each application individually. The +order of the I<sero> list does not matter. The serialization formats are +defined later in this document. + +Each side chooses which format to use for encoding outgoing messages by +comparing its own I<sero> list with the I<seri> list of the other. The first +format found in the others' I<seri> list that also appears in its own I<sero> +list is used. + +Similarly, each side chooses which format to use for decoding incoming messages +by comparing its own I<seri> list with the I<sero> list of the other. The first +format found in its own I<seri> that also appears in the others' I<sero> list +is used. + +This ensures that the format used for encoding outgoing messages on one side is +the same as the format used to decode incoming messages on the other side and +vice versa. This also allows implementations to support a different list of +input and output serialization formats. If there are no common formats for +either incoming or outgoing messages, then the handshake will fail and the +connection is closed. Examples: + + A: seri,gob,json sero,gob,json + B: seri,storable,json sero,storable,json + # B will write json messages to A + # A will write json messages to B + + A: seri,json sero,storable,json + B: seri,storable sero,storable,json + # A will write storable messages to B + # B will write json messages to A + + A: seri,gob sero,gob + B: seri,json sero,gob + # No common format for messages from A to B, disconnect =back @@ -69,10 +106,9 @@ reply (e.g. C<ser,json>). Accepted serialization formats are defined below. =head1 Messages -After the handshake, messages are exchanged asynchronously. There is no -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. +After the handshake, messages are exchanged asynchronously. The message format +described here is purely conceptual, see the serialization formats below for +actual encoding of these messages. =head2 Pattern synchronisation @@ -228,6 +264,10 @@ Message type 7. Second element is the $tid, encoded as a number. =back +=head2 Storable + +I<TODO> + =head2 Gob |