CatChat Protocol version 0.1 The CatChat protocol is intended for chatting in chat rooms. This is a peer-to-peer networking protocol in which every client has a dual role of client and server and is called a servent. The basic premise is that a servent connects to another known servent. After connecting all messages to be broadcast to the chat room are sent directly through the connection and the servent connected to then broadcasts the message to all known servent. ** at a later time, parents may store information about children here. . . Furthermore, this particular peer-to-peer network has a controlled hierarchy. All connections in this network have the following characteristics: 1) There are no cycles in the network. This means that when a message is broadcast, nowhere in the network will the message be seen more than once. 2) A message must be able to reach every servent in the network; every servent is connected. 3) Some method exists to lookup a list of servents in the chat room that are capable of acting as hosts. The server that is in control of this must have a static IP address and must be up "most" of the time. (A web page is the intended target, but it does not have to be one) ====================== The Connection Process ====================== ** In this process, servent "Alice" is connecting to servent "Bob" Alice connects to Bob using his address and port number. Alice sends to Bob: "CatChat CONNECT \n" Where: is the version of the protocol that the client whishes to use. If Bob wishes to accept the connection, he sends back to Alice: "CatChat OK\n" If Bob does not wish to accept the connection, he sends back to Alice: "CatChat ERROR:\n" Where: is a string representing the reason why Alice can not connect (maybe Bob is too overworked and is not capable of accepting more connections) =================== Protocol Definition =================== Once connected servlets may communicate with the following definitions: +---------------+------------------------------------------------------------- | Tag | Description +---------------+------------------------------------------------------------- |Connect | Connecting servent uses this to let parent know | | specific details of connection. +---------------+------------------------------------------------------------- |Disconnect | Disconnecting servent uses this to let parent know | | that it is disconnecting from the network. +---------------+------------------------------------------------------------- |Join | Used for broadcasting that a particular servent has joined | | the network. +---------------+------------------------------------------------------------- |Leave | Used for broadcasting that a particular servent has left the | | network. +---------------+------------------------------------------------------------- |Message | Used to broadcast a chat message to the network +---------------+------------------------------------------------------------- |Ping | Used to discover if a particular servent is still connected | | and to discover latency information +---------------+------------------------------------------------------------- |Pong | Response to ping +---------------+------------------------------------------------------------- |User List | For sending user list information from the parent to the | | newly connecting child +---------------+------------------------------------------------------------- Before we discuss each packet type we need to go over a few definitions: Each packet may travel with differing scope. Scope refers to where a particular packet will be routed. Here is a list: * BROADCAST--send the packet to everyone except the sender * CHILD--send the packet to all children except for the sender * PARENT--send the packet only to the parent (if there is one) * PARENT/CHILD--send the packet to the parent and then send the packet to all of the children. Do not send this packet to the sender. * PRIVATE--only receive this packet and do not send it to anyone Definitions of terms: * Parent--the servent that is connected to by a particular servent * Children--the serent(s) that are connected to a particular servent * Chat Host--the servent that started the chat room ===================== Generic Packet format ===================== All packets have this form: +-----+----------------+---------+ | TAG | Payload Length | Payload | +-----+----------------+---------+ 0 1 4 5 N Byte Offset Tag: Connect=0x00 Disconnect=0x01 Join=0x40 Leave=0x41 Ping=0x80 Pong=0x81 Message=0xC0 UserList=0xE0 Payload Length: A four byte number representing the number of bytes in the payload Payload: N bytes of payload information. Each tag has a specific payload ======= Packets ======= Connect (0x00) ============== Connect packets are used to send specific log in information to the parent during the connection process. Scope: PRIVATE Payload: +--------+----------+ | Length | Nickname | +--------+----------+ 0 1 N Byte Offset Length: The number of bytes in the nickname (limited to 255 bytes) Nickname: The nickname that the connecting servent requests ** NOTE: If the connecting servent's nickname is already in use, the servent is not allowed to connect and is sent an Error packet (see Status Packet section) Actions for servent to take upon receiving this packet ------------------------------------------------------ 1) If the connecting servent's nickname is already in use, the servent is not allowed to connect and is sent an Error Packet (see Status Packet section) 2) If the connecting servent's nickname is allowed, the servent must send Join Packets to all known servents (see Join Packet) 3) The servent use list is sent to the connecting child. (see User List Packet) Disconnect (0x01) ================= This packet is used to disconnect from a parent. NOTE: There is no payload for this packet. Scope: PRIVATE Actions for servent to take upon receiving this packet ------------------------------------------------------ 1) Send Leave Packets to all servents Join (0x40) =========== A join packet is for broadcasting that a particular servent has joined the network. Scope: PARENT/CHILD Payload: +-----------------+----------+------------+------+ | Nickname Length | Nickname | IP Address | Port | +-----------------+----------+------------+------+ 0 1 4 5 8 9 12 Byte Offset Nickname Length: The number of bytes in a nickname (limited to 255) Nickname: The nickname of the servent that joined IP Address: IP address of the joining servent in IPv4 format: ** see the section on on IPv4 format Port: The port number of the joining servent's server socket ** If the servent is not capable of being a server this number should be -1 Actions for servent to take upon receiving this packet ------------------------------------------------------ 1) Save user information on servent user list a. store user information on user list b. If joiner is a child: store joiner as a child on child list ** a parent must know who all of its children are ** NOTE: If a duplicate servent join is received, it simply replaces the old information. (see the section on Net Splitting to see why this is so) 2) resend packet using scoping rules Leave (0x41) ============ A leave packet is for broadcasting that a particular servent has joined the network Scope: PARENT/CHILD Payload: +--------+----------+ | Length | Nickname | +--------+----------+ 0 1 N Byte Offset Length: The number of bytes in the nickname (limited to 255 bytes) Nickname: The nickname that the connecting servent requests Actions for servent to take upon receiving this packet ------------------------------------------------------ 1) Take servent off user list a. Take off of user list b. If leaveer is a child: Take off of child list 2) resend packet using scoping rules Ping (0x80) =========== A servent uses a ping packet to let all of the other servents know that it is still connected. Otherwise when a servent does not hear from another servent for a while, it will take the other servent off of its known servent list (it will timeout the disconnected servent). The frequency that a servent should broadcast a Ping is currently set to 15 minutes. Note however, a servent only needs to send a ping if it has not been active for a period of 15 minutes. (See definition: Active) ** See the secions on Timing Out and on Chat Room Hosting SCOPE: PARENT/CHILD Payload: +--------+----------+ | Length | Nickname | +--------+----------+ 0 1 N Byte Offset Length: The number of bytes in the nickname (limited to 255 bytes) Nickname: The nickname that the connecting servent requests Actions for servent to take upon receiving this packet ------------------------------------------------------ 1) Update timout for servent that sent the ping 2) Send a Pong Packet to the servent that sent the ping 2) resend packet using scoping rules ** at a later time, parents may store information about children here. . . Pong (0x81) ----------- A servent sends a Pong packet in response to a ping. The purpose of pong is for a servent to receive statistical information about all of the other servents that are on the network. When a servent sends a ping it also starts a timer. Every time a pong packet comes back the time that it took to receive the pong packet is recoreded along with who sent the pong packet. (This information could be used in the future to determine how to order the network) If a pong is not received within a timeout period the client should take no action against that client. The servent will already time out another way so no additional work should be performed. Scope: PARENT/CHILD Payload: +--------+---------------+-----------------+-------------+ | Length | From Nickname | To Nickname Len | To Nickname | +--------+---------------+-----------------+-------------+ 0 1 N N+1 N+4 N+5 M Byte Offset Length: The number of bytes in the nickname (limited to 255 bytes) From Nickname: The nickname that the connecting servent requests To Nickname Len: The number of bytes in the To Nickname field To Nickname: The nickname the pong is intended for Actions for servent to take upon receiving this packet ------------------------------------------------------ 1) Update timout for servent that sent the Pong 2) If the To Nickname field is "this" servent, update the statistical information of the servent in the From Field. statistical information: (Ping Time - Pong time) 3) resend packet using scoping rules Message (0xC0) -------------- The purpose of this packet is to broadcast a message to all servents in the chat room. Scope: BROADCAST Payload: +-------------+----------+----------------+---------+ | Nick Length | Nickname | Message Length | Message +-------------+----------+----------------+---------+ 0 1 N N+0 N+4 N+5 M Byte Offset Nick Length: The number of bytes in the nickname (limited to 255 bytes) Nickname: The nickname that the connecting servent requests Message Length: The number of bytes in the message Message: The message (** see Message Format section) Actions for servent to take upon receiving this packet ------------------------------------------------------ 1) Update timout for servent that sent the Message 2) resend packet using scoping rules UserList (0xE0) --------------- The purpose of this packet is to send the newly connected servent a list of known servents in the chat room. Scope: PRIVATE Payload +---------------+-------------------+--------------+ | Num. servents | Servent List Size | Servent List | +---------------+-------------------+--------------+ 0 3 4 7 8 N Byte Offset Num. Servents: The number of servents currently on the network Servent List Size: The size of the servent list Servent List: A list of servents in this format: nick1:IP:port\n nick2:IP:port\n . . . nickx:IP:port\n Where nickx is the Xth nickname on the list Where x = Num Servents NOTE: Each servent in the list is deliminated with a newline Actions for servent to take upon receiving this packet ------------------------------------------------------ 1) Put all entries in the user list ========== Timing Out ========== After a certain timeout period a servent will be taken off of the servent list. This is to ensure that only valid connected servents are listed on the network and that when a new servent attempts to join the chatting, they will join a valid servent. The current timeout period is: 15 minutes ============= Net Splitting ============= A net split can occur when a servent disconnects. When this happens all of its children will be orphaned meaning that they will no longer be a part of the network. This state is called a net split and is a term taken directly from IRC chatting. When a net split occurs these steps must be taken by a servent to ensure the chat room stays consistent. Each orphaned child must: 1) Detect that its parent is gone (either by receiving a Leave packet or by detecting a network connection error) 2) Each child must reconnect to the network using the same technique it used to connect in the first place. ** If the disconnecting parent was the chat host, the first child to reconnect will become the new chat host. 3) Each child must send a Join packet for each of its children that are still connected to the network. ================= Chat Room Hosting ================= **UNDER CONSTRUCTION** Currently one way exists for a servent interested in connecting to a chat room exists. It is in the form of a CGI Perl script that stores a servent's IP address and port number (and nickname and IP address of real connection). All servents that are capable of acting as servers will connect to a web page and register themselves as Chat Hosts. When the servent leaves the network, their information is taken off of the web site. When the servent leaves without disconnecting from the web page the servent times out in 15 minutes. In order for a new servent wishing to connect to the chat to connect to the chat it looks up the web site and queries for chat hosts. It receives a list of chat hosts and picks one at random to connect to. (If it cannot connect to the given chat host it should pick another randomly taking the bad host off its list) ============== Message Format ============== **UNDER CONSTRUCTION** All messages will be in the format of HTML. A client should not allow random html tags however. So a message sent to the chat room must only be plain text which is converted to HTML by the client. Messages will include: - Formatted text of differing colors and fonts - Images - Sounds (may change this format to be in XML later... depends)