X-Git-Url: http://www.dxcluster.org/gitweb/gitweb.cgi?a=blobdiff_plain;f=techdoc%2Fprotocol.pod;h=5ea94c6642c0ecd73a5977673ff6006fc146e8ac;hb=7ee1dd3cf4163dff242b737c2b5293235a9fa24b;hp=48df580a13413d652098717691a9a90cca54dc37;hpb=815210e176e04f7f87036d2e235fb1cedbb1babb;p=spider.git diff --git a/techdoc/protocol.pod b/techdoc/protocol.pod index 48df580a..5ea94c66 100644 --- a/techdoc/protocol.pod +++ b/techdoc/protocol.pod @@ -1,6 +1,8 @@ =head1 NAME -DXSpiderWeb Orthogonal Communications Protocol +DXSpiderWeb Orthogonal Communications Protocol + +$Revision$ =head1 SYNOPSIS @@ -9,9 +11,18 @@ DXSpiderWeb Orthogonal Communications Protocol =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). @@ -58,7 +69,7 @@ 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 -L fields) down all interfaces showing a route for that +L fields) down some/most/all interfaces showing a route for that direction, it is unlikely that messages will be lost in practice. =head2 Field Description @@ -88,7 +99,7 @@ More detailed descriptions of the fields follow: =over -=item Origin +=item B This is a compulsory field. It is the name of the originating node. The field can contain up to 12 characters in the set [-A-Z0-9_] in @@ -96,16 +107,18 @@ any order. Higher layers may restrict this further. The field must not be changed by any other node. -=item TimeSeq +=item B This is a compulsory field. It is a 10 hexadecimal digit string which -consists of a day no (1-31), seconds within that day (0-86399) [6 -hex digits] that are concatenated with a sequence number (0-65535) -[4 hex digits] making the total of 10. +consists of a day no (1-31), +a flag to indicate NTP syncronisation in use, +seconds within that day (0-86399) [total of 6 hex digits] +that are concatenated with a sequence number (0-65535) +[4 hex digits] making the total of 10 hexadecimal digits. The date portion is constructed as: - my $date = ((gmtime)[3] << 18) | (time % 86400); + my $date = ((((gmtime)[3] < 1) | $ntpflag) < 18) | (time % 86400); The sequence number is simply an unsigned short (or 16 bit) number starting at 0. @@ -113,7 +126,7 @@ starting at 0. Each message originated at this node will increment the sequence number. -=item Hop +=item B This is a compulsory field. It is the number of hops from the originating node. It is incremented immediately on receipt and @@ -127,7 +140,7 @@ Implementations may have an upper limit to this field and may silently drop incoming messages with a L count greater than the limit. -=item FrmUser +=item B This field is optional. It is the identifier of the originating user. If it is missing then the message is @@ -136,7 +149,7 @@ assumed to come from the originating node itself. It can consist of up to 12 characters in the set [-A-Z0-9_] in any order. Higher layers may restrict this further. -=item To +=item B This field is optional. It is a string of up to 12 characters in the set [-A-Z0-9_] in any order. @@ -156,7 +169,7 @@ intervening nodes are free to duplicate the message and send it down more than one, likely looking, interface - depending on any network policies that may pertain. -=item ToUser +=item B This field is optional. It is a string of up to 12 characters in the set [-A-Z0-9_] in any order. Higher layers may restrict @@ -241,11 +254,12 @@ duplicated! =head2 Examples - # on link startup - GB7TLH,3D02350001,0|HELLO + # on link startup from GB7BAA (both sides hello) + GB7TLH,3D02350001,0,GB7BAA|HELLO,Aranea,1.2,24.123 + GB7BAA,3D02355421,1,GB7TLH|HELLO,Aranea,1.1,23.245 - # on user startup - GB7TLH,3D042506F2,0,G1TLH|HELLO + # on user startup to GB7TLH + GB7TLH,3D042506F2,0,G1TLH|HELLO,PClient,1.3 # on user disconnection GB7TLH,3D9534F32D,0,G1TLH|BYE @@ -268,7 +282,7 @@ duplicated! GB7TLH,1512346543,0,G1TLH,GB7DJK,G7BRN|PING,35DE # A possible reply, same ID as ping followed by the no of hops on the - # received ping + # ping that was received GB7DJK,1512450534,3,G7BRN,GB7TLH,G1TLH|PONG,35DE,3 @@ -276,10 +290,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: + + DX + PC23 + ANN + +Invalid tags include: -The L is separated from its data by a comma ','. All fields + 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 ',', @@ -322,27 +358,70 @@ 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 +=head2 Standard Commands -The L consists of string of uppercase letters and digits, starting -with a leading, uppercase, letter. Tags should be as short as is meaningful. +There are a number of L which must be accepted by +all implementations. -Valid tags would be: +=over - DX - PC23 - ANN +=item B -Invalid tags include: + HELLO,,,, - 1AAA - dx - Ann +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. -=head2 Standard Commands +=item B -There are a number of L which must be accepted by -all implementations. + 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 + + 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 + + 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 + + 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 =head1 AUTHOR @@ -355,6 +434,8 @@ Copyright 2004 by Dirk Koopman, G1TLH This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. +$Revision$ + =cut