mitre

Implement a Short Text Transfer Protocol Server

STTP (Short Text Transfer Protocol) is a made-up, lightweight protocol, designed for simple file management over TCP. The protocol allows clients to create, retrieve, update, delete, and list files containing short text snippets, each up to 160 characters long. Implement this server in any language you'd like.

Working Agreement
link

A working agreement is essentially a promise to you or to your team on habits and processes you agree to follow while working on a project.

Tip: Try to incorporate as many of these habits as possible, as is they aim to reflect a real-world workflow vs just hacking away at something. They are designed to keep you organized and ensure you deliver a quality product.

optional
circle
STTP Specification Review

The STTP Specification can be found in the following link.

optional
all_inclusive
circle
Error Handling and Feedback

As a developer, I agree to handle errors gracefully and provide feedback to the user.

Key Points
  • Implement error messages for invalid commands, missing arguments, or other user errors.
  • Ensure success messages for operations such as adding tasks or creating lists are distinct and easily visible.
  • Provide suggestions for correcting common errors to guide users in the right direction.
optional
all_inclusive
circle
Stories Must be Properly Tested

As a developer, I agree to ensure each story is properly tested. (A lot of times it can be a pain to test a CLI's tool main function, you'll understand when you get there, try your best, 100% code coverage is not required)

Key Points
  • Each story includes necessary unit testing.
  • Tests are run upon completion of a story.
  • All tests should pass before merge.
optional
all_inclusive
circle
Use Story Branches

As a developer, I agree to create a new git branch for each story I work on.

Key Points
  • Checkout a new branch for each story.
  • Development for a story is committed to the story branch.
  • Upon completion, create a PR to merge a story branch back into main.
  • If you are doing this project solo, you will be merging your own PRs.
(F) Server Initialization
link

Set up the basic structure and configuration for the STTP server, including handling network connections and reading configuration files.

optional
circle
(S) Server Configuration File

As a developer, I want to create a configuration file for the STTP server, so that I can easily manage settings like address, port, and docroot.

Key Points
  • The configuration file must be created in YAML format.
  • It should include settings for `listen_address`, `port`, and `docroot`.
  • The server must parse the configuration file at startup.
optional
circle
(S) Initialize TCP Server

As a developer, I want to set up the TCP server to listen for incoming connections, so that the STTP server can accept client requests.

Key Points
  • The TCP server must be initialized to listen on the configured address and port.
  • Basic logging should be implemented for incoming connections.
(F) Request Parsing
link

Implement the logic to parse incoming STTP requests, so the server can understand and respond to client commands.

optional
circle
(S) Parse STTP Request Format

As a developer, I want to parse incoming STTP requests, so that the server can understand the action, path, and optional content.

Key Points
  • The server must parse the STTP request format - `<action> <path/filename> (<contents> optional)`.
  • The request format must be validated.
  • The server should return an appropriate response for invalid requests.
optional
circle
(S) Implement Request Handlers

As a developer, I want to implement handlers for each STTP action, so that the server can process client requests.

Key Points
  • Handlers must be created for `CREATE`, `SHOW`, `LIST`, `DELETE`, and `UPDATE` actions.
  • Each handler must perform the correct operation based on the request.
  • The server should return appropriate success or error responses after processing the request.
(F) File Operations
link

Implement file operations for the STTP server, allowing it to create, read, update, and delete files as requested by the client.

optional
circle
(S) Implement CREATE Operation

As a developer, I want to implement the CREATE operation, so that the server can create new files with the provided content.

Key Points
  • The filename must be validated and must not exceed 32 characters.
  • The server must create the file with the specified content if it does not already exist.
  • The server should return a `100 CREATED` response if the operation is successful or an appropriate error response otherwise.
optional
circle
(S) Implement SHOW Operation

As a developer, I want to implement the SHOW operation, so that the server can retrieve and return the content of a specified file.

Key Points
  • The server must check if the specified file exists.
  • The server must return the file content with a `200 OK` response if the file exists.
  • The server should return a `400 NOT FOUND` response if the file does not exist.
optional
circle
(S) Implement LIST Operation

As a developer, I want to implement the LIST operation, so that the server can return a list of files in a specified directory.

