blob: 901967f1541bbcfb9da0c4ee26c092dca4c0a97b [file] [log] [blame]
MG Mud User88f12472016-06-24 23:31:02 +02001CONCEPT
2 intermud.basic
3
4DESCRIPTION
5 Here is how intermud data is sent across the internet - specific
6 for Zebedee Intermud (aka Intermud 2).
7
8ADVANCED 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
16PACKET 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
56PACKET 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
76DEFINED 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
128UDP 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
146AUTHOR
147 Information taken from Outerspaces documentation to be found
148 on http://mud.stack.nl/intermud/
149
150SEE ALSO
151 inetd(C), intermud(C)