Building a Minimal Async Python Web Framework from Scratch

Scope

The framework aims to handle the request‑response cycle, authentication, routing, and basic HTTP processing without providing templates, database integration, or full WSGI support.

Features

Process HTTP GET and POST requests.

Support asynchronous operations using Python 3 asyncio.

Simple routing logic with parameter extraction.

User‑level API similar to other micro‑frameworks.

Authentication support.

Limitations

Only a small subset of HTTP/1.1 is supported.

No support for transfer‑encoding, HTTP authentication, content‑encoding (e.g., gzip), persistent connections, MIME detection, WSGI, or databases.

Design Overview

The design is split into several loosely coupled parts: a TCP listener, a parser that turns raw bytes into request objects, a router that maps URLs to handler functions, and an App class that ties everything together.

Asynchronous Connection Simulation

Each HTTP request is handled on its own TCP connection to simplify simulation. The asyncio‑stream module is used for reading and writing data.

HTTPConnection Details

An HTTPConnection instance reads data incrementally with asyncio.StreamReader, parses it into a Request object, generates a Response, and sends it back via asyncio.StreamWriter. It also manages timeouts and error handling.

Timeout Mechanism

Three functions handle timeouts: one sends an error response and closes the connection, another cancels the current timeout, and a third schedules a new timeout using BaseEventLoop.call_later. The timeout is reset each time data is received.

Creating Connections

The HTTPServer class stores configuration (parser, router, event loop) and creates HTTPConnection objects for each incoming TCP connection via asyncio.start_server.

Request Parsing

A lightweight http_parser module provides a parse_into function that fills a Request object from a byte buffer. It parses the request line, headers (including Content‑Length), and optional body.

Routing

The Router stores path‑to‑function mappings. add_route compiles route patterns into regular expressions, stores them in a dictionary, and later matches incoming URLs to retrieve the appropriate handler.

Assembling Everything

The App class aggregates configuration and starts the server by creating an HTTPServer instance and passing its handle_connection method to asyncio.start_server. This ties together parsing, routing, and response generation.

Summary

The resulting framework consists of roughly 320 lines of code (about 540 including tests) and demonstrates how core web‑framework features can be built from scratch. It lacks templates, authentication, and database layers, but serves as a practical illustration of backend architecture, dependency injection, and test‑driven development.