diff --git a/LICENSE b/LICENSE deleted file mode 100644 index 7548a3e..0000000 --- a/LICENSE +++ /dev/null @@ -1,21 +0,0 @@ -MIT License - -Copyright (c) 2024 whamCloud - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/README-SETUP.md b/README-SETUP.md deleted file mode 100644 index 37f8384..0000000 --- a/README-SETUP.md +++ /dev/null @@ -1,147 +0,0 @@ -## Table of Contents - -- [Demo](#demo) -- [Running Server and Client](#running-server-and-client) -- [Configurations](#configurations) -- [Running Tests](#running-tests) -- [Git Hooks Setup](#git-hooks-setup) -- [GitHub Workflow](#github-workflow) -- [Clean And Build](#clean-and-build) -- [Summary of the Responsibilities for crate chatty-types and chatty-tcp in Workspace](#summary-of-the-responsibilities-for-crate-chatty-types-and-chatty-tcp-in-workspace) -- [Domain Driven Terminology](#domain-driven-terminology) - -### Demo - -[Demo](demo/Weather-Standup.mp4) - -### Running Server and Client - -To run the server and client, use the following commands: - -```shell -just run-chatty-tcp-server -``` - -And for 3 clients: - -```shell -just run-chatty-tcp-client-carl-join -``` - -This passes the username carl as an argument to the client. -And similarly for other clients: - -```shell -just run-chatty-tcp-client-david-join -``` - -```shell -just run-chatty-tcp-client-lucio-join -``` - -For entering username at the prompt: - -```shell -just run-chatty-tcp-client-join-no-username -``` - -### Configurations - -The project uses custom configurations defined in `.cargo/config.toml`: - -- TCP_SERVER_ADDRESS default "localhost" -- TCP_SERVER_PORT default "8081" - These configurations are used to set the server address and port for the TCP server. - This allows clients to connect to the server using the same address and port. - -[Back to Table of Contents](#table-of-contents) - -### Running Tests - -##### Unit and Integration tests - -`just test` - -[Back to Table of Contents](#table-of-contents) - -### Git Hooks Setup - -This project uses git hooks to ensure code quality. To set up the pre-commit hook: - -```bash -chmod +x .githooks/pre-commit -git config core.hooksPath .githooks -``` - -Once set up, this hook will automatically run before every commit to ensure code quality. You can also run it directly -anytime: - -```bash -./.githooks/pre-commit -``` - -[Back to Table of Contents](#table-of-contents) - -### GitHub Workflow - -The project leverages GitHub Actions to validate chat server client connectivity and executes both unit and integration -tests. -The workflow is defined in `.github/workflows/rust.yml`. - -[Back to Table of Contents](#table-of-contents) - -### Clean And Build - -```shell -just clean -``` - -```shell -just build -``` - -```shell -just build-with-tests -``` - -[Back to Table of Contents](#table-of-contents) - -### Summary of the Responsibilities for crate chatty-types and chatty-tcp in Workspace - -###### chatty-types: - -* Core types and behaviors (more will be added as needed when more protocols are added, currently only TCP. However, the - separation is done from extensibility perspective if more protocols are added) -* Shared infrastructure like tracing config - -###### chatty-tcp: - -* TCP-specific transport layer or tightly coupled logic with TCP for now -* Server and client implementations -* Client has: - - Sending `command` module as part of the client - - Processing `response` module as part of the client - - These are part of the `connect` module used by the client. -* Server has: - - Processing `command` module as part of the server - - Sending `response` module as part of the server - - These are part of the `listen` module used by the server. - -Bidirectional communication between the client and server is clear based on module names. -Both have `command` and `response` modules: the client sends the commands and processes responses, while the server -processes commands and sends responses. - -[Back to Table of Contents](#table-of-contents) - -### Domain Driven Terminology: - -The following terms are consistently used throughout the project, forming the core vocabulary of our -domain-specific language in both design and development: - -- **User**: A person who interacts with the chat application. -- **Command**: Command issued by a user to the chat application. -- **ChatMessage**: Message sent by a user in the chat application as part of Send command. -- **ChatResponse**: Response sent by the chat application. -- **ChatMemo**: Memo sent by the chat application as part of ChatResponse. - -[Back to Table of Contents](#table-of-contents) diff --git a/README.md b/README.md index 8c4d4e1..1f47a6a 100644 --- a/README.md +++ b/README.md @@ -1,71 +1,183 @@ -# Simple Chat +## Table of Contents -## Summary +- [Asynchronous Chat System](#asynchronous-chat-system) + - [Overview](#overview) + - [Server Architecture](#server-architecture) + - [Client Features](#client-features) +- [Demo](#demo) +- [Running Server and Client](#running-server-and-client) +- [Configurations](#configurations) +- [Running Tests](#running-tests) +- [Git Hooks Setup](#git-hooks-setup) +- [GitHub Workflow](#github-workflow) +- [Clean And Build](#clean-and-build) +- [Summary of the Responsibilities for crate chatty-types and chatty-tcp in Workspace](#summary-of-the-responsibilities-for-crate-chatty-types-and-chatty-tcp-in-workspace) +- [Domain Driven Terminology](#domain-driven-terminology) -You have been tasked with writing a simple asynchronous chat server and CLI -client. +### Asynchronous Chat System -Since this is a simple chat server there is only a single room. Users may -freely join or leave this room. They may also send messages to the room, which -will be sent to all connected users minus the sender. +#### Overview -Even though the server is simple, it has high throughput. Because of this, all -code should be non-blocking for maximum concurrency. +A high-performance asynchronous chat system consisting of a server and CLI client implementation, designed for maximum +throughput and concurrency. -The following is a rough specification of the server and client. +#### Server Architecture -## Server +Manages a single chat room with efficient user handling +Processes incoming messages through non-blocking operations +Broadcasts messages to all connected users except the sender +Handles user join/leave operations seamlessly +Maintains unique usernames across the system +Optimized for high throughput with minimal memory footprint +Implements automatic cleanup on user disconnection -* The servers job is to manage users. -* It should be able to receive a message from a user and process it. -* The user may wish to join, leave or send a message through the chat server. -* Any other user who is currently connected should get the message sent to -them. -* The user who sent the message should not get the message. -* When a user sends a leave message, or disconnects their client, the server -should no longer send messages to them, and do any internal bookkeeping to -clean up. -* Username's should be unique. -* The server should be able to support many users without a large delay -* The server should be able to support many users with a small memory footprint +#### Client Features +Features an async CLI interface +Connects automatically to the server on startup +Configurable through environment variables or command line arguments for: -## Client +- Host address +- Port +- Username -* The client is an async CLI program. -* It is responsible for sending messages to the server and displaying any -messages from the server. -* The client should accept environment variables or command line arguments -indicating the host and port where the server is listening. It should also -accept a username that will be used as an identifier on the server. -* The client should automatically connect to the chat server upon -initialization using the specified host and port. -* The client should display an interactive command prompt. The prompt should -be able to handle the following inputs: - * `send ` where `` is the message that should be sent to the - server - * `leave` this will disconnect the client from the server and exit the CLI. +Provides an interactive command prompt supporting: +- send for message broadcasting +- leave for graceful disconnection -## Additional Requirements +### Demo -* Your source should contain both unit and integration tests where necessary. -* All code must be formatted using the standard formatting tool. -* Code must compile without clippy errors. +[Demo with Weather-Standup](demo/Weather-Standup.mp4) -## Submission +### Running Server and Client -Please fork this repository to your own GitHub account and submit a pull -request to your own repository. Your pull request should include a -video of a working demo at the top along with any other key information -that should be highlighted. A link to the pull request can be submitted when -it is ready for review. +To run the server and client, use the following commands: -## Bonus +```shell +just run-chatty-tcp-server +``` -* Include a pre-commit hook that will ensure that all code is formatted, compiles -without error, and is free of clippy errors. -* Create a GitHub Action that will launch your chat server and attempt to -send a message to the server from the client. Make sure that niether the server -or client exit with a failure. This action should be run anytime new code -is pushed to a branch or landed on the main branch. +And for 3 clients: + +```shell +just run-chatty-tcp-client-carl-join +``` + +This passes the username carl as an argument to the client. +And similarly for other clients: + +```shell +just run-chatty-tcp-client-david-join +``` + +```shell +just run-chatty-tcp-client-lucio-join +``` + +For entering username at the prompt: + +```shell +just run-chatty-tcp-client-join-no-username +``` + +### Configurations + +The project uses custom configurations defined in `.cargo/config.toml`: + +- TCP_SERVER_ADDRESS default "localhost" +- TCP_SERVER_PORT default "8081" + These configurations are used to set the server address and port for the TCP server. + This allows clients to connect to the server using the same address and port. + +[Back to Table of Contents](#table-of-contents) + +### Running Tests + +##### Unit and Integration tests + +`just test` + +[Back to Table of Contents](#table-of-contents) + +### Git Hooks Setup + +This project uses git hooks to ensure code quality. To set up the pre-commit hook: + +```bash +chmod +x .githooks/pre-commit +git config core.hooksPath .githooks +``` + +Once set up, this hook will automatically run before every commit to ensure code quality. You can also run it directly +anytime: + +```bash +./.githooks/pre-commit +``` + +[Back to Table of Contents](#table-of-contents) + +### GitHub Workflow + +The project leverages GitHub Actions to validate chat server client connectivity and executes both unit and integration +tests. +The workflow is defined in `.github/workflows/rust.yml`. + +[Back to Table of Contents](#table-of-contents) + +### Clean And Build + +```shell +just clean +``` + +```shell +just build +``` + +```shell +just build-with-tests +``` + +[Back to Table of Contents](#table-of-contents) + +### Summary of the Responsibilities for crate chatty-types and chatty-tcp in Workspace + +###### chatty-types: + +* Core types and behaviors (more will be added as needed when more protocols are added, currently only TCP. However, the + separation is done from extensibility perspective if more protocols are added) +* Shared infrastructure like tracing config + +###### chatty-tcp: + +* TCP-specific transport layer or tightly coupled logic with TCP for now +* Server and client implementations +* Client has: + - Sending `command` module as part of the client + - Processing `response` module as part of the client + - These are part of the `connect` module used by the client. +* Server has: + - Processing `command` module as part of the server + - Sending `response` module as part of the server + - These are part of the `listen` module used by the server. + +Bidirectional communication between the client and server is clear based on module names. +Both have `command` and `response` modules: the client sends the commands and processes responses, while the server +processes commands and sends responses. + +[Back to Table of Contents](#table-of-contents) + +### Domain Driven Terminology: + +The following terms are consistently used throughout the project, forming the core vocabulary of our +domain-specific language in both design and development: + +- **User**: A person who interacts with the chat application. +- **Command**: Command issued by a user to the chat application. +- **ChatMessage**: Message sent by a user in the chat application as part of Send command. +- **ChatResponse**: Response sent by the chat application. +- **ChatMemo**: Memo sent by the chat application as part of ChatResponse. + +[Back to Table of Contents](#table-of-contents)