Skip to content

Volume ITechnology

3.14.1 — From WSGI to ASGI: How Python Web Servers Work ​

You write five lines with FastAPI, run uvicorn main:app, and your function answers HTTP requests from anywhere in the world. Between the network card and your function sit three separate programs, each with one job, joined by one small agreement about how to pass a request along. Knowing those layers is what lets you answer questions like "why did one slow endpoint freeze the whole service?" or "why does my async def route behave differently from my def route?". This page builds the layers from the bottom up. First the older standard, WSGI, and the wall it hit. Then ASGI, the standard that replaced it. Then a raw ASGI application with no framework at all. And finally how Uvicorn, Starlette and FastAPI stack on top of it.

1. The problem every Python web framework must solve ​

A web server's job is to accept TCP connections, read HTTP requests off them (Part 5 explains the wire format) and send responses back. A web framework's job is routing, parsing, validation and your business logic. They are written by different people. So they need an agreed way to hand a request from one to the other. Without one, every framework would need its own server, and every server would only run one framework.

CGI: a new process per request ​

The first answer, in 1993, was CGI, the Common Gateway Interface. For every request, the web server started a new program, passed the request details in environment variables and the body on standard input, and sent back whatever the program printed. It was simple and language-neutral. It was also slow: starting a Python interpreter and importing your code for every single request costs tens of milliseconds before any work happens.

WSGI: one function call per request ​

In 2003, Phillip J. Eby wrote PEP 333, the Web Server Gateway Interface, or WSGI, updated for Python 3 in 2010 as PEP 3333. The idea is one Python function. The server starts your program once, keeps it loaded, and for every request calls your application as a function.

python
import json

def app(environ, start_response):                          # (1)
    path = environ["PATH_INFO"]                            # (2)
    method = environ["REQUEST_METHOD"]
    body = json.dumps({"path": path, "method": method}).encode()
    start_response("200 OK", [("Content-Type", "application/json")])   # (3)
    return [body]                                          # (4)

if __name__ == "__main__":
    from wsgiref.simple_server import make_server          # (5)
    with make_server("127.0.0.1", 8001, app) as server:
        server.serve_forever()
text
$ curl http://127.0.0.1:8001/orders
{"path": "/orders", "method": "GET"}
  • (1) A WSGI application is any callable taking these two arguments.
  • (2) environ is a dict of request details, using CGI's old variable names, such as PATH_INFO and REQUEST_METHOD.
  • (3) start_response is a function the server gives you to send the status line and headers.
  • (4) The body is returned as an iterable of byte strings.
  • (5) The standard library includes a tiny reference server, fine for learning and never for production.

WSGI was a huge success. Django (2005) and Flask (2010) are WSGI frameworks. Gunicorn and uWSGI are WSGI servers. Any framework runs on any server.

The wall: one request holds one worker ​

Look at the shape of WSGI again. Your function is called, and the server waits until it returns. If your code waits 500 milliseconds for a database, the worker thread or process that called it is stuck for those 500 milliseconds, doing nothing, unable to serve anyone else.

Here is that cost measured. A WSGI app and an ASGI app (section 2) each wait 0.5 seconds per request, the way a slow database call would. Twenty clients call each one at the same time, with one worker each.

text
blocking WSGI, 1 worker : 20 requests in 10.1s
async ASGI,    1 worker : 20 requests in 0.6s

The WSGI server handled them one after another: 20 × 0.5 seconds. To serve 20 waiting requests at once, a WSGI deployment needs 20 threads or processes, and to serve 10,000 it needs 10,000. That is the C10k problem, named by Dan Kegel in 1999: how to serve ten thousand connections at once. It got worse when the web grew features where a connection stays open for minutes, such as WebSockets for live chat and server-sent events for live order tracking. WSGI's "call a function, get a response" shape cannot express a connection that stays open and sends messages both ways at all.

2. ASGI: the asynchronous version ​

In 2016, Django core developer Andrew Godwin started Django Channels, to add WebSockets to Django. Out of it came the ASGI specification, the Asynchronous Server Gateway Interface. Its current form, ASGI 3.0, dates from 2019. It keeps WSGI's idea of one agreed callable, but makes it an async function that talks in messages.

python
async def app(scope, receive, send):
    ...

Three arguments.

  1. scope is a dict describing the connection: its type ("http", "websocket" or "lifespan"), method, path, query string, headers and client address. It plays the role of WSGI's environ.
  2. receive is an async function. Awaiting it returns the next incoming message, such as a chunk of the request body, or "the client disconnected".
  3. send is an async function. Awaiting it with a message sends something outgoing, such as "start the response with status 200" or "here is a chunk of the body".

