# Yet Another InterMUD Communications specification draft version 1
# YAIMC draft version 1: A Candidate for IMC3 by Jeffrey Basurto
##############################################################################

A OVERVIEW
B IMPLEMENTATION
C PACKETS
D CLIENT SCHEDULE
E FUTURE
F NOTES

##############################################################################

OVERVIEW

The main goals for the project are three fold.
1. A smart, simple, more elegant design which makes the construction of new client technology easier, installing those clients into existing projects a much shorter and painfree experience, and ultimately a good platform for future expansions of functionality.

2. Upgrade of existing software technology to make error checking more strict and responsive. Eg, reporting specific errors to clients for packets, and perhaps more importantly–Ensuring incorrectly formatted packets are indeed detected.

3. Simplify packets and reducing bandwidth on every party, client and server, by a target of 50-60%.

What this project is not.
1. A massive expansion of functionality.
2. A massive change in convention from the user (client) perspective.

IMPLEMENTATION

Everything discussed here already has a working prototype.

Connections from clients(MUD) to server(IMC3) will be made using a TCP socket connection. Data can be sent as either plain-text or compressed format. The initial handshake will always be in plain text—at this point the client may agree to use compression and this will be honored by the server. The only data relayed should be properly formatted packets as defined below. It's also important to mention that data will be uniform.

A packet must contain a packet specifier followed by a variable list of options and delimited with \0, or a null character. The server will ensure the required options for any packet are included. The order is not important. It is up to the client to effectively know and include the required data. Because of the format it will be easy to define tables to streamline the process. This is how the server does it. More information on the exact syntax will be made
below.

packet_specifier  Option1="option1 data" Option2="option2 data" …

The required and optional fields are formatted the same way and can be in any order. Example:

packet_specifier  Reqopt1="req option" Optional="Not required"  Reqopt2="Req"
packet_specifier  Optional="Not required"  Required="required"

As long as the required options are included in any order, the packet is valid. Most optional data is valid for all packets. Such as Echo="yes" to tell the server you want confirmation. A successful packet otherwise operates as expected without any confirmation. An example is made in the packet documentation below for packet_validate.

PACKETS

Currently the only packets are defined in the candidate version:
packet_error, packet_validate, packet_chat, packet_tell

In IMC3 packets are reflective. Any packet that can be sent to the server can be also expected to be sent to a client potentially. Although the expected functionality changes.

1. packet_error
Purpose: To relay an error to the client or server.
The first and bottom level packet is packet_error. Typically it is sent by the server (or client) when an error was raised in a previous packet.

Examples:

>some_packet meh
packet_error Error="Packet malformed." Data="some_packet meh"
>some_packet Meh="correct format but mud not yet validated'
packet_error Error="MUD not yet validated." Data="some_packet [snip]"
>packet_validate Mud="Account name" Password="somepass123"

Which brings us to packet_validate.

2. packet_validate
Purpose: To login to the network and gain access to other packets.
Required fields: Mud, Password
Optional fields: Version="3", Echo="no", Compress="yes"

The first packet must be the validation packet. Any other packet will result in a rejection. The proper format for a validation packet follows:

>packet_validate Mud="Account name" Password="somepass123"

