kludex/starlette

The little ASGI framework that shines. 🌟

Structural Verdict

How Data Flows Through the System

HTTP requests flow through middleware stack, get routed to endpoints, and responses flow back through middleware

1. ASGI Receive — Incoming HTTP/WebSocket connection received from ASGI server
2. Middleware Processing — Request passes through middleware stack (errors, auth, CORS)
3. Route Matching — Router matches URL path to endpoint using path patterns and convertors
4. Endpoint Execution — Function or class-based endpoint processes request and returns response
5. Background Tasks — Optional async tasks scheduled to run after response is sent
6. Response Middleware — Response flows back through middleware stack in reverse order
7. ASGI Send — Final response sent to client via ASGI server

System Behavior

How the system actually operates at runtime — where data accumulates, what loops, what waits, and what controls what.

Data Pools

Feedback Loops

• Exception Handling Loop (retry, balancing) — Trigger: Unhandled exception in endpoint or middleware. Action: Look up exception handler and generate error response. Exit: Error response sent or re-raise if no handler.

Delays & Async Processing

• Background Task Execution (async-processing, ~variable) — Tasks run after response is sent, allowing cleanup without blocking client
• Threadpool Operations (async-processing, ~variable) — Sync functions run in thread pool to avoid blocking event loop

Control Points

• Debug Mode (feature-flag) — Controls: Whether detailed tracebacks are shown in error responses. Default: false
• CORS Configuration (runtime-toggle) — Controls: Cross-origin request handling policies and headers. Default: null

Technology Stack

Key Components

• Starlette (class) — Main application class that combines routing, middleware, and ASGI protocol handling starlette/applications.py
• Router (class) — Handles URL pattern matching and dispatches requests to appropriate endpoints starlette/routing.py
• BaseMiddleware (class) — Abstract base class for creating middleware that processes requests and responses starlette/middleware/base.py
• Request (class) — Wraps ASGI HTTP scope and provides methods for accessing request data, form parsing, JSON starlette/requests.py
• Response (class) — Base response class with status codes, headers, and async content streaming starlette/responses.py
• WebSocket (class) — Handles WebSocket connections with methods for accepting, sending, receiving messages starlette/websockets.py
• HTTPEndpoint (class) — Class-based endpoint that dispatches HTTP methods to corresponding handler methods starlette/endpoints.py
• BackgroundTasks (class) — Manages async tasks that run after the response is sent to the client starlette/background.py
• ExceptionMiddleware (class) — Catches and handles exceptions, mapping them to appropriate HTTP error responses starlette/middleware/exceptions.py
• CORSMiddleware (class) — Handles Cross-Origin Resource Sharing headers and preflight requests starlette/middleware/cors.py
• FormParser (class) — Parses multipart form data and URL-encoded forms into structured data starlette/formparsers.py
• Config (class) — Environment variable configuration management with type conversion and validation starlette/config.py

Configuration

starlette/formparsers.py (python-dataclass)

• field_name (str, unknown) — default: ""
• data (bytearray, unknown) — default: field(default_factory=bytearray)
• item_headers (list[tuple[bytes, bytes]], unknown) — default: field(default_factory=list)

tests/test_responses.py (python-dataclass)

• headers (dict[bytes, bytes], unknown)
• data (bytes, unknown)

Related Repository Repositories

Frequently Asked Questions

Analyzed on March 31, 2026 by CodeSea. Written by Karolina Sarna.