Here is a complete ASGI application with no framework at all.

python
import json

async def app(scope, receive, send):
    if scope["type"] != "http":                                     # (1)
        return
    message = await receive()                                       # (2)
    body = json.dumps({
        "path": scope["path"],
        "method": scope["method"],
        "got_body": message["body"].decode(),
    }).encode()
    await send({"type": "http.response.start", "status": 200,       # (3)
                "headers": [(b"content-type", b"application/json")]})
    await send({"type": "http.response.body", "body": body})        # (4)
text
$ uvicorn asgi_app:app --port 8002
$ curl -X POST http://127.0.0.1:8002/orders -d '{"sku":"mug"}'
{"path": "/orders", "method": "POST", "got_body": "{\"sku\":\"mug\"}"}
  • (1) One callable handles every kind of connection. This one only speaks HTTP.
  • (2) Reading the body is an await. While the client is still sending a large upload, this coroutine is paused and the server's event loop serves other connections (3.13.15).
  • (3) The response starts with one message holding the status and headers. Header names and values are bytes, exactly as they travel on the wire.
  • (4) The body follows in one or more messages. A body sent in many messages is how streaming responses work (3.14.8).

There is no magic: drive it by hand ​

Because an ASGI application is just an async function, you can call it yourself with a fake receive and send. This is exactly what a server does, minus the sockets.

python
import asyncio
from asgi_app import app

async def main():
    scope = {"type": "http", "method": "POST", "path": "/orders",
             "headers": [], "query_string": b""}
    inbox = [{"type": "http.request", "body": b'{"sku": "mug"}', "more_body": False}]

    async def receive():                 # (1)
        return inbox.pop(0)

    async def send(message):             # (2)
        print(message)

    await app(scope, receive, send)

asyncio.run(main())
text
{'type': 'http.response.start', 'status': 200, 'headers': [(b'content-type', b'application/json')]}
{'type': 'http.response.body', 'body': b'{"path": "/orders", "method": "POST", "got_body": "{\\"sku\\": \\"mug\\"}"}'}
  • (1) Our receive hands over the request body as one message.
  • (2) Our send just prints what the app wanted to send to the client.

Figure 1 shows the message exchange for one HTTP request between a server and an ASGI app.

server (Uvicorn)ASGI app① app(scope, receive, send)② await receive(){"type": "http.request", "body": …}③ send http.response.start (status, headers)④ send http.response.body (one or many)
Figure 1 — One HTTP request in ASGI. The server calls the app once per connection. The app pulls incoming messages with receive and pushes outgoing ones with send. Every arrow is an await, so the server's event loop is free between them.

The same three-argument shape handles a WebSocket: scope["type"] is "websocket", and the app keeps calling receive and send for as long as the conversation lasts. It also handles the server's lifespan: one special connection at start-up and shutdown, used to open and close database pools (3.14.5). One interface covers every case WSGI could not.

3. The three layers: Uvicorn, Starlette, FastAPI ​

Writing raw ASGI for a real service would be tedious: parsing query strings, matching URL paths, decoding JSON, building headers. So the work is split into layers, each one an ASGI application wrapping the next. Figure 2 shows the stack.

your function: async def get_order(order_id: int)business logic onlyFastAPIreads your signature · validates with Pydantic · dependencies · OpenAPI docsStarletterouting · Request/Response objects · middleware · WebSockets · thread poolASGI: app(scope, receive, send)Uvicorn (the server)sockets · HTTP parsing (httptools) · event loop (uvloop) · process managementoperating system: TCP connections, epoll
Figure 2 — The FastAPI stack. Each layer does one job and talks to the next through the same ASGI interface. You write only the top box.

Uvicorn: the server ​

Uvicorn, released by Tom Christie's company Encode in 2017, is an ASGI server. Its jobs are the ones a server always had:

  1. open the listening socket and accept TCP connections;
  2. parse raw HTTP bytes into a scope dict and body messages, using httptools, a fast C parser taken from Node.js;
  3. run the event loop, using uvloop when it is installed (3.13.15);
  4. call your ASGI app once per request, and turn its send messages back into HTTP bytes.

Other ASGI servers exist, such as Hypercorn and Granian, and your app runs unchanged on any of them. That is the point of a standard.

Starlette: the toolkit ​

