diff --git a/subjects/localhost/README.md b/subjects/localhost/README.md new file mode 100644 index 00000000..2c2c8bb6 --- /dev/null +++ b/subjects/localhost/README.md @@ -0,0 +1,76 @@ +## Localhost + +Finally you are going to understand how internet works from the server side. The Hypertext Transfer Protocol was created in order to ensure a reliable way to communicate on a request/response base. + +This protocol is used by servers and clients (usually browsers) to serve content and it is the backbone of the World Wide Web, still it is also used in many other cases that are far beyond the scope of this exercise. + +Here you will learn the basics of the protocol and a good place to start could be the [HTTP/1.1 RFC](https://www.rfc-editor.org/rfc/rfc9112.html). + + +### Instructions + +- The project can be written in one of these languages [`Rust`, `C++`, `C`]. + +#### The Server + +- Your server should **never** crash. +- All requests should timeout if they are taking too long. +- Your server should be able to listen on multiple ports and instantiate multiple servers at the same time. +- You must use only one process and one thread. +- Your server must receive a request from the browser/client and send a response using the `HTTP` header and body. +- Your server should be compatible with `HTTP/1.1` protocol. +- You can compare your results with `NGINX` which will be used as the reference. +- Your server should be compatible with the last version of your chosen browser. +- Your server should manage at least [`GET`, `POST`, `DELETE`] methods. +- Your server should be able to receive file uploads made by the client. +- Your server should handle cookies and sessions. +- You should create default error pages for at least the following error codes [400,403,404,405,413,500]. +- Your server should call `select` function (or `poll` or equivalent) only once for each client/server communication. +- All reads and writes should pass by `select` or equivalent API. +- All I/O operations should be non-blocking. +- You should manage chunked and unchunked requests. +- You should set the right status for each response. + +#### The CGI +- Based on the file extension the server will execute the corresponding `CGI` (for example `.php` or `.py`). +- You need to implement only one `CGI` of your choice. +- You are allowed to fork a new process to run the `CGI`. +- `CGI` expects the file to process as first argument and `EOF` as end of the body. +- Pay attention to the directory where the `CGI` will run for correct relative paths handling. +- The `CGI` will check `PATH_INFO` environment variable to define the full path. + +#### Configuration File + +In the file you should be able to specify the following: + +- The host (server_address) and one or multiple ports for each server. +- The first server for a host:port will be the default if the "server_name" didn't match any other server. +- Path to custom error pages. +- Limit client body size for uploads. +- Setup routes with one or multiple of the following settings: + - Define a list of accepted HTTP methods for the route. + - Define HTTP redirections. + - Define a directory or a file from where the file should be searched (for example, if `/test` is rooted to `/usr/Desktop`, the URL `/test/my_page.html` will route to `/usr/Desktop/my_page.html`). + - Define a default file for the route if the URL is a directory. + - Specify a `CGI` to use for a certain file extension. + - Turn on or off directory listing. + - Set a default file to answer if the request is a directory. +- No need to manage comments "(#)". + +> Routes won't need to support regular expressions. + +> There is no need to pass through `poll` when reading the configuration file. + +#### Testing your server +- Do stress tests (for example with `siege -b [IP]:[PORT]`), it must stay available at all costs (availability should be up to 99.5). +- Create tests for as many cases as you can (redirections, bad configuration files, static and dynamic pages, default error pages and so on). +- You will be requested to provide and explain your tests during the audits. +- You can use the language you prefer to write tests, as long as they are exhaustive and the auditor can check their behavior. +- Test possible memory leaks before to submit the project. +- Once again, the server should never crash and never leak memory. + +### Bonus +- Handle at least one more `CGI`. +- Write the project in two different programming languages. + +> If the two languages are C and C++ the provided solution for C++ should heavily rely on C++ specific features. diff --git a/subjects/localhost/audit/README.md b/subjects/localhost/audit/README.md new file mode 100644 index 00000000..5f6d1ee4 --- /dev/null +++ b/subjects/localhost/audit/README.md @@ -0,0 +1,65 @@ +#### Functional + +#### Localhost is about creating your own HTTP server and test it with an actual browser. +#### Take the necessary time to understand the project and to test it, looking into the source code will help a lot. + +### Basic server mechanics + +#### The student should be able to justify his choices and explain the following: +###### How does an HTTP server works? +###### Which function was used for I/O Multiplexing and how does it works? +###### Is the server using only one select (or equivalent) to read the client requests and write answers? +###### Why is it important to use only one select and how was it achieved? +###### Read the code that goes from the select (or equivalent) to the read and write of a client, is there only one read or write per client per select (or equivalent)? +###### Are the return values for I/O functions [read,recv,write,send] checked properly? (checking only -1 or 0 is not enough, both should be checked). +###### If an error is returned by the previous functions on a socket, is the client removed? +###### Is writing and reading ALWAYS done through a select (or equivalent)? + +### Configuration file + +#### Check the configuration file and ensure the following configs are working: +##### Setup a single server with a single port. +##### Setup multiple servers with different port. +##### Setup multiple servers with different hostnames (for example: curl --resolve test.com:80:127.0.0.1 http://test.com/). +##### Setup custom error pages. +##### Limit the client body (for example: curl -X POST -H "Content-Type: plain/text" --data "BODY with something shorter or longer than body limit"). +##### Setup routes and ensure they are taken into account. +##### Setup a default file in case the path is a directory. +##### Setup a list of accepted methods for a route (for example: try to DELETE something with and without permission). + +### Methods and cookies + +#### For each method be sure to check the status code (200, 404 etc): +###### Are the GET requests working properly? +###### Are the POST requests working properly? +###### Are the DELETE requests working properly? +###### Test a WRONG request, is the server still working properly? +###### Upload some files to the server and get them back to test they were not corrupted. +###### A working session and cookies system is present on the server? + +### Interaction with the browser + +#### Open the browser used by the team during tests and its developer tools panel to help you with tests. +###### Is te browser connecting with the server with no issues? +###### Are the request and response headers correct? (It should serve a full static website without any problem). +###### Try a wrong URL on the server, is it handled properly? +###### Try to list a directory, is it handled properly? +###### Try a redirected URL, is it handled properly? +###### Check the implemented CGI, does it works properly with chunked and unchunked data? + +### Port issues + +###### Configure multiple ports and websites and ensure it is working as expected. +###### Configure the same port multiple times. The server should find the error. +###### Configure multiple servers at the same time with different configurations but with common ports. Ask why the server should work if one of the configurations isn't working. + +### Siege & stress test + +##### Use siege with a GET method on an empty page, availability should be at least 99.5% with the command `siege -b [IP]:[PORT]`. +##### Check if there is no memory leak (you could use some tools like top). +##### Check if there is no hanging connection. + +### Bonus Part + +##### +There's more than one CGI system such as [Python,C++,Perl]. +##### +There is a second implementation of the server in a different language (repeat practical tests on it before to validate).