Nothing echos on success by default. (Although an error packet will result from malformed or erroneous data.

Example using optional Echo.

>packet_validate Mud="Account name" Password="somepass123" Echo="yes"
packet_validate Success="yes"

Or to request plain text:

>packet_validate Mud="Account name" Password="somepass123" Compress="yes"

3. packet_chat
Purpose: To send a global chat message to a specified channel.
Required fields: Sender, Text, Channel
Optional fields: Echo="yes", Mud="Registered MUD"

Proper format for chat packet:

>packet_chat Sender="Retnur" Text="Hello world" Channel="ichat"
>packet_chat Sender="Retnur" Text="Hello world" Channel="icode"

When received by client:

>packet_chat Sender="Retnur@Feltain2" Text="Hello World" Channel="ichat"

4. packet_tell
Purpose: To send a private message to one or more people.
Required fields: Sender, Targets, Text
Optional fields: Echo="yes", Mud="Registered MUD"

>packet_tell Sender="Retnur" Text="Hello, guys."  Targets="davidhaley,kayle@MW"
>packet_tell Sender="Retnur" Text="Hey." Targets="davion@ADP samson@alsherok"
>packet_tell Sender="Retnur" Text="Mew"  Targets="davion samson kayle"

When received by client:

>packet_tell Sender="Retnur@Feltain2", Text="Hello, guys." Targets="DavidHaley@MW Kayle@MW"

In the first two examples you may specify targets if you wish. In the third example the server will be able to determine the destined MUD.

CLIENT SCHEDULE

No standalone client will be required for any purpose other than perhaps testing technology before installing it. Connecting directly to the server through any standard telnet/mud client will be possible. (Similar to Talon but built-in, not relayed.)

Currently a C, C++, Java, Python and Ruby client all have alpha versions scheduled to be complete with the server technology. These clients will have no particular codebase in mind. Although independant developers are welcome to make a client in whatever language they wish, we hope there will be largely no reason to in most cases. We hope some codebase standard releases will be made integrating these clients.

FUTURE

These initial packets only represent a hand full that will be complete for an adoption version.

NOTES

In most cases the server can receive multiple formats for any given thing, however, clients can expect a consistant format. Example:
Server can receive a field as:

Data=meh or Data="Meh" or Data='meh'

But the client can always expect an uniform:

Data="Meh"

Optional fields default differently depending on the packet in question.
For fields that require a yes or no answer it is also valid to answer with:
yes or no
true or false
1 or 0

Currently all fields allow multiple words (but must be encased in quotes). Limitations will be defined at the time of implementation. For example, a password may be limited to certain characters. A mud name may or may not be allowed to have spaces and certain characters may be disallowed from any given field.

I've been working closely with Runter on designing this updated version of the protocol, with the hopes of updating the MudBytes IMC2 Network to use this new simple, flexible protocol. Any input is welcome, and in fact, highly encouraged, since the project is still in it's infancy.

Should this be accepted as an update to the MudBytes network, There will be a protocol translation layer to translate packets from the existing clients into the new format, at the very least for a while. Should the new protocol catch on widely because of it's ease of use, the translation layer may be slowly phased out.

Obviously, I'm all in favor of this revision, but I look forward to hearing everyone else's thoughts on the subject.

Ok. While an updated protocol is probably not a completely horrid idea, what's been displayed here is barely enough to go on.

You've basically outlined chat, tell, and validate. There's no mention of just how the client is supposed to know about channels, other clients, etc. and that seems rather important as the clients need some way to know what channels exist, what other clients exist, and that sort of thing.

There should also at the very least be suitable replacements for who, chanlist, info, and locate packets.

And a point I will stress highly. There should be no forceful effort made to badger people into upgrading. Folks right now on the network all have clients that work. There is no particularly good reason any of them should be told they have to update or risk losing the connection at some undetermined date in the future. Plenty of people have other things they'd rather spend their development time worrying about than integrating some new chat protocol to replace the one they have that "just works".

I appreciate the input but I'm not sure if this is constructive criticism. I'll attempt to address your concerns, in any event.



It was suggested we make this project more public going forward. This specification is nowhere near complete.


All I can say is that those things while neglected to be mentioned in the passage will not be neglected in the final product. And they'll be built within the structure of this very alpha documentation for what is already working software. The debate on the table is ideas/suggestions and feedback going forward.


There will be. Again, within the structure already outlined above.



Sure. And it's a legitimate point, but nobody is suggesting we force anyone to upgrade at this point. There are plenty of options on the table for retrospective compatibility as well as tethering of the existing IMC2 server. It's really a nonissue if the project is adopted.

Ok I donno if this idea sounds good, or if its something people would even consider. But would it be a bad idea to be able to have two clients have the ability to connect to each other, and not just directly to a server/hub. So say… I want communication from my dev port and main port but the server is down, I could then just manually connect the two clients together form a short kinda server of some sort. Again this prolly is just more based the user itself of client but thought I might through it out there as something to show an example of or something.

The number one thing that would make it interesting to me, would be if it were ALSO useful as a candidate for an "I4" network. The I3 networks and the IMC2 networks have been stupidly insular for far too many years. It's fine if the personalities who run them want to keep distinct segments that don't talk to each other, but you guys really should work together on a common protocol so there's at least a chance of bringing the same features and code to all mud codebases.

The separation don't make a lick of sense to me neither.

Honestly though, the protocol isn't the issue there.

I wrote a translation module so that someone on a Diku can show up on i3
and give me a hard time, and indeed I think you've connected (waitin on the
hasslin tho) as has our pal Fury. I'm very familiar with both the i3 and imc2
protocols and would be positively delighted to code a module to join the
imc2/imc3 and i3 servers as peers.