Starlette, also by Tom Christie, released in 2018, is a lightweight ASGI framework. It gives you Request and Response objects instead of raw message dicts, URL routing, middleware, WebSockets, background tasks, and a thread pool for running ordinary blocking functions. It is a complete framework on its own, and it is the engine room under FastAPI.

FastAPI: the layer that reads your function ​

FastAPI was released by Sebastián Ramírez in December 2018. He had spent years building APIs with Flask and other frameworks, adding validation, serialisation and documentation by hand to each one. His insight was that Python 3.6's type hints already said what each parameter should be. So FastAPI reads your function's signature and builds everything else from it:

  • where each parameter comes from: the path, the query string, the body, a header;
  • how to convert and validate it, using Pydantic (3.14.2);
  • the dependencies to run before your function (3.14.4);
  • how to turn your return value into JSON;
  • an OpenAPI description of the whole API, which powers the interactive documentation page at /docs.

FastAPI does not replace Starlette. It is Starlette, with that extra layer on top.

python
from fastapi import FastAPI
from starlette.applications import Starlette

print([cls.__module__ + "." + cls.__name__ for cls in FastAPI.__mro__[:2]])
app = FastAPI()
print(isinstance(app, Starlette), callable(app))
text
['fastapi.applications.FastAPI', 'starlette.applications.Starlette']
True True

FastAPI is a subclass of Starlette, and an instance is callable. It is an ASGI application, exactly like the twelve-line function in section 2.

Proof: drive FastAPI by hand ​

Since a FastAPI app is an ASGI callable, we can call it exactly like our raw app, with no server.

python
import asyncio
from fastapi import FastAPI

app = FastAPI()

@app.get("/orders/{order_id}")
async def get_order(order_id: int):
    return {"order_id": order_id, "status": "paid"}

async def call(path):
    scope = {"type": "http", "asgi": {"version": "3.0"}, "http_version": "1.1",
             "method": "GET", "path": path, "raw_path": path.encode(), "root_path": "",
             "scheme": "http", "query_string": b"", "headers": [(b"host", b"shop.local")],
             "client": ("127.0.0.1", 5000), "server": ("shop.local", 80)}

    async def receive():
        return {"type": "http.request", "body": b"", "more_body": False}

    async def send(message):
        print(message)

    await app(scope, receive, send)

asyncio.run(call("/orders/42"))         # (1)
asyncio.run(call("/orders/abc"))        # (2)
text
{'type': 'http.response.start', 'status': 200, 'headers': [(b'content-length', b'31'), (b'content-type', b'application/json')]}
{'type': 'http.response.body', 'body': b'{"order_id":42,"status":"paid"}'}
{'type': 'http.response.start', 'status': 422, 'headers': [(b'content-length', b'153'), (b'content-type', b'application/json')]}
{'type': 'http.response.body', 'body': b'{"detail":[{"type":"int_parsing","loc":["path","order_id"],"msg":"Input should be a valid integer, unable to parse string as an integer","input":"abc"}]}'}
  • (1) Starlette's router matched /orders/{order_id}. FastAPI saw the hint order_id: int, converted the text "42" to the integer 42, called your function, and turned the returned dict into JSON with the right headers.
  • (2) "abc" is not an integer. FastAPI never called your function. It answered 422 Unprocessable Content with a precise description of which value failed and why. You wrote no validation code at all.

Everything on the next nine pages is a closer look at what happens between those two send calls.

4. One request, end to end ​

Put the layers together and follow a request for GET /orders/42 through a running service.

  1. The client opens a TCP connection to the server's port, and the kernel accepts it (Part 5).
  2. Uvicorn's event loop is told the socket has data. It reads the bytes and parses the request line and headers into a scope.
  3. Uvicorn calls await app(scope, receive, send), which is your FastAPI instance.
  4. The request passes through every middleware layer, outermost first (3.14.5).
  5. Starlette's router compares the path with each registered route and finds /orders/{order_id}.
  6. FastAPI extracts and validates the parameters, runs any dependencies, and calls your function. An async def function is awaited on the event loop. A plain def function is sent to a thread pool, so it cannot block the loop (3.14.3 explains why that matters).
  7. Your return value is validated against the response model, converted to JSON, and wrapped in a response.
  8. The response travels back out through the middleware, innermost first, and becomes send messages.
  9. Uvicorn writes the bytes to the socket, and keeps the connection open for the client's next request if HTTP keep-alive allows.

While any one request is paused at an await, in steps 6 and 7 for example while waiting for a database, the same Uvicorn process is busy moving dozens or thousands of other requests through the same steps. That is the measured difference between 10.1 seconds and 0.6 seconds in section 1.