Key Points
  • The server must validate that the directory exists.
  • The server should return a list of files in the directory with a `200 OK` response.
  • The server should return a `400 NOT FOUND` response if the directory does not exist.
optional
circle
(S) Implement DELETE Operation

As a developer, I want to implement the DELETE operation, so that the server can delete a specified file.

Key Points
  • The server must check if the specified file exists.
  • The server must delete the file and return a `600 DELETED` response.
  • The server should return a `400 NOT FOUND` response if the file does not exist.
optional
circle
(S) Implement UPDATE Operation

As a developer, I want to implement the UPDATE operation, so that the server can modify the content of a specified file.

Key Points
  • The filename must be validated and must not exceed 32 characters.
  • The server must update the file content if the file exists.
  • The server should return a `200 OK` response if the operation is successful, or a `400 NOT FOUND` response if the file does not exist.
(F) Error Handling and Response
link

Implement error handling and ensure the server returns appropriate responses for all operations.

optional
circle
(S) Handle Invalid Requests

As a developer, I want to handle invalid requests gracefully, so that the server provides useful feedback to the client.

Key Points
  • The server must return a `300 CLIENT ERROR` response for invalid commands or arguments.
  • The server should provide suggestions or correct format guidelines in the response message.
optional
circle
(S) Implement 310 FILENAME TOO LONG Response

As a developer, I want to implement the 310 FILENAME TOO LONG response, so that the server enforces the filename length limit.

Key Points
  • The server must check the filename length for all file operations.
  • The server should return a `310 FILENAME TOO LONG` response if the filename exceeds 32 characters.
optional
circle
(S) Handle Path Errors

As a developer, I want to handle errors related to paths, so that the server can correctly respond to issues with paths that don't exist.

Key Points
  • The server must return a `410 PATH NOT FOUND` response if a specified path does not exist.
  • The server should return a `510 CANNOT CREATE PATH` response if it is unable to create the required path.
optional
circle
(S) Implement 500 SERVER ERROR Response

As a developer, I want to implement a 500 SERVER ERROR response, so that the server can inform the client of internal errors.

Key Points
  • The server must catch unexpected errors during file operations.
  • The server should return a `500 SERVER ERROR` response with a relevant error message.
(F) Caching System
link

Implement a caching system to improve the performance of the STTP server by storing frequently accessed files in memory.

optional
circle
(S) Implement Cache Initialization

As a developer, I want to initialize the caching system, so that frequently accessed files can be stored in memory.

Key Points
  • The configuration file must include cache settings such as `enabled`, `max_files`, `max_size`, and `expiration`.
  • The caching system must be initialized based on the provided settings.
  • Note that the expiration setting will be used in next feature - (F) Concurrency and Thread Safety
optional
circle
(S) Implement File Caching

As a developer, I want to implement file caching, so that the server can quickly serve cached files to clients.

Key Points
  • The server must cache files upon first access and store them based on the defined limits.
  • The server should serve files from the cache if available, reducing disk I/O.
  • A cached file shall be removed from the cache if the file is modified or replaced with an STTP UPDATE request.
optional
circle
(S) Cache Management

As a developer, I want to manage and expire cached files, so that the cache remains within the defined limits.

Key Points
  • The server must implement logic to remove the least recently used (LRU) files when the cache reaches its max size or file count.
  • Cached files that exceed the expiration time must be removed from the cache.
(F) Concurrency and Thread Safety (Advanced)
link

Implement concurrency in the STTP server to handle multiple client requests simultaneously and ensure thread safety, especially in shared resources like the cache.

optional
circle
(S) Implement Concurrency for Handling Client Connections

As a developer, I want to use concurrent execution to handle multiple client connections simultaneously, so that the server can serve multiple clients efficiently.

Key Points
  • The server must implement concurrent execution to handle each client connection in parallel.
  • The main server loop should continue to accept new connections while handling current clients.
optional
circle
(S) Implement Mutex for Cache Access

As a developer, I want to implement mutual exclusion mechanisms to protect access to the cache, so that concurrent reads and writes do not cause race conditions.

