david/rust-irc
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update readme, rfc

Browse Source
This commit is contained in:
David Westgate 2023-11-30 22:34:38 -08:00
parent fe27fdd9d4
commit e64c156216
3 changed files with 102 additions and 114 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
README.md
View File

@ -12,25 +12,9 @@ Here we have a simple irc-like client and server application in rust, and librar
### Behaviour ### Behaviour
#### Server For behaviour and protocol implementation, please consult rfc.txt
* A host can run the server application on port 6667
* The server can stop gracefully with `0` ## Source Code
* The server can list connected users with `1`
* The server can list active rooms with `2`
* The server can broadcast a message to all users with `3`
* The server can intentionally double lock with `4` (For testing/demonstration only)
#### Client
* A client can connect to a specified host
* A client can become a user by registering their desired nickname with the server (avoiding collisions)
* A new server has no rooms yet, and a new user is not a part of any room.
* A user may both join and create (as relevant) a room with `/join [room]`
* A user may both leave and destroy (as relevant) a room with `/leave [room]`
* A user may see the nickname of all other connected users with `/users`
* A user may see all rooms in existance with `/rooms`
* A user may see all users in a given room with `/list [room]`
* A user may send a message to a specific room (which they have joined) with `/msg [message]`
* A user may simultanously message all rooms they have joined by simply entering their message, not as a command.
* A user may stop gracefully with `/quit`
### `src/lib.rs` ### `src/lib.rs`
This file contains primarily the unique list of bytecodes used by both the client and the server in the irc implementation. Each message in either direction always start with one of these bytecodes in the stream. Errors are generally followed by a 2nd special error byte code also. This file also contains some shared/re-usable functions for modularity This file contains primarily the unique list of bytecodes used by both the client and the server in the irc implementation. Each message in either direction always start with one of these bytecodes in the stream. Errors are generally followed by a 2nd special error byte code also. This file also contains some shared/re-usable functions for modularity
@ -55,6 +39,9 @@ The use of stdout/stdin on this project leaves user experience to be desired on
Another element to be desired is de-muxing of the channel streams that are displayed to the client. Ideally more work could be done so that the client could choose to 'show' just one room at a time, and switch between room views with easy. Message that come in on the room not shown, would be cached in memory until displayed. With my approach, all client messages are displayed in the same stdout for simplicity. Another element to be desired is de-muxing of the channel streams that are displayed to the client. Ideally more work could be done so that the client could choose to 'show' just one room at a time, and switch between room views with easy. Message that come in on the room not shown, would be cached in memory until displayed. With my approach, all client messages are displayed in the same stdout for simplicity.
### `src/main.rs`
A simple entrypoint which will look for the `s` or `c` command line argument to run the server or client module.
## Building/ Running ## Building/ Running
To run the client in debug mode To run the client in debug mode
```bash ```bash

187
rfc.txt
View File