What the interviewer will push on ​

"What is the difference between WSGI and ASGI?" WSGI is a synchronous callable, app(environ, start_response), which returns a whole response and occupies a worker until it does. ASGI is an async callable, app(scope, receive, send), which exchanges messages, so one process can interleave thousands of connections and support long-lived WebSockets and lifespan events. The tell is explaining why WSGI cannot do WebSockets: its shape is one call, one response.

"What do Uvicorn, Starlette and FastAPI each do?" Uvicorn is the ASGI server: sockets, HTTP parsing and the event loop. Starlette is the ASGI toolkit: routing, requests, responses, middleware and the thread pool. FastAPI subclasses Starlette and adds signature-driven validation with Pydantic, dependency injection and OpenAPI generation. A weak answer treats them as one thing.

"Is FastAPI fast because it is asynchronous?" Partly. Async lets one process overlap many waits, which matters for I/O-bound APIs. Its benchmark speed also comes from Uvicorn's C-based HTTP parser and uvloop, and from Pydantic's Rust core. It does nothing for CPU-bound handlers, which still need more processes.

"Can a Django or Flask app run on an ASGI server?" Django has supported ASGI natively since version 3.0. A WSGI app can be wrapped with an adapter that runs it in a thread pool, so it works but gets none of the async benefits.

Something to volunteer that nobody asks for: a FastAPI app is just an ASGI callable, so you can drive it by hand with a fake scope, receive and send, and see the exact messages it emits. That is how you prove to yourself, and to an interviewer, that there is no magic between the socket and your function.

Recall

  • CGI started a process per request. WSGI (PEP 333, 2003) calls app(environ, start_response) once per request in a long-running process. Django, Flask and Gunicorn are WSGI. A waiting request occupies its worker, which is the C10k problem, and WSGI cannot express WebSockets.
  • ASGI (Andrew Godwin, 2016, version 3.0 in 2019) is async def app(scope, receive, send). scope describes the connection, receive pulls incoming messages, and send pushes outgoing ones: http.response.start, then http.response.body. It covers HTTP, WebSockets and lifespan.
  • Uvicorn is the server: sockets, httptools, uvloop. Starlette is the toolkit: routing, Request/Response, middleware, thread pool. FastAPI (Sebastián Ramírez, 2018) subclasses Starlette and reads your function signature to validate with Pydantic, inject dependencies and generate OpenAPI.
  • A FastAPI app is an ASGI callable. You can drive it by hand. Invalid input gets a 422 before your code runs.

Self-test: Why does a blocking WSGI worker serve 20 slow requests in 10 seconds while one ASGI worker serves them in 0.6? What are the three arguments of an ASGI app, and what flows through each? Which layer parses HTTP bytes, which matches URLs, and which converts "42" into 42?

Quiz Bank ​

FoundationalWhy are ASGI response headers lists of byte pairs instead of a dict of strings?

Because HTTP headers on the wire are bytes, and the protocol allows the same header name to appear more than once, for example several Set-Cookie headers. A dict cannot hold duplicate keys, and converting to strings would force a text encoding onto data that HTTP defines as bytes. A list of (name, value) byte pairs represents the response exactly as it will be sent, and frameworks such as Starlette build the friendlier header objects on top.

AppliedA team moves a Flask app to FastAPI but keeps the same synchronous database driver and requests library. Will it handle more concurrent traffic?

Only if they keep their endpoints as plain def functions. FastAPI then runs each one in Starlette's thread pool, so behaviour is similar to a threaded WSGI server, bounded by the pool size. If they convert endpoints to async def but keep calling the blocking driver and requests, each call blocks the event loop and the whole worker serves one request at a time, which is worse than before. The real gain needs async libraries all the way down: an async database driver and an async HTTP client such as httpx.AsyncClient, inside async def endpoints.

InterviewExplain what happens between the socket and your FastAPI function for one request.

Uvicorn's event loop learns that the socket is readable, reads the bytes, and parses the request line and headers with httptools into an ASGI scope. It calls the FastAPI app with scope, receive and send. The request passes through the middleware stack. Starlette's router matches the path to a route. FastAPI uses the plan it built at start-up from your function's signature to extract path, query, header and body values, validate and convert them with Pydantic, and resolve dependencies. It then awaits your async def function, or runs a def function in the thread pool. The return value is validated against the response model, serialised to JSON, and sent back through the middleware as http.response.start and http.response.body messages, which Uvicorn writes to the socket.

