summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorYorhel <git@yorhel.nl>2012-02-22 11:16:20 +0100
committerYorhel <git@yorhel.nl>2012-02-22 11:16:20 +0100
commit81fc5992111807e84398e49c91fb45216e99df8e (patch)
treeadff3431dcc718f348b1f240503960274868bc7f
parent1f37ca47cab23e9d2382cce1daff296385403b2a (diff)
doc/proto: Changed protocol to fully symmetric + better format selection
-rw-r--r--doc/proto.pod126
1 files changed, 83 insertions, 43 deletions
diff --git a/doc/proto.pod b/doc/proto.pod
index 3cd9611..8cffe57 100644
--- a/doc/proto.pod
+++ b/doc/proto.pod
@@ -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