Key Points
  • The server must implement mutual exclusion to control access to the cache.
  • The server should ensure only one execution thread can read or write to the cache at a time.
  • The server should be tested to ensure there are no race conditions when accessing the cache.
optional
circle
(S) Cache Expiry

As a developer, I want to manage and expire cached files, so that the cache remains within the defined limits.

Key Points
  • Introduce a background routine which will remove items from the cache.
  • Cached files that exceed the expiration time must be removed from the cache.
optional
circle
(S) Implement Communication Mechanisms for Safe Interaction

As a developer, I want to implement safe communication mechanisms for concurrent execution threads, so that the server can coordinate actions without shared memory issues.

Key Points
  • The server must implement safe communication mechanisms between the main server loop and worker threads.
  • The server should use these mechanisms to safely pass data between concurrent threads.
  • The server must ensure communication channels are closed properly to avoid deadlocks or resource leaks.
optional
circle
(S) Test for Race Conditions

As a developer, I want to thoroughly test for race conditions, so that the server remains stable and reliable under concurrent load.

Key Points
  • The server must be tested using tools to identify potential race conditions.
  • The server should be tested under simulated heavy load with multiple concurrent clients to ensure stability.
  • Any identified race conditions must be fixed and re-tested to ensure stability.
(F) CLI - Design and Setup
link

Design and implement the basic structure for the STTP client CLI, including parsing commands and handling global flags.

optional
circle
(S) Implement Basic CLI Structure

As a user, I want a basic CLI structure that handles commands and options correctly.

Key Points
  • The CLI must parse and handle commands correctly.
  • Global flags `-h, --help` and `-v, --verbose` must be implemented.
  • The CLI must display correct usage information when `-h` is passed.
optional
circle
(S) Implement Verbose Flag

As a user, I want a verbose flag that enables detailed output for debugging.

Key Points
  • The CLI must provide detailed output when the `-v` flag is enabled.
  • Verbose logging should be consistent across all commands.
(F) CLI - URL Parsing and Domain Lookup
link

Implement the parsing of the `sttp://` URL format and handle domain lookup with a default port.

optional
circle
(S) Parse STTP URL

As a user, I want the CLI to correctly parse the `sttp://` URL format to extract the host, port, path, and filename.

Key Points
  • The CLI must correctly parse the host, port, path, and filename from the URL.
  • If no port is specified, the CLI must default to port 8080.
  • The parsed components should be validated and used in subsequent requests.
optional
circle
(S) Handle Domain Lookup

As a user, I want the CLI to resolve domain names to IP addresses before making requests.

Key Points
  • The CLI must resolve the domain name to an IP address before making requests.
  • The CLI should handle errors in domain resolution gracefully and provide clear feedback to the user.
(F) CLI - Implement STTP Actions
link

Implement the core STTP actions (create, show, list, delete, update) in the CLI.

optional
circle
(S) Implement CREATE Action

As a user, I want to create a file on the STTP server with specified content using the `create` action.

Key Points
  • The CLI must parse the `create` command and send a `CREATE` request to the server.
  • The CLI must handle and display the server's response, whether successful or not.
optional
circle
(S) Implement SHOW Action

As a user, I want to retrieve the content of a file from the STTP server using the `show` action.

Key Points
  • The CLI must parse the `show` command and send a `SHOW` request to the server.
  • The CLI must display the retrieved content or an error message based on the server's response.
optional
circle
(S) Implement LIST Action

As a user, I want to list all files in a directory on the STTP server using the `list` action.

Key Points
  • The CLI must parse the `list` command and send a `LIST` request to the server.
  • The CLI must display the list of files or an appropriate error message based on the server's response.
optional
circle
(S) Implement DELETE Action

As a user, I want to delete a file on the STTP server using the `delete` action.

Key Points
  • The CLI must parse the `delete` command and send a `DELETE` request to the server.
  • The CLI must handle and display the server's response, confirming deletion or showing an error.
optional
circle
(S) Implement UPDATE Action

As a user, I want to update the content of a file on the STTP server using the `update` action.

Key Points
  • The CLI must parse the `update` command and send an `UPDATE` request to the server.
  • The CLI must handle and display the server's response, confirming the update or showing an error.