StaffYour service must support 5,000 concurrent WebSocket connections for live order tracking, alongside a normal REST API. How does the ASGI model shape your design?

ASGI lets one process hold thousands of idle WebSocket connections cheaply, since each is a paused coroutine waiting on receive. So a few Uvicorn worker processes can carry 5,000 connections, as long as no handler blocks the loop. The design questions move elsewhere. Connections are pinned to one process, so an order update produced anywhere must reach the right process: use a shared publish-subscribe channel such as Redis, with each process subscribing and forwarding to its own sockets. Load balancers need sticky or WebSocket-aware routing and long idle timeouts. Deploys must drain connections gracefully, and clients must reconnect with backoff. Consider separating the WebSocket tier from the REST tier, so a slow REST endpoint or a deploy of one does not disturb the other.

Next: FastAPI validated "abc" and returned a 422 without any code from you. That came from Pydantic. 3.14.2 opens up Pydantic: how it validates and converts data, every kind of validator, serialisation, and the Rust engine that makes it fast.

Combine chapters into one PDF

Pick the chapters you want. They print in the order you pick them.

Volume I — Technology
Part 0 — Retention & Notation
Part 1 — Foundations of Computation
Part 2 — Operating Systems
2.1 The Kernel
2.2 Processes
2.3 Threads & Scheduling
2.4 Concurrency Under the Hood
2.5 Memory Management
2.6 File Systems
2.7 Input/Output
2.8 Linux for Engineers
2.9 Windows & macOS in Practice
Part 3 — Languages, Compilers & Runtimes
3.6 JavaScript & V8
3.7 TypeScript
3.8 Node.js Internals
3.13 Python & CPython
3.14 FastAPI & Production Python
Part 4 — Data Structures & Algorithms
4.0 Classic Problems — Before NeetCode
4.4 Arrays & Hashing — Problems
4.5 Two Pointers
4.6 Sliding Window
4.8 Stack — Problems
4.9 Linked List — Problems
4.11 Binary Search — Problems
4.13 Trees
4.14 Tree — Problems
4.15 Trie — Problems
4.17 Heap — Problems
4.18 Backtracking — Problems
4.19 Graphs
4.20 Graph — Problems
4.21 Advanced Graph — Problems
4.23 1-D DP — Problems
4.24 2-D DP — Problems
4.26 Greedy — Problems
4.27 Interval — Problems
4.28 Math & Geometry — Problems
4.30 Bit Manipulation — Problems
Part 5 — Networking & the Web
5.3 IP
5.4 Transport
5.6 HTTP
Part 6 — Frontend Engineering
6.1 Browser Internals
6.2 HTML & CSS Mastery
6.3 JavaScript in the Browser
6.4 React, from First Component to Full Shop
6.5 Frameworks & Rendering
6.8 UI Engineering & Patterns
Part 7 — Databases & Storage
7.2 SQL Mastery
7.3 Storage Engine Internals
7.4 Transactions
7.5 NoSQL Taxonomy
7.8 Analytics & Big Data
Part 8 — Security, Identity & Cryptography
8.2 Cryptography
8.3 Protocols of Trust
8.4 Identity: AuthN & AuthZ
8.5 Application Security
8.6 Infrastructure Security
Part 9 — Software Design (LLD)
9.2 OOP Foundations
9.3 Design Principles
9.4 Design Patterns
9.5 Concurrency
9.6 API Design
9.7 LLD Interview Machines
9.9 Node/Express Production Playbook
Part 10 — Distributed Systems & HLD
10.7 Consistency & Consensus
10.8 Messaging & Microservices
10.14 Caching
Building blocks from the design seat
Part 11 — System Design Case Studies
Part 12 — AI & ML Engineering
12.1 What AI Engineering Is
12.2 The Math You Need
12.3 Classical Machine Learning
12.4 Data for ML
12.5 Deep Learning
12.6 Embeddings & Vector Search
12.7 Transformers & LLMs
12.8 Building with LLMs
12.9 Retrieval-Augmented Generation
12.10 Agents
12.11 Adapting Models
12.12 Production AI
12.13 Multimodal AI
12.14 AI Security & Governance
12.15 Case Studies & Capstone
Part 13 — Cloud, DevOps & Infrastructure
13.11 Git, from First Commit to Team Workflow
Part 14 — Containers: Docker & Kubernetes
14.1 Foundations
14.2 Docker
14.3 Kubernetes
14.4 Kubernetes on Azure
Part 15 — The Craft & Career
Nothing picked yet