Webserv

Webserv is a minimal HTTP web server written in C++ (C++98). It supports multiple server blocks, locations, CGI, file uploads, autoindex, and common HTTP methods (GET, POST, DELETE).

Table of Contents

• Quick Start
• Configuration
• Multiplexing & I/O model
• HTTP Methods & Behavior
• Project layout
• Quick test examples
• Contributors

Quick Start

git clone <repo-url>
cd webserv
make
./webserv

Build:

• Command: make
• Rebuild: make re

Run:

• Run with default config: ./webserv (uses config/file.conf).
• Run with a specific config: ./webserv config/your.conf or via Makefile: make run ARGS="config/your.conf".

Debugging:

• Rebuild and run under Valgrind: make debug (Makefile target debug).

Configuration:

• Main configs live in config/file.conf and other files in config/.
• Example default listeners in config/file.conf include 127.0.0.2:8080 and 127.0.0.3:8080.

Configuration File:

• Default path: config/file.conf (used when no path is provided to the program).
• Structure: one or more server { ... } blocks. Each server block may contain:
  • listen <host>:<port> — bind address and port.
  • client_max_body_size <size> — maximum request body size (e.g. 100M).
  • location <path> { ... } — location-specific directives such as:
    • root <path> — filesystem root for that location.
    • index <file> — default file to serve.
    • methods GET|POST|DELETE — allowed HTTP methods.
    • upload <dir> — upload destination directory.
    • cgi <ext> <interpreter> — map file extensions to interpreters (e.g. .py /bin/python3).
    • autoindex on|off — enable directory listing.
    • return <code> <url> or return <url> — redirect/return a response.
• See the example configuration at config/file.conf for usage and more examples.

Configuration validation:

• The program requires valid configuration syntax to run. Other files in the config/ folder may be examples or incomplete — incorrect syntax will cause the server to fail to start or throw parsing errors.
• Always ensure your server { ... } and location { ... } blocks follow the examples in config/file.conf before running the program.

Multiplexing & I/O model:

• Webserv uses Linux epoll for scalable I/O multiplexing. The server creates an epoll instance and registers both listening sockets (for each server {} block) and client connection file descriptors (when new connections are accepted).
• Sockets are set non-blocking (O_NONBLOCK + FD_CLOEXEC) so I/O operations never block the main loop.
• The main loop calls epoll_wait() (configured in the code with a short/non-blocking timeout) and handles ready events:
  • EPOLLIN on a listening socket -> accept and create a Connection object.
  • EPOLLIN on a client socket -> parse incoming request data and update activity timestamp.
  • EPOLLOUT on a client socket -> send response data (supports chunked send for large bodies).
• Idle or stalled connections are closed by periodic timeout checks (RECV_TIMEOUT / SEND_TIMEOUT).
• Signals: the program ignores SIGPIPE and installs a SIGINT handler to perform a clean shutdown.

HTTP Methods & Behavior:

• Supported methods: GET , POST , and DELETE. Other methods return 501 Not Implemented.
• GET:
  • Serves static files from the location root.
  • If the requested path is a directory, the server tries each index file in order.
  • If autoindex on is set and no index file is found, the server returns a generated directory listing.
  • CGI-enabled files (by cgi .ext /path/to/interpreter) are executed and their output is used as the response.
  • Large file responses use a chunked send strategy to avoid loading the entire file in memory.
• POST:
  • Allowed when methods includes POST for the location.
  • Uploaded bodies are written to a temporary file then moved to the configured upload directory.
  • If the upload target corresponds to a CGI script, the server runs the CGI with the uploaded file on stdin and returns its output.
  • Content types are used to choose file extensions for stored uploads.
• DELETE:
  • Allowed when methods includes DELETE for the location.
  • Recursively deletes files/directories under the target path when permitted, returning appropriate status codes (204, 403, 404, 500).

Project layout:

Root files:

• main.cpp — Program entry point. Parses command-line arguments to load a config file (defaults to config/file.conf), starts the WebServer, and handles errors.
• Makefile — Build rules for compiling C++ files. Key targets: make (build), make re (rebuild), make run (rebuild and run with ARGS), make debug (run under Valgrind).
• WebServer.cpp & includes/WebServer.hpp — Core server class. Manages multiple ServerConfig instances, creates the epoll instance, and runs the main event loop.
• ServerConfig.cpp & includes/ServerConfig.hpp — Configuration parser and server socket management. Defines ServerConfig and Location classes for holding server and location settings.
• Connection.cpp & includes/Connection.hpp — Per-client connection handler. Manages request parsing, response building, and method dispatch (MethodGet, MethodPost, MethodDelete).
• Request.cpp & includes/Request.hpp — HTTP request parsing and storage.
• Methods.cpp — Implements the three HTTP methods: MethodGet(), MethodPost(), MethodDelete(), plus CGI and file utilities.
• MethodPost.cpp — POST logic: file uploads, CGI invocation on upload targets, and status responses.
• MethodDelete.cpp — DELETE logic: recursive file/directory removal with proper error handling.
• runServer.cpp — The main server event loop using epoll, socket event handling, timeout management, and signal handling.
• MyError.cpp & includes/MyError.hpp — Custom exception class for error handling.

Directories:

• config/ — Configuration files in plain-text format:
  • file.conf — The default config; defines listening servers and their routes.
  • test.conf, test1.conf, test3.conf — Example or alternate configs for testing.
• includes/ — C++ header files (.hpp):
  • WebServer.hpp, ServerConfig.hpp, Connection.hpp, Request.hpp, MyError.hpp — Class definitions and public interfaces.
• var/www/ — Default web root (served by example server blocks):
  • index2.html, index3.html, page.html — Static HTML files.
  • file.php, cgi_file.sh, script_cgi.py, test_website.py, time_out.py — CGI scripts for execution tests.
  • session/ — Example subdirectory with login/session scripts:
    • index.py, login.html, home.html — Session example files.
• errors/ — Custom HTTP error response pages (HTML files):
  • 400.html, 403.html, 404.html, 405.html, 408.html, 409.html, 411.html, 413.html, 414.html, 415.html, 500.html, 501.html, 502.html, 504.html — Standard error responses served by the server.

Quick test examples:

• Build: make
• Start server (default config): ./webserv
• Request homepage: curl http://127.0.0.2:8080/ or open in browser.
• Test GET curl http://127.0.0.2:8080/
• Test POST upload curl -X POST -F "file=@test.txt" http://127.0.0.2:8080/upload/
• Test DELETE curl -X DELETE http://127.0.0.2:8080/delete/test.txt
• Alternatively, test interactively with tools like Postman.

Contributors:

• Fatimezzahra BBOT
• Chaimae Khater