MG Mud User | 88f1247 | 2016-06-24 23:31:02 +0200 | [diff] [blame^] | 1 | CONCEPT |
| 2 | intermud.basic |
| 3 | |
| 4 | DESCRIPTION |
| 5 | Here is how intermud data is sent across the internet - specific |
| 6 | for Zebedee Intermud (aka Intermud 2). |
| 7 | |
| 8 | ADVANCED PROTOCOL |
| 9 | This file was originally written as a brief outline of the intermud |
| 10 | protocol for use by developers interested in incorperating similar, |
| 11 | compatible intermud protocols into their own mud systems. It is |
| 12 | included here as it provides a much more detailed description of the |
| 13 | intermud protocol than that provided by the original PROTOCOL file, |
| 14 | and hence may be of use to LpMud developers. |
| 15 | |
| 16 | PACKET PROTOCOL / FORMAT |
| 17 | All information is transferred as a string via a UDP port (each mud |
| 18 | has 1 send and 1 receive port). This kindof transfer is inherently |
| 19 | unreliable, but it's fast and doesn't use up file descriptors. |
| 20 | The format of the strings (packets) is as follows: |
| 21 | |
| 22 | header1:body1|headerN:bodyN|DATA:body-data |
| 23 | |
| 24 | In other words, a header name, followed by a : and then the data |
| 25 | associated with this header. Each header/body pair is separated by |
| 26 | the | character. This means that headers and their body cannot |
| 27 | contain the | character. You should check for this in outgoing |
| 28 | packets to aviod decoding errors at the recieving end. The exception |
| 29 | to this is the DATA field. If it is present, it is ALWAYS positioned |
| 30 | at the end of the packet. Once a DATA header is found, everything |
| 31 | following it is interpreted as the body of the DATA field. This |
| 32 | means it can contain special characters without error and it is |
| 33 | used to carry the main body or data of all packets. |
| 34 | |
| 35 | By convention, predefined system fields will use capital letters for |
| 36 | field headers and custom headers used by specific applications will |
| 37 | use lowercase names to avoid clashes. The defined system fields are |
| 38 | generally refered to by a set of macros which are defined in a |
| 39 | common header file for clarity. |
| 40 | |
| 41 | There is one exception to this header format; If the data is too |
| 42 | large to be transmitted in one single packet, it will be split into |
| 43 | packets of convenient size, each with a special unique packet header |
| 44 | to enable them to be reassembled at the receiving end. These |
| 45 | headers are of the format: |
| 46 | |
| 47 | PKT:mudname:packet-id:packet-number/total-packets|rest-of-packet |
| 48 | |
| 49 | In this case, the mudname and packet-id combine to form a unique id |
| 50 | for the packet. The packet-number and total-packets information is |
| 51 | used to determine when all buffered packets have been received. The |
| 52 | rest-of-packet part is not parsed, but is stored while the receiver |
| 53 | awaits the other parts of the packet. When/if all parts have been |
| 54 | received they are concatenated and decoded as a normal packet. |
| 55 | |
| 56 | PACKET ENCODING / DECODING |
| 57 | Only 2 generic data types are fully suported within the inetd code |
| 58 | itself (namely strings and integers), though others can easily be |
| 59 | used by converting them to one of the supported data types before |
| 60 | transfer and converting back again in receipt. The LpMud "object" |
| 61 | data type is converted to a string automatically by the inetd on |
| 62 | encoding, but no such conversion is carried out on decoding. |
| 63 | |
| 64 | On encoding integers are simply converted to a corresponding string. |
| 65 | Strings are left untouched as long as there is no ambiguity as to |
| 66 | wether they should be decoded as a string or an integer. In this |
| 67 | case of ambiguity, the string is prepended with a $ character. If |
| 68 | the first character of a string is the $ character, it is escaped |
| 69 | by prepending another $ character. On decoding, any string with a $ |
| 70 | as its first character will have it removed and will then be treated |
| 71 | as a string. Any remaining strings that can be converted to an |
| 72 | integer and then back to a string with no loss of information are |
| 73 | considered to be integers. Any remaining strings are treated as |
| 74 | such and are left unaltered. |
| 75 | |
| 76 | DEFINED SYSTEM HEADERS |
| 77 | "RCPNT" (RECIPIENT) |
| 78 | The body of this field should contiain the recipient the message |
| 79 | is to be sent to if applicable. |
| 80 | "REQ" (REQUEST) |
| 81 | The name of the intermud request that is being made of the |
| 82 | receiving mud. Standard requests that should be supported by |
| 83 | all systems are "ping" (PING), "query" (QUERY), and "reply" |
| 84 | (REPLY). The PING request is used to determine wether or not a |
| 85 | mud is active. The QUERY request is used to query a remote mud |
| 86 | for information about itself (look at the udp/query module for |
| 87 | details of what information can be requested). The REPLY request |
| 88 | is special in that it is the request name used for all replies |
| 89 | made to by mud B to an initial request made by a mud A. It is |
| 90 | mud A's responsibility to keep track of the original request |
| 91 | type so that the reply can be handled appropriately. |
| 92 | "SND" (SENDER) |
| 93 | The name of the person or object which sent the request or to |
| 94 | whom replies should be directed. This is essential if a reply |
| 95 | is expected. |
| 96 | "DATA" (DATA) |
| 97 | This field should contain the main body of any packet. It is |
| 98 | the only field that can contain special delimiting characters |
| 99 | without error. |
| 100 | |
| 101 | The following headers are used internally by the inetd and should |
| 102 | not be used by external objects: |
| 103 | "HST" (HOST) |
| 104 | The IP address of the host from which a request was received. |
| 105 | This is set by the receiving mud and is not contained in |
| 106 | outgoing packets. |
| 107 | "ID" (ID) |
| 108 | The packet id. This field is simply an integer which is set by |
| 109 | the sending inetd. The number is incremented each time a packet |
| 110 | is sent (zero is never used). This field is only needed if a |
| 111 | reply is expected. REPLY packets _must_ include the original |
| 112 | request id. This is _not_ done by the inetd. |
| 113 | "NAME" (NAME) |
| 114 | The name of the local mud. Used for security checking and to |
| 115 | update host list information. |
| 116 | "PKT" (PACKET) |
| 117 | A special header reserved for packets which have been split. |
| 118 | See PACKET PROTOCOL / FORMAT. |
| 119 | "UDP" (UDP_PORT) |
| 120 | The UDP port the local mud is receiving on. Used for security |
| 121 | checking and updating host list information. |
| 122 | "SYS" (SYSTEM) |
| 123 | Contains special system flags. The only system flag used at |
| 124 | present is TIME_OUT. This is included in packets returned due |
| 125 | to an expected reply timing out to differentiate it from an |
| 126 | actual reply. |
| 127 | |
| 128 | UDP REQUESTS / MODULES |
| 129 | The following are standard request types that must be supported |
| 130 | by all systems: |
| 131 | "ping" (PING) |
| 132 | This module should return a REPLY packet that contains the |
| 133 | original requests ID in it's ID field and the SENDER in it's |
| 134 | RECIPIENT field. It should also include an appropriate string |
| 135 | in the DATA field, eg. "Mud-Name is alive.\n" |
| 136 | "query" (QUERY) |
| 137 | This module expects the type of query requested to appear in the |
| 138 | recieved DATA field. It should return a REPLY packet containing |
| 139 | the original ID in the ID field, the SENDER in it's RECIPIENT |
| 140 | field, and the query type in a QUERY field. The DATA field should |
| 141 | contain the information requested. |
| 142 | |
| 143 | For details of how other intermud requests operate, look at the |
| 144 | relevant module code. |
| 145 | |
| 146 | AUTHOR |
| 147 | Information taken from Outerspaces documentation to be found |
| 148 | on http://mud.stack.nl/intermud/ |
| 149 | |
| 150 | SEE ALSO |
| 151 | inetd(C), intermud(C) |