X-Git-Url: http://www.dxcluster.org/gitweb/gitweb.cgi?a=blobdiff_plain;f=techdoc%2Fprotocol.pod;h=6a56b6389d1e5d680f10c5008a3a2be1ea8a5acf;hb=6c8062c1356fe49974da2df121852b41971f7b77;hp=d429d044eace8e7c4b028c7e0e50389909db619b;hpb=3c74f791e2f4c3e534c837f3a7d5ca596c76a5ee;p=spider.git diff --git a/techdoc/protocol.pod b/techdoc/protocol.pod index d429d044..6a56b638 100644 --- a/techdoc/protocol.pod +++ b/techdoc/protocol.pod @@ -1,6 +1,8 @@ =head1 NAME -DXSpiderWeb Orthogonal Communications Protocol $Revision$ +DXSpiderWeb Orthogonal Communications Protocol + +$Revision$ =head1 SYNOPSIS @@ -9,9 +11,18 @@ DXSpiderWeb Orthogonal Communications Protocol $Revision$ =head1 ABSTRACT For many years DX Clusters have used a protocol which was designed -for a non-looped tree of nodes. This has probably never, reliably, -been achieved in practice; certainly not recently. This document -describes a complete replacement for that protocol. It allows a +for a non-looped tree of nodes. This environment has probably never, reliably, +been achieved in practice; certainly not recently. + +There have always been loops, sometimes bringing the network to its +knees. In modern usage, both in order to get some resilience and also +to expedite information flow, we use internet based, deliberately +looped networks with filtering. Whilst this works, after a fashion, there +are all sorts of problems that the current PC protocol can never +address. + +This document +describes a complete replacement for the PC protocol. It allows a fully looped network, is inherently extensible and should be simple to implement (especially in perl). @@ -20,20 +31,38 @@ for inter-node communications. =head1 DESCRIPTION -This protocol is encoded in UTF8 with HTTP style escaping. It is +This protocol is designed to be an extensible basis for any type of one to many "instant" line-based communications tasks. This protocol is designed to be flood routed in a meshed network in -as efficient a manner as possible. +as efficient a manner as possible. The reason we have chosen this +mechanism is that most L need to be broadcast to all nodes. + +Experience has shown that nodes will appear and (more infrequently) +disappear without much (or any) notice. +Therefore, the constantly changing and uncoordinated +nature of the network doesn't lend itself to fixed routing policies. + +Having said that: directed routing is available where routes have +been learned through past traffic. +Those L that could be routed (mainly single line one to +one "talk" L) +happen sufficiently infrequently that, should they need to be flood routed +(because no route has been learned yet) it is a small cost overall. + +=head1 Messages + +A message is a single line of UTF8 encoded and HTTP escaped text +terminated in the standard internet manner with a . Each message consists of a L and a L. -The two sections are separated with the '|' character and the whole -message is terminated in the standard RFC/Internet manner with the -ascii characters. It follows that these -characters (as well as a small number of other reserved characters) +The two sections are separated with the '|' character. +It follows that these +characters (as well as non-printable characters, , and +a small number of other reserved characters) can only be sent escaped. This is described further in the -L. +L and L. Most of this document is concerned with the L, however some L which all implementation should issue and @@ -47,7 +76,7 @@ effectively a datagram. It is assumed that nodes are connected to each other using a "reliable" streaming protocol such as TCP/IP or -AX25. Having said that: in context, messages in this protocol could be +AX25. Having said that: in context, L in this protocol could be multi/broadcast, either "as is" or wrapped in some other framing protocol. @@ -56,10 +85,10 @@ through your node" protocol, there is no guarantee that a message will get to the other side of a mesh of nodes. There may be a discontinuity either caused by outage or deliberate filtering. -However, as it is envisaged that most messages will be flood routed or, -in the case of directed messages (those that have L and/or +However, as it is envisaged that most L will be flood routed or, +in the case of directed L (those that have L and/or L fields) down some/most/all interfaces showing a route for that -direction, it is unlikely that messages will be lost in practice. +direction, it is unlikely that L will be lost in practice. =head2 Field Description @@ -126,7 +155,7 @@ neighbouring nodes must increment this field before passing it on to higher layers for onward processing. Implementations may have an upper limit to this field and may -silently drop incoming messages with a L count greater than the +silently drop incoming L with a L count greater than the limit. =item B @@ -212,7 +241,7 @@ tuple. The basic system will learn which interfaces can see what nodes by looking at the tuple and merging that with the L count. Each interface remembers the latest L with the lowest L for each L that arrives on that interface. It also remembers -the number of messages for that L that has been received on +the number of L for that L that has been received on that interface. Any message for onward broadcast is duplicated and sent out on all @@ -244,11 +273,11 @@ duplicated! =head2 Examples # on link startup from GB7BAA (both sides hello) - GB7TLH,3D02350001,0,GB7BAA|HELLO,Aranea,bld=24.123 - GB7BAA,3D02355421,1,GB7TLH|HELLO,Aranea,bld=23.245 + GB7TLH,3D02350001,0,GB7BAA|HELLO,Aranea,1.2,24.123 + GB7BAA,3D02355421,1,GB7TLH|HELLO,Aranea,1.1,23.245 # on user startup to GB7TLH - GB7TLH,3D042506F2,0,G1TLH|HELLO,PClient,ver=1.03 + GB7TLH,3D042506F2,0,G1TLH|HELLO,PClient,1.3 # on user disconnection GB7TLH,3D9534F32D,0,G1TLH|BYE @@ -279,10 +308,32 @@ duplicated! The L of the message contains the actual data being passed. It is called the Command Section because all commands -are identified with a L which is implemented by -the software using this protocol. +are identified with a L each of which is implemented by +the software using this protocol. Each (usually) is followed by one +or more L. + +=head2 Tag + +The L consists of string of uppercase letters and digits, starting +with a leading, uppercase, letter. Tags should be as short as is meaningful. + +Valid tags would be: -The L is separated from its data by a comma ','. All fields + DX + PC23 + ANN + +Invalid tags include: + + 1AAA + dx + Ann + +The L is separated from its data L by a comma ','. + +=head2 Fields + +All fields in any subsequent data shall be separated by a comma ','. All fields shall be HTTP encoded such that reserved characters (comma ',', @@ -308,7 +359,7 @@ are written according to this specification must say: use UTF8; A message (or line) is terminated with -0x0d 0x0a. Incoming messages must be accepted even when terminated +0x0d 0x0a. Incoming L must be accepted even when terminated with just . Care must be taken to make sure that fields have any reserved characters @@ -325,23 +376,6 @@ specified above and can otherwise contain any character. There is no maximum size specified for a message. It is up to each implimentation to enforce one (if only for their own protection). -=head2 Tag - -The L consists of string of uppercase letters and digits, starting -with a leading, uppercase, letter. Tags should be as short as is meaningful. - -Valid tags would be: - - DX - PC23 - ANN - -Invalid tags include: - - 1AAA - dx - Ann - =head2 Standard Commands There are a number of L which must be accepted by @@ -351,23 +385,59 @@ all implementations. =item B -Command sent on connection to another node. + HELLO,,,, + +Command sent on connection to another node. Both sides send their information +to the other. All the possible arguments are optional, although some of the +arguments should be sent in order to help diagnose problems. This command is +broadcast. -=item B +=item B -Command sent to voluntarily disconnect a connection. + BYE, + +Command sent to all connections when the software is shutting down. This is sent +by the node just before shutdown occurs. This is really only used to help the +network prune its routing tables. It isn't a requirement. The field +is optional. =item B -Command sent when a node has disconnected from this node. + DISC,, + +Command sent when a node has disconnected from this node. This message is sent when +an interface shuts down. It need not be sent if a L from an interface for +that node has just been received. This command should be broadcast. + +The is mandatory and is the name of the interface that has just +disconnected. =item B -Command to send a ping to a node or user. + PING, + +Command to send a ping to a node or user. This command is used both by the software +and users to determine a) whether a node or user exists and b) how good the path is +between them. + +The is a unique string which is usually the hexadecimal equivalent of an +integer that is incremented every time it is used. But it can be anything that +will identify this ping using the tuple (L,) as unique. =item B -Command to reply to a successful ping + PONG,, + +Command to reply to a ping. This is sent as a reply to an incoming ping command. +The is the one supplied and the is the number of +hops it took for the ping to arrive. + +=item B + + T, + +All implementations must be able to send "text" (encoded as specified in +L). There would be little point in doing all this otherwise! =back