Skip to content

README.md

Latest commit

 

History

History
456 lines (370 loc) · 16.5 KB

README.md

File metadata and controls

456 lines (370 loc) · 16.5 KB

HTTP Server - Zero-Dependency Java NIO Implementation

A high-performance, production-ready HTTP/1.1 server built from scratch in Java with zero external dependencies. Features non-blocking I/O, virtual hosts, file uploads, CGI execution, and comprehensive HTTP compliance.

🚀 Quick Start

# Build
make build

# Run
make run

# Test
curl http://localhost:8080/

Server starts on http://localhost:8080 by default.

✨ Features

Core HTTP Features

  • ✅ HTTP/1.1 Compliant - Full protocol support with keep-alive connections
  • ✅ Non-Blocking I/O - Single-threaded event loop handles 1000+ concurrent connections
  • ✅ Virtual Hosts - Multiple sites on same IP:port, routed by Host header
  • ✅ Multi-Port - Listen on multiple ports simultaneously
  • ✅ Keep-Alive - Persistent connections for improved performance

Request Processing

  • ✅ Incremental Parsing - Handles partial data without buffering entire request
  • ✅ Chunked Transfer Encoding - Supports chunked request/response bodies
  • ✅ Large Body Handling - Automatic disk streaming for bodies > 5MB
  • ✅ Path Traversal Protection - Prevents ../ attacks
  • ✅ Request Timeouts - 10-second inactivity timeout

📖 Detailed Documentation: Request Parser →

File Upload System

  • ✅ Multipart/Form-Data - RFC 7578 compliant, multiple files per request
  • ✅ Raw Binary Upload - Direct file POST/PUT
  • ✅ Disk Streaming - Files stream directly to disk (no memory limits)
  • ✅ Security - Filename sanitization, path traversal prevention
  • ✅ Mixed Mode - Handles chunked multipart (rare but valid)

📖 Detailed Documentation: File Upload →

CGI Execution

  • ✅ Non-Blocking Execution - CGI scripts don't block the event loop
  • ✅ Standard CGI/1.1 - Full environment variable support
  • ✅ Process Monitoring - 5-second timeout, 10MB output limit
  • ✅ Stdin/Stdout Streaming - Handles large request/response bodies

📖 Detailed Documentation: CGI Execution →

Routing & Handlers

  • ✅ URL Routing - Longest-prefix matching algorithm
  • ✅ Static Files - MIME type detection, browser caching headers
  • ✅ Directory Listing - Optional directory browsing with sorting
  • ✅ HTTP Redirects - 301/302 redirects with configuration
  • ✅ DELETE Support - File deletion with safety checks
  • ✅ Custom Error Pages - Configurable 404/500 pages

📖 Detailed Documentation: Router & Handlers →

Sessions & State

  • ✅ Session Management - Server-side session storage with UUID
  • ✅ Cookie Support - Parsing and setting cookies (HttpOnly flag)
  • ✅ Thread-Safe - ConcurrentHashMap-based session store

📖 Detailed Documentation: HTTP Features (Redirects, Sessions, etc.) →

Advanced Features

  • ✅ Zero-Copy File Transfer - Uses FileChannel.transferTo() for efficiency
  • ✅ Virtual Hosts - Name-based virtual hosting
  • ✅ Multi-Server Config - Run multiple independent servers
  • ✅ Comprehensive Logging - File + console logging with rotation

📖 Detailed Documentation: Server Core & Event Loop →

Configuration

  • ✅ JSON Configuration - Human-readable config files
  • ✅ Zero Dependencies - Custom JSON parser
  • ✅ Comprehensive Validation - Type checking, range validation, duplicate detection
  • ✅ Hot-Swappable Routes - (future: currently requires restart)

📖 Detailed Documentation: Configuration System →

📁 Project Structure

