This project was created as part of the 42 curriculum by Yaman Alrifai, Hamzah Beliah, and Yousef Kitaneh.

---

Table of Contents

• Description
• Instructions
  • Building and Running
  • Dependencies
  • Configuration File
    • Syntax Rules
    • Server Block
    • Location Block
    • CGI Configuration
• Resources
  • Documentation
  • Tests
  • Informational
  • Tools
  • AI Usage
• Contributing

Description

LeftHookRoll is a simple HTTP server implemented in C++. It is fully HTTP/1.0 compliant and supports the methods GET, POST, and DELETE, as well as dynamic CGI scripting functionality. The server operates on a single thread while still being fully non-blocking, achieving 100% availability on siege through the use of I/O multiplexing via epoll() and a stateful concurrency machine.

(Complete documentation available through Doxygen, see Documentation section)

the dependency graph for main.cpp, generated using Doxygen

the class relationship diagram for the Connection class, the beefiest class in our project

Instructions

Building and Running

At the root of the project, run:

    make
    ./server [config_file]

Additional make commands:

    make \
        clean       # removes object files
        fclean      # removes object files and executables
        re          # clean rebuild of project
        docs        # generates documentation using Doxygen
        docs-clean  # removes generated documentation

Details and syntax for writing the conf file are covered in Configuration File section. A sample conf file is provided in examples/confs. In addition to that, an autoconf.sh script is provided to guide you through the process of setting up a configuration file.

Dependencies

• a C++98 compiler
• a system that supports epoll() (Linux 🐧)
• optional:
  • doxygen for generating documentation
  • graphviz for generating system graphs in documentation

Configuration File

The server is configured via a text file following Nginx-inspired syntax.

Syntax Rules

• Blocks are enclosed in curly braces {}. Everything lives inside a server block.
• Directives end with a semicolon ;.
• Comments start with # and extend to the end of the line.
• Whitespace is ignored (spaces, tabs, newlines).

Server Block

server {
    # server directives here
}

Directive	Syntax	Example
listen	listen <port>; or listen <ip>:<port>;	listen 8080; / listen 127.0.0.1:8080;
server_name	server_name <name>;	server_name example.com;
client_max_body_size	client_max_body_size <size>;	client_max_body_size 10M;
error_page	error_page <code> <path>;	error_page 404 /errors/404.html;
location	location <path> { ... }	location /api { ... }

client_max_body_size suffixes: k/K (kilobytes), m/M (megabytes), g/G (gigabytes). Plain number = bytes.

Location Block

Defined inside a server block. Matched by longest-prefix against the request URL.

location /path {
    # location directives here
}

Directive	Syntax	Example
root	root <path>;	root /var/www/html;
methods	methods <METHOD> [METHOD ...];	methods GET POST DELETE;
autoindex	autoindex <on|off>;	autoindex on;
index	index <file>;	index index.html;
upload_store	upload_store <path>;	upload_store /var/www/uploads;
return	return <code> <url>;	return 301 https://new-site.com;
cgi_interpreter	cgi_interpreter <path> <.ext>;	cgi_interpreter /usr/bin/python3 .py;

CGI Configuration

CGI is configured per-location using the cgi_interpreter directive. Each directive maps a file extension to an interpreter binary. Multiple cgi_interpreter directives can be specified in a single location block to support different script types.

server {
    listen 8080;
    server_name localhost;
    client_max_body_size 1M;

    error_page 404 /errors/404.html;
    error_page 500 /errors/500.html;

    location / {
        root /var/www/html;
        methods GET;
        index index.html;
        autoindex off;
    }

    location /uploads {
        root /var/www;
        methods GET POST DELETE;
        upload_store /var/www/uploads;
    }

    location /cgi-bin {
        root /var/www;
        methods GET POST;
        cgi_interpreter /usr/bin/python3 .py;
        cgi_interpreter /usr/bin/perl .pl;
        cgi_interpreter /bin/sh .sh;
    }

    location /old-page {
        return 301 https://new-site.com/new-page;
    }
}

Resources

Documentation

Doxygen-generated documentation is available. To generate it, run make docs at the root of the project. Generated documentation will be located in docs/doxygen/html/index.html. It includes detailed descriptions of the server's architecture, design decisions, and implementation details, as well as system graphs generated using Graphviz.

Tests

A suite of tests is provided in the tests directory, to run:

./tests/tester.sh [help|standard|valgrind]

Informational

The most helpful resources we used:

• Beej's Guide to Network Programming
• HTTP 1.0 RFC
• HTTP in depth
• CGI RFC
• Understanding epoll
• Mozilla's HTTP docs
• nginx conf file syntax (as inspiration)

Tools

• siege for load testing and benchmarking the server's performance.
• Draw.io was used to collaborate on the specification and design of the server.
• GitHub was used for version control, code review, and project management.
• doxygen and graphviz were used to generate real-time documentation and system graphs.

AI Usage

AI was used to assist and speed up the code-writing process. To ensure quality and resilient code, testing suites and a rigorous code review process were put in place; no code was written without at least 2 human eyes reviewing it. AI was also used to proofread docs such as this document (; Architectural design and code structure were all human efforts.

Contributing

Although this project was created for educational purposes, contributions and questions are welcome. If you have any suggestions or questions, feel free to open an issue, submit a pull request, or reach out. The code standards we followed are detailed here.