🚧 WORK IN PROGRESS - Educational Project 🚧
A production-grade HTTP/1.1 web server written entirely in x86-64 assembly language (NASM syntax) for Linux. This is a learning project to understand low-level networking, HTTP protocol implementation, and system programming without any frameworks or high-level abstractions.
This project aims to build a fully-featured HTTP server from scratch using only:
- Raw Linux syscalls (no libc)
- x86-64 assembly language
- NASM assembler
- GNU ld linker
No dependencies. No frameworks. Just syscalls and registers.
Project structure - Complete
Build system - Working
Implementation - In progress (skeleton code only)
The project currently builds successfully but contains only stub functions. All modules are marked with TODO comments indicating what needs to be implemented.
- Low-level networking: TCP sockets, epoll, non-blocking I/O
- HTTP protocol: Request parsing, response building, headers, status codes
- System programming: Linux syscalls, process management, memory management
- Assembly language: x86-64 instructions, calling conventions, stack management
- Concurrency: Thread pools, connection pooling, async I/O
- Security: TLS/SSL, authentication, input validation
- TCP socket server with epoll for async I/O
- HTTP/1.1 protocol support (GET, POST, PUT, DELETE, etc.)
- URL routing with pattern matching (
/users/:id) - Query parameter parsing (
?key=value&foo=bar) - JSON request/response handling
- Middleware chain for request processing
- Keep-alive connections
- Chunked transfer encoding
- Multipart form data (file uploads)
- HTTPS/TLS support (via OpenSSL wrapper)
- JWT authentication
- CORS handling
- Rate limiting
- OpenAPI/Swagger documentation
- Thread pool for concurrent requests
- Connection pooling
- Error handling and logging
Educational value:
- Forces deep understanding of how HTTP servers actually work
- No "magic" - every byte is your responsibility
- Learn exactly what high-level frameworks do under the hood
- Understand performance implications at the lowest level
Not recommended for production. Use ASP.NET, Express, FastAPI, etc. for real applications.
http-server-asm/
├── Makefile # Build system
├── README.md # This file
├── src/
│ ├── constants.inc # Syscall numbers, structs, defines
│ ├── core/ # Core server logic
│ │ ├── main.asm # Entry point & event loop
│ │ ├── socket.asm # Socket operations (create, bind, listen, accept)
│ │ ├── epoll.asm # Epoll for async I/O
│ │ ├── thread_pool.asm # Worker thread pool
│ │ └── connection_pool.asm # Connection management
│ ├── http/ # HTTP protocol implementation
│ │ ├── http_parser.asm # Parse HTTP requests
│ │ ├── http_response.asm # Build HTTP responses
│ │ ├── chunked_encoding.asm
│ │ ├── keep_alive.asm
│ │ ├── multipart_parser.asm
│ │ ├── router.asm # URL routing & pattern matching
│ │ ├── query_parser.asm # Parse query strings
│ │ ├── url_decode.asm # URL encoding/decoding
│ │ └── middleware.asm # Middleware chain
│ ├── security/ # Security features
│ │ ├── tls_wrapper.asm # TLS/SSL (OpenSSL wrapper)
│ │ ├── jwt.asm # JWT token handling
│ │ ├── auth_middleware.asm
│ │ ├── session.asm
│ │ ├── rate_limiter.asm
│ │ ├── cors.asm
│ │ └── xss_filter.asm
│ ├── data/ # Data handling
│ │ ├── json_parser.asm # Parse JSON
│ │ ├── json_builder.asm # Build JSON responses
│ │ ├── json_validator.asm
│ │ └── sqlite_wrapper.asm # SQLite database wrapper
│ ├── utils/ # Utility functions
│ │ ├── string_utils.asm # String operations
│ │ ├── memory_pool.asm # Custom memory allocator
│ │ ├── datetime.asm # Date/time handling
│ │ ├── base64.asm # Base64 encoding/decoding
│ │ ├── hash_table.asm # Hash table for headers/params
│ │ ├── error_handler.asm # Error handling
│ │ └── logger.asm # Logging to file/syslog
│ ├── api/ # API documentation
│ │ ├── swagger_ui.asm # Serve Swagger UI
│ │ ├── openapi_builder.asm # Generate OpenAPI spec
│ │ └── health_check.asm # Health check endpoint
│ └── handlers/ # Example HTTP handlers
│ ├── get_users.asm # GET /users
│ ├── post_user.asm # POST /users
│ └── get_health.asm # GET /health
└── build/ # Compiled .o files and binary
- OS: Linux (x86-64)
- Assembler: NASM 2.14+
- Linker: GNU ld (binutils)
- Optional: GDB for debugging
sudo apt install nasmsudo pacman -S nasmsudo dnf install nasm# Compile the project
make
# Clean build artifacts
make clean
# Run the server (when implemented)
make run- Socket creation, binding, listening
- Accept connections in a loop
- Send hardcoded HTTP response ("Hello World")
- Basic request parsing (method + path)
- Full HTTP request parser (headers + body)
- HTTP response builder with proper status codes
- URL routing (exact match)
- Query parameter parsing
- Epoll for async I/O
- Thread pool for handling requests
- Connection pooling
- Keep-alive connections
- JSON parsing and building
- Chunked transfer encoding
- Multipart form data (file uploads)
- Pattern matching in routes (
/users/:id)
- HTTPS/TLS support
- JWT authentication
- CORS handling
- Rate limiting
- Input validation (XSS, SQL injection prevention)
- Error handling & logging
- Graceful shutdown
- Health check endpoint
- Swagger/OpenAPI documentation
- Metrics & monitoring
| Component | Lines of Assembly | Difficulty |
|---|---|---|
| Basic socket server | ~200 | Easy |
| HTTP parser | ~800 | Medium |
| HTTP response builder | ~300 | Medium |
| Router | ~400 | Medium |
| JSON parser | ~1,200 | Hard |
| Epoll + threading | ~700 | Hard |
| TLS wrapper | ~500 | Medium (using OpenSSL) |
| Full production server | ~17,000+ | Very Hard |
Time estimate: 6-12 months for one developer to complete all features.
- x86-64 Linux Syscall Reference
- HTTP/1.1 RFC 2616
- NASM Documentation
- x86-64 Assembly Programming
- Linux System Call Interface
This is purely educational. For reference:
| Implementation | Lines of Code | Development Time |
|---|---|---|
| This project (Assembly) | ~17,000 | 6-12 months |
| ASP.NET Core | ~30 | 1 day |
| Express.js | ~20 | 1 day |
| FastAPI | ~25 | 1 day |
Performance: Raw assembly can theoretically be faster, but ASP.NET Kestrel is already highly optimized C++ under the hood. Real-world gain would be minimal (~5-10%) while losing months of development time.
This is a personal learning project. Feel free to fork and implement your own features, but pull requests are not being accepted as the goal is self-education.
MIT License - Do whatever you want with this code.
This is NOT production-ready code.
Use real web frameworks for actual applications.
This project exists purely for educational purposes.
If you want to learn low-level systems programming and understand how HTTP servers work at the most fundamental level, this project is for you. If you want to ship a web application, use ASP.NET, Express, Django, or any other mature framework.
Author: Learning x86-64 assembly the hard way
Status: Work in progress
Target: Full HTTP/1.1 server with modern features