.
├── src/
│   ├── Main.java                    # Entry point
│   ├── core/
│   │   ├── Server.java             # NIO selector, event loop
│   │   └── ClientHandler.java     # Per-connection state & I/O
│   ├── http/
│   │   ├── RequestParser.java      # HTTP request parser (incremental)
│   │   ├── ResponseBuilder.java    # Response construction
│   │   ├── MultipartParser.java    # Multipart/form-data parser
│   │   ├── HttpRequest.java        # Request data structure
│   │   ├── HttpHeaders.java        # Header storage
│   │   ├── HttpMethod.java         # GET/POST/DELETE enum
│   │   └── HttpStatusCode.java     # Status codes enum
│   ├── handlers/
│   │   ├── Handler.java            # Handler interface
│   │   ├── StaticFileHandler.java  # Serve files
│   │   ├── DirectoryHandler.java   # Directory listing
│   │   ├── UploadHandler.java      # File uploads
│   │   ├── CGIHandler.java         # CGI execution
│   │   ├── DeleteHandler.java      # File deletion
│   │   ├── RedirectHandler.java    # URL redirects
│   │   ├── ErrorHandler.java       # Error pages
│   │   └── SessionHandler.java     # Session demo
│   ├── router/
│   │   └── Router.java             # Route matching & handler selection
│   ├── config/
│   │   ├── AppConfig.java          # Root config
│   │   ├── ServerConfig.java       # Server config
│   │   ├── RouteConfig.java        # Route config
│   │   ├── ConfigLoader.java       # Config loading
│   │   └── ConfigValidator.java    # Config validation
│   ├── session/
│   │   ├── SessionManager.java     # Session storage
│   │   └── Cookie.java             # Cookie handling
│   ├── utils/
│   │   ├── JsonParser.java         # Custom JSON parser
│   │   ├── MimeTypes.java          # MIME type mapping
│   │   └── ServerLogger.java       # Logging utility
│   └── exceptions/
│       ├── HttpParseException.java
│       └── InvalidMethodException.java
├── test/
│   └── http/
│       └── RequestParserTest.java  # 103 unit tests
├── www/                            # Static files root
│   ├── index.html
│   ├── about.html
│   └── images/
├── scripts/                        # CGI scripts
│   ├── cgi-1.py
│   ├── cgi-2.py
│   └── cgi-3.py
├── config.json                     # Server configuration
├── makefile                        # Build & run commands
└── README.md                       # This file

🔧 Configuration

Basic Configuration (config.json)

{
  "name": "http-server",
  "version": "1.0.0",
  "servers": [
    {
      "host": "127.0.0.1",
      "ports": [8080],
      "serverName": "localhost",
      "defaultServer": true,
      "maxBodySize": 104857600,.
      "routes": [
        {
          "path": "/",
          "methods": ["GET"],
          "root": "./www",
          "index": "index.html"
        },
        {
          "path": "/uploads",
          "methods": ["POST", "DELETE"],
          "root": "./www/uploads"
        },
        {
          "path": "/cgi-bin",
          "root": "./scripts",
          "methods": ["GET", "POST"],
          "cgiExtension": "py"
        }
      ]
    }
  ]
}

Virtual Hosts Example

{
  "servers": [
    {
      "host": "127.0.0.1",
      "ports": [8080],
      "serverName": "site1.local",
      "defaultServer": true,
      "routes": [...]
    },
    {
      "host": "127.0.0.1",
      "ports": [8080],
      "serverName": "site2.local",
      "routes": [...]
    }
  ]
}

Access with: curl -H "Host: site1.local" http://localhost:8080/

🧪 Testing

Run Unit Tests

make test

Test coverage: 103 tests covering request parsing, headers, chunked encoding, multipart, and edge cases.

Manual Testing

# Static files
curl http://localhost:8080/index.html

# Directory listing
curl http://localhost:8080/images/

# File upload (multipart)
curl -F "file=@document.pdf" http://localhost:8080/uploads

# File upload (raw binary)
curl -T document.pdf http://localhost:8080/uploads/document.pdf

# CGI script
curl "http://localhost:8080/cgi-1?name=test"

# File deletion
curl -X DELETE http://localhost:8080/uploads/document.pdf

# Session management
curl -c cookies.txt http://localhost:8080/session
curl -b cookies.txt http://localhost:8080/session  # Views: 2

Load Testing

# Install siege
sudo apt-get install siege

# Test concurrent connections
siege -c 100 -t 30S http://localhost:8080/

# Results will show:
# - Transactions (requests completed)
# - Availability (uptime %)
# - Response time
# - Throughput

📊 Performance Characteristics

Scalability

  • 1000+ concurrent connections on single thread
  • Non-blocking I/O - no thread-per-connection overhead
  • Zero-copy file transfers - OS-level sendfile for static files
  • Memory efficient - ~8KB per connection

Throughput

  • Static files: ~15,000 req/sec (small files)
  • Dynamic content: ~5,000 req/sec (CGI scripts)
  • File uploads: ~500 MB/sec (disk-limited)
  • Keep-alive: Reduces latency by 50%+

Memory Usage

  • Baseline: ~20 MB (JVM + server)
  • Per connection: ~8 KB (buffers only)
  • 1000 connections: ~28 MB total
  • Large uploads: Constant (streams to disk)

