summaryrefslogtreecommitdiff
path: root/proto.pod
diff options
context:
space:
mode:
Diffstat (limited to 'proto.pod')
-rw-r--r--proto.pod135
1 files changed, 91 insertions, 44 deletions
diff --git a/proto.pod b/proto.pod
index 5edbc6f..2917b5f 100644
--- a/proto.pod
+++ b/proto.pod
@@ -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
}