computing : games & art : research


Image: W18N70

Mitsubachi is a tiny and open chat protocol, designed to be minimal, easy to implement, easy to use and easy to understand. Mitsubachi supports nicknames, nickname changing, user-to-user messaging and channel / group (known in Mitsubachi as "distribution lists") chat.

{{p I designed the Mitsubachi protocol because I found that most common, open chat protocols (IRC, XMPP, etc.) are to complex too implement properly and completely. Writing a very bare-bones IRC client is easy, but implementing the whole protocol is not. XMPP messages are way to heavy to be reliable on high-latency, low-bandwidth networks. The protocol is also very complex for an amateur, casual client / server writer to implement. Mitsubachi aims to address all these issues.

protocol tl;dr.

Connection is done via plain sockets on TCP port 7107.

Messages between client and server are divided in 5 sections separated by a single space.

Messages end with a \n character.

Mitsubachi Message Format
Command Sender Recipient Extra-Data Content
4 chars 1 to 32 chars 1 to 32 chars >1 chars >1 chars

All clients and lists have a nick that identifies them. Nicks are unique.

Lists also have nicks, but list nicks begin with the character !.

Clients may join and leave lists. Messages sent to a client are delivered to that client. Messages sent to lists are sent to every client on that list.

When a client joins a list that doesn't exist, it is created and the client is added to it.

Below is a list of valid commands. These commands can both be sent to a Mitsubachi server or be received by a Mitsubachi client:
Command Action
NICK <nick> # # #\n Used to change your nick
JOIN # <list-nick> # #\n Used to join a list
LEAV # <list-nick> # #\n Used to leave a list
MESG <sender-nick> <recipient-nick> # <message>\n Used to send an actual message to a nick
EXIT # # # #\n Used to close the connection, usually sent by clients only
OOPS # # <error-code> #\n Used to tell a client the result of an operation (sent by servers)
INFO # # # <error-code>\n Used by servers to send text messages to clients
Notice in the table above how every command has the five sections stated in the previous table. # means the literal character #. This character (or any other character really, as it should be ignored) is used to fulfill the character requirement of at least one character of unused sections.

Error codes: A server should reply 000 ("ok") when a client changes their nick successfully. Otherwise it should reply 001 ("nick already in use") or 002 ("invalid nick", for nicks beginning in ! for users). 003 should be sent when trying to join an invalid list (using a client nick). 005 should be sent when a client tries to send a message to a list they are not a member of. 006 should be sent when an invalid command is received by the server. 007 should be sent to clients that have not chosen a nick when the server has received a command from them other than NICK.

protocol details.

By default and standard, Mitsubachi servers listen for connections on TCP port 7107. Clients (users) connect to a server by plain socket connection.

Exchange between server and client is handled via messages. A message is a string sent from a client to the server or from the server to a client. Messages have a maximum length of 1024 bytes (1024 characters), are divided in 5 sections and follow the format:

command sender recipient extradata content\n

Note the \n at the end. This character is used to delimit the end of the message and thus cannot be used anywhere else in the message.

Each section of a message represents a different type of information:

When a section is supposed to be empty (for example, when sending a message to the server that has no recipient) it must be filled with a single character, usually #.

The minimum length of any message is 13: XXXX # # # #\n.

Nicks identify users. Each user has a nick (or nickname) and no two users can have the same nickname. When a user disconnects from the server, their nickname becomes available to be used by other user. Nicknames have a minimum length of 1 character and a maximum length of 32 characters. Nicknames that start with the character ! identify lists. As such, user nicknames cannot contain this character in the first position. Nicks can contain any character except spaces.

Lists are lists of users. They have a nickname just like any other user, but messages sent to a list are sent to every member of the list. In order to be able to send a message to a list, a client must be part of said list (otherwise error message 005 ("you are not a member of this list") should be sent to the client). When a message is sent to a list, it is broadcast to every member of the list except the one who sent the message. Users may join and leave lists at any time. When a client tries to join a non-existant list, it is created.

All this said, the following messages are valid Mitsubachi messages:

In order to request any command to a server, clients must first have chosen a nick (by issuing a NICK message). Should they try to send any other message to the server other than a NICK command, the server should reply OOPS # # 007 #\n ("please log in").

Should a message not in the list above be received by a server, it should reply OOPS # # 006 #\n ("unknown command").


A Mitsubachi Server written in LDPL is uploaded here. You are allowed to use and modify it in any way you see fit. You are encouraged to host your own Mitsubachi servers! In order to build and run this server implementation you must run the following commands:

ldpl mitsubachi-server.ldpl -o=mitsubachi-server

This server implementation requires the LDPL Net Server and the text package from the LDPL Standard Library.

If at the time of reading the LDPL Library Library is still available, you can install both libraries by running:

lpm install ldpl_net_server lpm install std-text


The Mitsubachi protocol is released under the MIT license and may be freely reproduced and translated. The Mitsubachi bee logo is released under the MIT license and may be freely reproduced on any medium.

Lartu © 2015 - 2021 — Released under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License.