Latency

  • Static file (cached): < 1ms
  • Static file (disk): 1-5ms
  • CGI script: 10-100ms
  • File upload (1MB): 10-20ms

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                          Client                              │
└────────────────────────┬────────────────────────────────────┘
                         │ HTTP Request
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                    Server (NIO Selector)                     │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              Event Loop (50ms timeout)               │   │
│  │  - Accept new connections                            │   │
│  │  - Read from sockets                                 │   │
│  │  - Write to sockets                                  │   │
│  │  - Check timeouts                                    │   │
│  │  - Monitor CGI processes                             │   │
│  └──────────────┬───────────────────────────────────────┘   │
└─────────────────┼───────────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────────┐
│                      ClientHandler                           │
│  ┌────────────────┐  ┌────────────────┐  ┌───────────────┐ │
│  │ RequestParser  │→│     Router     │→│   Handler     │ │
│  │ (incremental)  │  │ (route match)  │  │ (process)     │ │
│  └────────────────┘  └────────────────┘  └───────────────┘ │
│           │                   │                    │         │
│           ▼                   ▼                    ▼         │
│  ┌────────────────┐  ┌────────────────┐  ┌───────────────┐ │
│  │  HttpRequest   │  │   RouteConfig  │  │ResponseBuilder│ │
│  └────────────────┘  └────────────────┘  └───────────────┘ │
└─────────────────────────────────────────────────────────────┘
                         │
                         ▼
              ┌─────────────────────┐
              │   Response Sent     │
              └─────────────────────┘

Flow:

  1. Client connects → Server accepts → ClientHandler created
  2. Client sends data → RequestParser parses incrementally
  3. Request complete → Router selects Handler
  4. Handler processes → ResponseBuilder constructs response
  5. Response sent → Connection kept alive or closed

🔐 Security Features

Request Validation

  • Path traversal protection - Canonical path checking
  • Size limits - Configurable max body size (default: 100MB)
  • Timeout protection - 10-second inactivity timeout
  • Method validation - Only allowed methods per route

File Upload Security

  • Filename sanitization - Removes path separators, special chars
  • Directory validation - Files stay within upload directory
  • Field size limits - Form fields limited to 64KB (DoS protection)
  • Total size limits - Enforced during parsing

CGI Security

  • Output size limit - 10MB maximum (prevents memory exhaustion)
  • Execution timeout - 5 seconds maximum
  • Permission checks - Script must have execute permission
  • Path isolation - CGI scripts isolated in ./scripts/

General Security

  • No directory listing by default - Must be explicitly enabled
  • Custom error pages - Don't reveal server internals
  • HttpOnly cookies - JavaScript cannot access session cookies
  • Input validation - All config fields validated at startup

🛠️ Development

Build Commands

make build     # Compile sources
make test      # Run unit tests
make run       # Start server
make clean     # Remove compiled files
make rebuild   # Clean + build

Project Requirements

  • Java 11+ (uses var, new String methods)
  • No external dependencies (pure Java)
  • Linux/Mac/Windows compatible

Adding New Routes

  1. Edit config.json:
{
  "path": "/api",
  "methods": ["GET", "POST"],
  "root": "./www/api",
  "index": "index.html"
}
  1. Restart server:
make run

Creating Custom Handlers

public class MyHandler implements Handler {
    @Override
    public void handle(HttpRequest request, ResponseBuilder response) {
        response.status(HttpStatusCode.OK)
                .contentType("text/plain")
                .body("Hello from custom handler!");
    }
}

Register in Router.java:

if (requestPath.equals("/custom")) {
    return new MyHandler();
}

📚 Documentation

Component Description Link
Request Parser HTTP parsing, chunked encoding, incremental processing → Docs
File Upload Multipart/form-data, binary uploads, disk streaming → Docs
CGI Execution Non-blocking CGI, process monitoring, timeouts → Docs
Router & Handlers Routing logic, handler architecture, virtual hosts → Docs
HTTP Features Redirects, directory listing, sessions, cookies → Docs
Server Core Event loop, NIO selector, connection management → Docs
Configuration JSON parsing, validation, multi-server setup → Docs

🤝 Contributors

This is an educational project showcasing HTTP server implementation without frameworks.

contributors:

yassine elmach

safae beytour

hamza maach

🙏 Acknowledgments

Built as a learning project to understand:

  • HTTP/1.1 protocol internals
  • Java NIO and non-blocking I/O
  • Event-driven architecture
  • Zero-dependency philosophy

Inspired by nginx, Apache HTTP Server, and Node.js's HTTP module.