@ -1,5 +1,5 @@
Portland State University Computer Science Group David Westgate Portland State University Computer Science Group David Westgate
Request for Comments: CS594 02 Nov 2023 Request for Comments: CS594 30 Nov 2023
Internet Relay Chat Protocol Internet Relay Chat Protocol
@ -8,7 +8,7 @@ Status of This Memo
This memo defines a personal re-implementation of the already well established Internet Relay Chat Protocol, by presenting a simplified version using a subset of the full feature list defined in RFC 1459. This protocol does not add anything new to the well established IRC protocol, and is intended for academic purposes. This memo defines a personal re-implementation of the already well established Internet Relay Chat Protocol, by presenting a simplified version using a subset of the full feature list defined in RFC 1459. This protocol does not add anything new to the well established IRC protocol, and is intended for academic purposes.
Abstract Abstract
The IRC Protocol was developed in the early 1990’s as a simple method for internet users to communicate in real time, with the ability to organize various combinations of groups of users. Although once a popular means of internet communication, IRC has to some extent become niche as other instant messengers and social media platforms have become mainstream. IRC is uniquely fascinating from a privacy perspective in that anyone can run a server for their friends or the world and ensure they are the custodians of their data. The IRC Protocol was developed in the late 1980's as a simple method for internet users to communicate in real time, with the ability to organize various combinations of groups of users. Although once a popular means of internet communication, IRC has to some extent become niche as other instant messengers and social media platforms have become mainstream. IRC is uniquely fascinating from a privacy perspective in that anyone can run a server for their friends or the world and ensure they are the custodians of their data.
Table of Contents Table of Contents
@ -23,36 +23,39 @@ Table of Contents
3.2. Handling Clients 3.2. Handling Clients
3.3. User Management 3.3. User Management
3.4. Room Management 3.4. Room Management
3.5 Commands
3.5.1 0 - Quit
3.5.2 1 - List connected users
3.5.3 2 - List rooms
3.5.3 3 - Broadcast message
4. Client 4. Client
4.1. Client Initialization 4.1. Client Initialization
4.2. User Interaction 4.2. User Interaction
4.3. Commands 4.3. Commands
4.3.1 {message} 4.3.1 {message}
4.3.2 /msg [room,room…] {message} 4.3.2 /msg [room] {message}
4.3.3 /list 4.3.3 /list [room]
4.3.4. /join {room name} 4.3.4. /join {room name}
4.3.5. /my-rooms 4.3.5. /leave {room name}
4.3.6. /show {room} 4.3.6. /quit
4.3.7. /leave {room name}
4.3.8. /quit
5. Error Handling 5. Error Handling
5.1 Codes 5.1 Codes
5.2. Server experienced Errors 5.2. Errors
5.2.1 Attempt to message a room which does not exist 5.2.1 Client attempts to message a room which does not exist
5.2.2 Nickname collision 5.2.2 Nickname collision (a new users attempts to choose the same nickname as an already active user)
5.2.3 No KEEP_ALIVE 5.2.3 Client does not get a message for 30 seconds
5.3. Client experienced Errors 5.2.4 Out-of-order registration
5.3.1 Handling ERROR_INVALID_ROOM 5.2.5 Joining the same room twice
5.3.2 Handling NICKNAME_COLLISION 5.2.6 Leaving a room not yet joined
5.3.3 Network failure 5.2.7 Leaving a that does not exist
5.3.3 No RESPONSE to client message
6. Conclusion 6. Conclusion
6.1. Limitations/Omissions 6.1. Limitations/Omissions
6.2. Security Considerations + Privacy 6.2. Security Considerations + Privacy
6.3. Future 6.3. Future
6.4. References 6.4. References
1. Introduction, Scope 1. Introduction, Scope
Internet Relay Chat uses a client-server architecture to allow users (identified by nicknames) running a client application to establish a connection to a server application. Once connected, clients will be able to create, join, and leave multiple rooms, as well as send messages to other clients who are also members of those rooms. These are the core functionalities. Clients are also able to perform functions such as list all of the available rooms to join on the server, as well as listing all members of any particular room. Individual messages that clients send may be to one or more rooms. Internet Relay Chat uses a client-server architecture to allow users (identified by nicknames) running a client application to establish a connection to a server application. Once connected, clients will be able to create, join, and leave multiple rooms, as well as send messages to other clients who are also members of those rooms. These are the core functionalities. Clients are also able to perform functions such as list all of the available rooms to join on the server, as well as listing all members of any particular room. Individual messages that clients send may be to one room, or all of the rooms joined so far.
2. Protocol Overview 2. Protocol Overview
This IRC protocol is implement as a payload over TCP. TCP is a natural base layer protocol choice over IP for its ability to ensure data arrives uncorrupted and in-order. This IRC protocol is implement as a payload over TCP. TCP is a natural base layer protocol choice over IP for its ability to ensure data arrives uncorrupted and in-order.
@ -63,48 +66,63 @@ Table of Contents
2.2. Opcodes 2.2. Opcodes
Each opcode listed below will be elaborated on in the relevant section. If the opcode is expected to be followed by a parameter, it is shown in {}. Each opcode listed below will be elaborated on in the relevant section. If the opcode is expected to be followed by a parameter, it is shown in {}.
0x01: JOIN_ROOM {room} TBD = 0x00
0x02: JOIN_SERVER JOIN_ROOM = 0x01
0x03: LEAVE_ROOM {room} JOIN_SERVER = 0x02
0x04: LIST_ROOMS LEAVE_ROOM = 0x03
0x05: SEND_MESSAGE {message} LIST_ROOMS = 0x04
0x06: MESSAGE = 0x05
0x07: REGISTER_NICK = 0x06
0x08: LIST_USERS = 0x07
0x09: LIST_USERS_IN_ROOM = 0x08
0x0A: MESSAGE_ROOM = 0x09
0x0B: QUIT QUIT = 0x0B
0x0C: KEEP_ALIVE KEEP_ALIVE = 0x0C
0x0D: RESPONSE {message} RESPONSE = 0x0D
0x0E: RESPONSE_OK RESPONSE_OK = 0x0E
0x0F: ERROR {error code} ERROR = 0x0F;
2.3. Communication Flow 2.3. Communication Flow
Both the client and server may send instructions, which are the above Opcodes followed by their optional parameters. Both applications should expect a RESPONSE to each instruction, again which may have an optional parameter. Codes 0x01 to 0x05 are sent from the client, and the rest may be sent from either client or server Both the client and server may send instructions by writing TCP streams, which are the above Opcodes followed by their optional parameters. Both applications should expect a RESPONSE to each instruction, again which may have an optional parameter. Which codes may be sent from client or server, and maybe interpreted by each depend on the specific code.
3. Server 3. Server
It is critical the server application run with stability and accuracy to ensure client messages are correctly received, processed, and acted upon. It is critical the server application run with stability and accuracy to ensure client messages are correctly received, processed, and acted upon. Upon stopping the server, a QUIT signal and 0 byte stream will be written to each client to facillitate graceful stopping.
3.1. Server Initialization 3.1. Server Initialization
On start-up, the server application will read from storage a list of rooms (which may exist from a previous instance) and users associated with those rooms. The server will then create the rooms and associate the users. The server will then listen for TCP connections on port 6667 On start-up the server will listen for TCP connections on port 6667. If successful, the server application will start in a new state.
3.2. Handling Clients 3.2. Handling Clients
From this point, the server is responsible for keeping track of how many channels exist, the names of each channel, and the users associated with each channel, which as stated above should be persistent. Also, a list of the currently connected users by their nicknames will be kept track. From this point, the server is responsible for keeping track of how many channels exist, the names of each channel, and the users associated with (joined on) each channel. Also, a list of the currently connected users by their nicknames and tcp stream references will be kept track.
3.3. User Management 3.3. User Management
User management is handled simplistically. There is no authentication among nicknames, and the honor system will be relied on to prevent impersonation. A maximum number of users connected to the server at anytime of 20 will be imposed (to guarantee performance and reliability), but rooms will have no user limit. User management is handled simplistically. There is no authentication among nicknames, and the honor system will be relied on to prevent impersonation.
3.4. Room Management 3.4. Room Management
Rooms are to be created implicitly, as soon as the first user joins a room by a unique name, and rooms will be implicitly destroyed when the last user leaves. Rooms will be identified by a name between 3 and 20 characters, and are case insensitive. Messages sent to a room will be automatically forwarded by the server to all active users in the room. Users who are part of a room and then disconnect from the server, will automatically re-join the room on re-connecting to the server. Rooms are to be created implicitly, as soon as the first user joins a room by a unique name, and rooms will be implicitly destroyed when the last user leaves. Rooms will be identified by an alphanumeric name, and are case sensitive. Messages sent to a room will be automatically forwarded by the server to all users in the room aside from the sender. Users who are part of a room and then disconnect from the server, will be automatically removed from the room.
3.5 Commands
The server may run some basic diagnostic commands
3.5.1 0 - Quit
Send QUIT to each client, close each TCP connection and stop the server application
3.5.2 1 - List connected users
Print out all connected users, and information from their TCP connection
3.5.3 2 - List rooms
Print out all rooms and their associated users
3.5.3 3 - Broadcast message
Enter a message as a parameter to SEND_MESSAGE to each user.
4. Client 4. Client
Clients are the users, running the client application on their local machines. Clients are the users, running the client application on their local machines.
4.1. Client Initialization 4.1. Client Initialization
Clients who have never before used the application will first be prompted to choose a nickname. After this the client will then be prompted to enter the host-name of the server they wish to connect to. If a client has already connected to a host, they will be asked if they want to re-connect to this host, or choose a new one. Client will ask to JOIN_SERVER to the host, and await a RESPONSE_OK or ERROR Clients will first be prompted to choose a nickname. After this the client will then be prompted to enter the host-name of the server they wish to connect to. Client will ask to REGISTER_NICK on the host, and await a RESPONSE_OK or ERROR before the main client loop begins.
4.2. User Interaction 4.2. User Interaction
After a RESPONSE OK from attempting to connect to the hostname, the client is now a user of the server. The client application will present them with the standard input and output to show the information, server messages, and prompt for keyboard input After a RESPONSE OK from attempting to register their nickname, the client is now a user of the server. The client application will present them with the standard input and output to show the information, server messages, and prompt for keyboard input
4.3. Commands 4.3. Commands
The following commands are available on the standard input to users who have successfully connected to a host. The /help command will also list these The following commands are available on the standard input to users who have successfully connected to a host. The /help command will also list these
@ -112,77 +130,60 @@ Table of Contents
4.3.1 {message} 4.3.1 {message}
Any standard input not starting with / is assumed to be a message for the current active room. It is transmitted as a SEND_MESSAGE {message} operation Any standard input not starting with / is assumed to be a message for the current active room. It is transmitted as a SEND_MESSAGE {message} operation
4.3.2 /msg [room,room…] {message} 4.3.2 /msg [room] {message}
With this command, one or more valid room names may be included in a comma separated list in square brackets, followed by a space and then the message. There are a number of potential errors with this command which will be explored in the error handling section MESSAGE_ROOM command, one room name must be included, followed by a space and then the message. There are a number of potential errors with this command which will be explored in the error handling section
4.3.3 /list
A simple command which shall send LIST_ROOMS operation to the server and show the user the RESPONSE {data} , which is expected to contain a list of the available rooms
4.3.3 /list [room]
A simple command which shall send LIST_ROOMS operation to the server with the room name and show the user the RESPONSE {data} , which is expected to contain a list of users in the given room, if it exists.
4.3.4. /join {room name} 4.3.4. /join {room name}
Send a JOIN_ROOM operation with the room name and await a RESPONSE OK from the server. This is not expected to encounter any specific errors, as rooms which do not already exist are created. The client will enforce the character limits. Send a JOIN_ROOM operation with the room name and await a RESPONSE OK from the server. This is not expected to encounter any specific errors, as rooms which do not already exist are created.
4.3.5. /my-rooms 4.3.5. /leave {room name}
A simple command which shall show the user which rooms they are currently a member of. This is kept track of by the client application. Send a LEAVE_ROOM operation with the room name and await a response. This may have errors
4.3.6. /show {room} 4.3.6. /quit
Rotate standard out to show the specified room, which the user should already have joined. If the room specified is not one they are already in, let the user know they must join it first. Send a QUIT operation to the server and stop the client application.
4.3.7. /leave {room name}
Send a LEAVE_ROOM operation with the room name and await a response
4.3.8. /quit
Send a QUIT operation to the server and await a RESPONSE OK. Then, the client will be prompted with the standard output as shown when the application first starts.
5. Error Handling 5. Error Handling
Errors may occur in various ways, the most likely being an illegal instruction sent from the client. Network or connection errors may also occur and must be handled gracefully. Errors may occur in various ways, the most likely being an illegal instruction sent from the client. Network or connection errors may also occur and must be handled gracefully.
5.1 Codes 5.1 Codes
Error codes shall be 8 bit values both understood by the client and server Error codes shall be 8 bit values both understood by the client and server
INVALID_ROOM = 0x10
NICKNAME_COLLISION = 0x11
SERVER_FULL = 0x12 # Not used
ALREADY_REGISTERED = 0x13
NOT_YET_REGISTERED = 0x14
MALFORMED = 0x15
ALREADY_IN_ROOM = 0x16
NOT_IN_ROOM = 0x17
EMPTY_ROOM = 0x18
0x10 – ERROR_INVALID_ROOM 5.2. Errors
0x11 - NICKNAME_COLLISION These are the various anticipated possible errors between client/server flows
0x12
0x13
0x14
0x15
0x16
0x17
0x18
0x19
0x1A
0x1B
0x1C
0x1D
0x1E
0x1F
5.2. Server experienced Errors 5.2.1 Client attempts to message a room which does not exist
These are errors the server may have to handle The server will respond INVALID_ROOM
5.2.1 Attempt to message a room which does not exist 5.2.2 Nickname collision (a new users attempts to choose the same nickname as an already active user)
A user may attempt to /msg and list one or more rooms which do not exist. For the sake of simplicity, this will be handled with partial grace. If at-least one room in the list exists, the server will silently ignore the invalid rooms and respond with RESPONSE OK. However, if no rooms exist, the server shall respond ERROR_INVALID_ROOM. The server will respond NICKNAME_COLLISION
5.2.2 Nickname collision 5.2.3 Client does not get a message for 30 seconds
A user may attempt to connect to a server with a nickname that is already in use by a connected user. In this case, the server will response with NICKNAME_COLLISION, and the client will understand that it was not able to connect. The client will send a KEEP_ALIVE message every 10 seconds, and expected a RESPONSE_OK. If the client does not read any TCP stream for 30 seconds, the server is assumed unresponsive and the client will self terminate.
5.2.3 No KEEP_ALIVE 5.2.4 Out-of-order registration
The server is expected to see a KEEP_ALIVE message from the client every 30 seconds, to which it will send a RESPONSE_OK. If this message is not received at-least every 45 seconds, the server will considered the client disconnected and shall send it the QUIT message to let it know just in case. It should not be possible, but if the client attempts to register a nickname a 2nd time, the server will respond ALREADY_REGISTERED. If the client attempts to send commands before registering a nickname, the server will respond NOT_YET_REGISTERED
5.3. Client experienced Errors 5.2.5 Joining the same room twice
The server will respond ALREADY_IN_ROOM
5.3.1 Handling ERROR_INVALID_ROOM 5.2.6 Leaving a room not yet joined
In this event, we let the user know they attempted to send a message to an invalid room The server will respond NOT_IN_ROOM
5.2.2 Handling NICKNAME_COLLISION 5.2.7 Leaving a that does not exist
In this event, the user will be told there was a nickname collision and they must choose a different nickname to connect to the server. The server will respond INVALID_ROOM
5.3.3 Network failure
The nature of TCP with its acknowledgments allows the client application to detect if a message was infact received by the server. If there is a TCP socket interruption, the client will be disconnected and informed there may be a server or network issue
5.3.3 No RESPONSE to client message
If the client does not receive an expected response to any message, this may indicate that the server is online, but in a broken state. The user will be notified they should try their message again, or contact the server operator through another channel to investigate the issue. A well engineered server application should make this unlikely.
6. Conclusion 6. Conclusion
6.1. Limitations/Omissions 6.1. Limitations/Omissions
@ -205,7 +206,7 @@ Table of Contents
Since the body of TCP packets are visible to the network and could be snooped on by a potentially interested party, modern web applications generally run on an encryption layer like SSL or TLS. However, due to the extra complexity of including such a layer in this application, transmission will be both sent and received unencrypted. Therefor, the application will remind the user before each session not to send sensitive or private information with this application. Since the body of TCP packets are visible to the network and could be snooped on by a potentially interested party, modern web applications generally run on an encryption layer like SSL or TLS. However, due to the extra complexity of including such a layer in this application, transmission will be both sent and received unencrypted. Therefor, the application will remind the user before each session not to send sensitive or private information with this application.
6.3. Future 6.3. Future
This IRC implementation attempts to faithfully provide reliable internet chat for a group of users who trust one another, and to give them the ability to organize by channel. Of the noted omissions, the must urgent future update will include version validation, followed by an SSL encryption layer. Secondary future feature needs will focus on authentication, private messaging. Ideally, all remaining omissions would be included in the later future. This IRC implementation attempts to faithfully provide reliable internet chat for a group of users who trust one another, and to give them the ability to organize by channel. Of the noted omissions, the must urgent future update will include version validation, followed by an SSL encryption layer. Secondary future feature needs will focus on authentication, private messaging, seperate room muxing/switching. Ideally, all remaining omissions would be included in the later future.
6.4. References 6.4. References
References listed have helped inspire this RFC References listed have helped inspire this RFC

4
src/lib.rs
View File

@ -18,13 +18,13 @@ pub mod codes {
pub mod error { pub mod error {
pub const INVALID_ROOM: u8 = 0x10; pub const INVALID_ROOM: u8 = 0x10;
pub const NICKNAME_COLLISION: u8 = 0x11; pub const NICKNAME_COLLISION: u8 = 0x11;
pub const SERVER_FULL: u8 = 0x12; pub const SERVER_FULL: u8 = 0x12; // Not used
pub const ALREADY_REGISTERED: u8 = 0x13; pub const ALREADY_REGISTERED: u8 = 0x13;
pub const NOT_YET_REGISTERED: u8 = 0x14; pub const NOT_YET_REGISTERED: u8 = 0x14;
pub const MALFORMED: u8 = 0x15; pub const MALFORMED: u8 = 0x15;
pub const ALREADY_IN_ROOM: u8 = 0x16; pub const ALREADY_IN_ROOM: u8 = 0x16;
pub const NOT_IN_ROOM: u8 = 0x17; pub const NOT_IN_ROOM: u8 = 0x17;
pub const EMPTY_ROOM: u8 = 0x8; pub const EMPTY_ROOM: u8 = 0x18;
} }
} }