In my opinion, though, this is a completely separate problem to solve than
fixing the weaknesses of imc2. I fully agree with unification. I am wary of
throwing it into this discussion as a potential distraction and excuse to
object to imc3.

-Crat
http://lpmuds.net

The point is, though, right now there are two distinct protocols that act to divide the mudding community into two camps, as it were. The "LpMUD" camp is more-or-less forced onto the I3 network, because support for IMC2 isn't widely available. I know there IS an imc client in lpc, but have no idea if it works. Likewise, the "Diku" camp is mostly forced onto the IMC2 network, because the various I3 modules have been abandoned.

Having translation servers is fine, but it adds another confusing variable to the mix. I have indeed added the IMC2 "freedom" client to my own Diku, and used it to connect to the I3 network via your bridge. It works, more or less, but I can tell that I'm only getting half the data I'd get on a native IMC network, or with a native I3 implementation, because the various info fields aren't compatible. So, I get empty fields and incomplete data.

That's why I suggest inviting you and the other folk who are working with the current I3 network to take part in helping design the protocol. If it's done right, both camps can end up using the same protocol and the same code (albeit in different languages). If everyone still wants to keep their networks "pure", that's fine, but at least someone setting up a new MUD of *ANY* kind is free to choose the network because of who they want to talk to, not because one works better than the other.

That's all I'm saying.

Works fine, but Davion keeps changing ip's!




That is a good idea. I am good and do some of the heavy lifting
with i3, but Aidil is smarter than me. I think he's important
to bring in for what you say. Maybe one of these days when you're
kibitzing over DGD you can nudge him over this way.

Absent that, I'm happy to chime in, but I am concerned that my
history with some of the parties involved would prove more of
an obstacle than a help.

I suppose it could be worse. It could be scandum's protocol!

Anyway, I get the drift about interoperability and in that
vein I'd suggest a few things to consider for imc3:

* A standardized format for a who list that is an array of names
and associated information about each name.

* A standard for muds to connect directly to each other after
authenticating over the server (for more private tells and email).

* NOT specifying a markup for color, but rather encouraging muds
to use the ANSI codes if they really need to send color.

* NOT having a limited number of slots for connections. This is
a vector for denial of service.

* Allowing muds to create their own channels, and set their policies.

* Allowing spaces in mud names.

* A message-of-the-day packet, to have a formal standard for
things like migration and downtime notices.

* interslay. nuf said.

If you're curious about the standard packets used by i3, they
are described here: http://mud.stack.nl/intermud/intermud3.h...

-Crat
http://lpmuds.net

Some random thoughts…

- Reducing bandwidth. This seems incompatible with the apparent goal of making packets human readable. I don't see much need for making packets human readable; although it makes it (only a little) easier to debug, it increases the payload of every message considerably.

- Compression. I would do this using plain old MCCP. We know it works, and it's a process that can be initiated or stopped at any point in time.

- Variable length packets. Sometimes good, sometimes bad. Unless there's a compelling use-case for them, I would go without. They only add complexity, and make it harder to make short packets.

- Packet format. I would argue that packets should be of the format:
<type> <delimiter> <arg1> <delimiter> <arg2> …
where type is a packet type number, delimiter is something like a NUL, and args depend on the packet. The delimiter would have to be escaped using some well-known convention if it appears anywhere in the packet text.
Do *not* make whitespace significant: only the delimiter should matter.

- Color codes. There should be a very well-defined standard for color codes in IMC packets, that clients can translate to their own color codes if they wish to do so. There should be a well-known convention for escaping color codes in messages. This standard for color codes could simply be ANSI as Crat said.

- More packet types vs. packet options. Instead of a chat message with an "emote" flag, have an emote packet type. This makes it easier to switch on packet type and drop straight into the proper processing function, and furthermore makes it easier to add more things since you don't have to worry about flag options changing etc.

- Socials vs. emotes. Drop any kind of explicit social support, make everything emotes.

- Channels. As others have said, allow creation of channels on the fly, as with IRC for example. The server can specify predefined channels if it chooses to do so. Network admins can override custom created channel policies if necessary.

- Do not distinguish between packet format for clients and servers. Everybody sends packets the same way. Do *not* allow clients to be sloppy in how they talk to the server. There is a convention, and Thou Shalt Use It.



That's probably it for now… need to go to lunch. :wink:

Keep in mind this protocol is based strongly on the existing IMC2 format—and that's what we're upgrading.


This is certainly up for debate, and I don't necessarily care one way or the other. As it stands, it's really just cleaning up and following the current convention of IMC2. I disagree that it is incompatible with the goals. The way described indeed uses less bandwidth than IMC2. Not less bandwidth than solution X which DH describes above.


