From: minima Date: Tue, 11 Jan 2005 17:55:16 +0000 (+0000) Subject: more WIP X-Git-Tag: 1.53~198 X-Git-Url: http://dxcluster.org/gitweb/gitweb.cgi?a=commitdiff_plain;h=0bbec0ad6efa0dabc4ab3cc1a4867b297e651746;p=spider.git more WIP --- diff --git a/techdoc/protocol.pod b/techdoc/protocol.pod index 1a017376..02388d8e 100644 --- a/techdoc/protocol.pod +++ b/techdoc/protocol.pod @@ -7,12 +7,12 @@ $Revision$ =head1 SYNOPSIS - ,,,|,... + ,,,[,]|,... =head1 ABSTRACT For many years DX Clusters have used a protocol which was designed -for a non-looped tree of nodes. This environment has probably never, reliably, +for a non-looped tree ofLs. This environment has probably never, reliably, been achieved in practice; certainly not recently. There have always been loops, sometimes bringing the network to its @@ -33,14 +33,14 @@ for inter-node communications. =head1 DESCRIPTION This protocol is -designed to be an extensible basis for any type of one too many +designed to be an extensible basis for any type of one -> 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. The reason we have chosen this -mechanism is that most L need to be broadcast to all nodes. +mechanism is that most L need to be broadcast to allLs. -Experience has shown that nodes will appear and (more infrequently) +Experience has shown thatLs 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. @@ -72,18 +72,19 @@ must accept are described. =head1 Applications In the past messaging applications such as DX Cluster software have maintained -a fairly strict division between Ls and Ls". This protocol attempts -to get away from that distinction by allowing any entity to connect to any -other. +a fairly strict division between Ls and Ls. This protocol attempts +to get away from that by deliberately blurring (or, in some cases, removing) +any distinction between the two. Applications that use this protocol are essentially all peers and therefore nodes the only real difference between Ls and Ls is that a "node" has one or more listeners running that will, -potentially, allow incoming connections, from other Ls, Ls or Ls +potentially, allow incoming connections from other Ls, Ls or Ls. These +routable entities are called Ls. -Any application that is a sink and/or source of data for Ls, is capable of obeying +Any application that is a sink and/or source of data for Ls; is capable of obeying the protocol message construction rules and understands how to deduplicate incoming messages -correctly can operate as a routeable entity in this protocol. It is called an L. +correctly can operate as a routeable entity or L in this protocol. It is called an L. An L is called a L if it accepts connections from Ls and is prepared to route messages on their behalf to other Ls or L. In addition it @@ -106,7 +107,14 @@ They should be treated as local clients, in fact as Ls, B as peers in this protocol. It is likely that, in order to do this, some extra Ls will need to be defined at application level. -=head1 Connection Types +=head1 Definitions + +In this document we use a number of terms that need to be defined. + +=head2 Terminal + +A L is a routable entity, in other words: a callsign or service that can be routed +to, that lives at one or a few Ls. =head2 User @@ -121,7 +129,7 @@ An L is a connection to a L that uses the protocol. From a rout view, it is indistiguishable from a L. The L is responsible for creating and decoding well formed protocol messages. An L does not route beyond the immediate L(s) to which it is connected. It may also be a L connected to a L which provides some -addressable service that can be queried. +addressable service (such as a database) that can be queried. =head2 Node @@ -130,13 +138,25 @@ from other Ls or Ls, whether directly connected or not. Option may provide other interfaces, such as direct L connections or legacy PC protocol speaking DX Clusters. +=head2 Channel + +A L is a L address that is not a L. It is (unless qualified by a L) +broadcast on all a Ls interfaces unless preventing by some filtering or other local policy on +that L. + +=head2 Service + +A L is application that either plugs into or connects as an L to a L. It is an +application that, in effect, is a database. In other words: queries are sent to the L and it sends +back a reply. + =head1 Routing Section The application that implements this protocol is essentially a line oriented message router. One line equals one message. Each line is effectively a datagram. -It is assumed that nodes are connected to +It is assumed thatLs are connected to each other using a "reliable" streaming protocol such as TCP/IP or AX25. Having said that: in context, L in this protocol could be multi/broadcast, either "as is" or wrapped in some other framing @@ -145,12 +165,11 @@ protocol. Although the physical transport between Ls is reliable, the actual message is unreliable, because this is an unreliable, best effort, "please route my packets 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 +will get to the other side of a mesh of Ls. There may be a discontinuity either caused by outage or deliberate filtering. 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 +in the case of directed L (those that have L that is a callsign down some/most/all interfaces showing a route for that direction, it is unlikely that L will be lost in practice. Assuming that there is a path between all the Ls in a network, then it is guaranteed @@ -161,21 +180,14 @@ using the information in the L. =head2 Field Description -The first four fields in the L are compulsory. However, -a client connection can - -Adding a L and/or L field will restrict the destinations -or recipients that receive this message. +All fields in the L are compulsory except the L field. If it is missing +so is the separating comma. The L field is incremented on receipt of a message on a node. Fields are separated by the comma ',' character with the last field required followed by the vertical bar '|' character. -If trailing fields are missed out then superfluous commas can also -be left out. If intervening fields are missing then no space needs -to be left for the separating comma. - The characters allowed in the routing section are restricted. Any invalid characters in any field will cause the whole message to be silently dropped. @@ -194,29 +206,34 @@ The field must not be changed by any other node. =item B -This is the Group (or Channel) to be used for this data. It is compulsory. There -is always a L +This is the Group (or Channel) to be used for this data. It is compulsory. It is a string of up to 12 characters -in the set [-A-Z0-9_] in any order. Optionally, for extra routing to -a specific end point (node or user), it may have another 12 character -field in the same set, concatenated with the string, separated by a ':' -character. - -This field is used either to indicate particular node destination -or to differentiate this broadcast in some way by making this -message as a member of a L. Any message can be sent -down any L. The names of Ls and their usage -is entirely up to the implementor. - -It is assumed that node names can be differentiated from user -names and L names. - -If the field is set to a particular node destination, it will -be routed (rather than broadcast) to that node. However, any -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. +in the set [-A-Z0-9_/] in any order. + +Optionally, for extra routing to +a particular L connected at a specific L, or even a +particular L in a L, +it may have another 12 character +string in the same set, concatenated with the first string. The two strings are separated by a ':' +character. For example: + + DX # the DX group + GB7DJK # the node GB7DJK + G1TLH # the user or endpoint G1TLH + GB7DJK:G1TLH # the user G1TLH at GB7DJK + DX:G1TLH # the user G1TLH in the DX group + +This field can contain either a L or some other string which is interpreted +as broadcastable group address. Any message that has a L that is not recognised as a L must +be broadcast. + +This means that messages to callsigns, for whom no specific routing information is available, +will be found by means of a broadcast. Hopefully this will cause some kind of activity o.b.o +that callsign will allow routing tables to be gathered that narrow down the scope of any future +message to that callsign through the network. + +Remember that not all Ls may pass every L field, depending on local policy. =item B @@ -251,7 +268,11 @@ Implementations may have an upper limit to this field and may silently drop incoming L with a L count greater than the limit. +=item B +The L field is optional. When present, it represents a L at +the originating L. If it is missing then either it is not relevant or it +is assumed to be the L. =back @@ -311,21 +332,21 @@ duplicated! # a talk (actually 'text') message to a user (some distance away # from the origin node) - GB7TLH,G8TIC,3D03450019,3|T,G1TLH,Hiya Mike what's happening? + GB7TLH,G8TIC,3D03450019,3,G1TLH|THiya Mike what's happening? # a talk/chat/text message to a Group - GB7TLH,VHF,0413525F23,2|T,G1TLH,2m is opening on MS + GB7TLH,VHF,0413525F23,2,G1TLH|T,2m is opening on MS # a ping to find the whereabouts and distance of a user from a node # the hex number on the end is the ping ID - GB7TLH,G7BRN,1512346543,0|PING,G1TLH,9F4D + GB7TLH,G7BRN,1512346543,0,G1TLH|PING,9F4D # this effectively asks whether the user is on-line on a particular node - GB7TLH,GB7BAA:G7BRN,1512346543,0|PING,G1TLH,35DE + GB7TLH,GB7BAA:G7BRN,1512346543,0,G1TLH|PING,35DE # A possible reply, same ID as ping followed by the no of hops on the # ping that was received thus telling you how far away it is. - GB7BAA,G1TLH,1512450534,3|PONG,G7BRN,35DE,3 + GB7BAA,G1TLH,1512450534,3,G7BRN|PONG,35DE,3 =head1 Command Section