Fair enough, but I don't see why that's simpler than just compressing with zlib everything sent. I also don't see a reason for being able to toggling it on and off. Maybe you do?


If it wasn't verbose I don't see how a single field packet would be harder to make a short packet. I'd argue in situations they can make packets shorter.

I think your assertion that making white space significant is some kind of epic deal breaker is silly. It's actually a pretty trivial difference.


I agree with Crat about the ANSI codes. I have found little reason not to use them other than some claims of people not supporting ANSI colors. (Doesn't that mean they can just use the translation layer like is already being proposed and used in IMC2?)


I agree.


I agree.


Definitely agree.


Maybe you can give a convincing reason why clients shouldn't be able to send packets to the server in the easiest way for them if the server can easily support multiple formats.

This isn't a discussion of unification. If we'd like to open discussions on unification, let's do it in a separate thread, Runter and I are looking strictly for input on the protocol itself, not the existing networks.

Well, hopefully I'm not one of said parties. I think we've had disagreements in the past but I have a healthy amount of respect for your opinions. Also I don't think we're on bad terms.


I agree. Other than some artsy deal I don't see a reason why every mud should implement the way you view who lists. The same way someone else doesn't implement the colors you want to use for chat channels, etc.


This is something on the table for me personally. It really depends on how many people see a need for this and what Kayle and others have to say about it.


I see no reason not to. Others have attempted to make an argument against it but I haven't seen any that hold water, really.


Not really sure what you mean. IMC2 has a limited number of slots for connections?


Yes. No reason not to.


I agree with this.


Sure. Sounds like a good idea.

The protocol is already breaking compatibility, so there's not much reason to do things like IMC2 just because that's how IMC2 does it. If we can improve something, we should do so; if we can improve it even more, why not do that too? Why stop at a small improvement when we can make a larger one?

This isn't really an "upgrade" of IMC2 in the sense that it will be backwards compatible. It really is a different protocol as given, so changing the basic rules is fair game.

I don't see a reason to toggle it on and off, but I do see a reason to use a well-established protocol-level negotiation rather than tack on yet another handshake layer.

Not sure I follow what you're saying.

I didn't say that it was an "epic deal breaker"…
If you start saying that spaces are a separator, you'll end up with problems like one space vs. two spaces, etc. The information is not meant for human consumption, so build it to be absolutely clear and unambiguous. It's not trivial at all: one has very clear rules to follow, and the other introduces ambiguity.

Of course, if your delimiter were specified as a single space instead of a NUL, that would be fine too. The point would be that it's not whitespace separated, but separated by character 0x20 instead of 0x00.

It makes a mess: it's more stuff to support, it's more stuff to parse, it's more code to parse stuff. It introduces complexity for basically no client-side benefit: I can turn around your question and ask why it's easier to send single vs. double quotes vs. no quotes at all? What are the rules of not using quotation marks, but using spaces in your text?

Basically any added complexity must be very strongly justified, especially if the overarching goal is to simply things.

It is far simpler to have a single, unambiguous rule for packets. Again, the protocol is for machine consumption.

While it is generally a network programming adage to be liberal in what you accept and strict in what you send, that's no excuse to build laxness and sloppiness into the protocol itself.

Yes. There's some issue where the server only accepts so many connections, and those get reserved even if the MUD is offline. Recently that number has had to be bumped up a few times. It's a little unnecessary.

Well, I consider a lot of the role of the server to do things that all clients shouldn't need to do. The clients themselves may lack the ability to connect straight to each other in this way at the end of the day. That being said, it may be easy enough for you to make your own private channel for your muds and it would seem localized to your two ports.

If they're on the same machine he can just use the mudmsg snippet in the repository that allows communication between two ports on the same machine. Not the most elegant solution, but it works fairly well I've found.

The point is you can't use the single word without quotes if there is space in your data. (Some of the diku functions do that by default. Only add quotes if it is required.) I disagree with most of what was said but I'm not going to derail the thread on this point. The fact of the matter is if you are writing the client for the protocol there is no added complexity for any other author by allowing one author to have a space and another not to. If the server handles it all gracefully there is no issue.

I think it's safe to say we'll lift this restriction.

I cannot express my objection more strongly; I think it is a very, very bad idea to introduce sloppiness into the protocol and for whatever it's worth I would never back a protocol that did so. From experience with protocols in general, it's just a terrible idea and adds far less benefit than you seem to think it does.