Skip to content

Python Web Servers, the Kernel and Production Networking


The main idea

Most beginners think that:

from fastapi import FastAPI

or:

from flask import Flask

is already a:

web server

But that is NOT the case.


Framework ≠ Server

FastAPI, Flask, Django — are:

application frameworks

They: - describe routes, - business logic, - request handlers, - middleware.

But they do NOT: - open TCP sockets directly, - do NOT call accept(), - do NOT manage epoll/select, - do NOT work with the kernel networking stack directly.


Who actually works with the network?

The real networking is done by:

  • Gunicorn
  • Uvicorn
  • Hypercorn
  • uWSGI
  • Daphne

They are the ones that: - open sockets, - bind() to a port, - listen(), - accept(), - recv(), - send().


Architecturally

Python App
    ↓
WSGI / ASGI
    ↓
Python Server
    ↓
OS Kernel
    ↓
TCP/IP Stack
    ↓
Network

What is WSGI?

WSGI =

Web Server Gateway Interface

The old synchronous standard for Python web.


The WSGI model

HTTP Request
↓
1 worker/thread/process
↓
Framework handles request
↓
HTTP Response

Frameworks that work through WSGI

Framework Type
Flask minimal WSGI
Django (classic) full-stack WSGI

What is ASGI?

ASGI =

Asynchronous Server Gateway Interface

The new async Python standard.


ASGI supports

  • asyncio
  • WebSocket
  • long connections
  • streaming
  • async I/O
  • event loops

Frameworks that work through ASGI

Framework Type
FastAPI modern ASGI
Starlette lightweight ASGI
Quart async Flask
aiohttp async HTTP
modern Django async hybrid

The most important systems-thinking point

The framework:

defines the application logic

The server:

defines the networking model


What does Gunicorn actually do?

Gunicorn: - socket() - bind() - listen() - fork workers - accept() - recv() - passes the request to the Flask/Django app


Gunicorn lifecycle

socket()
↓
bind()
↓
listen()
↓
fork workers
↓
accept()
↓
recv()
↓
WSGI app
↓
response

What does Uvicorn actually do?

Uvicorn is an async ASGI server.

It: - uses an event loop, - epoll/select, - non-blocking sockets, - asyncio tasks.


Uvicorn lifecycle

socket()
↓
epoll/select
↓
event loop
↓
async tasks
↓
ASGI app
↓
await recv/send

Production Architecture

A typical production setup for FastAPI:

                 INTERNET
                      │
══════════════════════╪══════════════════════
                      ▼
               ┌────────────┐
               │   Nginx    │
               │ :80 / :443 │
               └─────┬──────┘
                     │ reverse proxy
                     ▼
          ┌─────────────────────┐
          │     Uvicorn         │
          │   ASGI Server       │
          └─────┬──────┬────────┘
                │      │
         Worker 1   Worker 2
                │      │
                ▼      ▼
             FastAPI App

For Django

Browser
↓
Nginx
↓
Gunicorn
↓
Django

What does Nginx do?

Nginx: - listens on 80/443, - TLS/HTTPS, - reverse proxy, - buffering, - static files, - load balancing, - keep-alive connections.


Why NOT run FastAPI/Flask directly?

Because:

app.run()

is a:

development server

A development server does NOT properly handle

  • multiprocessing
  • worker management
  • graceful shutdown
  • production buffering
  • efficient concurrency
  • load balancing
  • advanced socket handling

The full Mental Model

        USER SPACE
═══════════════════════════════════

 FastAPI / Django / Flask
            │
            ▼
    Uvicorn / Gunicorn
            │
            ▼
════════ syscall boundary ════════

         OS KERNEL
═══════════════════════════════════

 TCP Stack
 Socket Buffers
 Scheduler
 epoll/select
 File Descriptors

═══════════════════════════════════

        NETWORK LAYER
═══════════════════════════════════

 TCP/IP
 Ethernet
 Wi-Fi
 Routers
 Internet

What does recv() mean in a production server?

When Uvicorn or Gunicorn does:

sock.recv(1024)

it means:

crossing the syscall boundary into the kernel

Then the kernel:

  • checks the receive buffer,
  • if there are bytes → returns the data,
  • if there are no bytes → blocks the thread/process.

Blocking Model

Python Process
↓
recv()
↓
Kernel checks socket buffer
↓
buffer empty
↓
process asleep
↓
packet arrives
↓
kernel wakeup
↓
recv() returns bytes

The most important conclusion

A Python framework is only the application layer.

The real networking: - sockets, - TCP, - buffers, - event loops, - epoll/select, - scheduler, - kernel wakeups

is done by: - Gunicorn, - Uvicorn, - the kernel networking stack.

🔥 1. Flask / Django (WSGI) Architecture

flowchart TB

    Browser["🌍 Browser"]

    Nginx["Nginx<br>Reverse Proxy"]

    Gunicorn["Gunicorn<br>WSGI Server"]

    Django["Django / Flask<br>WSGI App"]

    Browser -->|"HTTP Request"| Nginx

    Nginx -->|"proxy_pass"| Gunicorn

    Gunicorn -->|"WSGI call"| Django

    Django --> Gunicorn

    Gunicorn --> Nginx

    Nginx --> Browser

    classDef step     fill:#eceff1,stroke:#546e7a,stroke-width:1px;
    classDef success  fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    classDef warning  fill:#fff8e1,stroke:#e65100,stroke-width:2px;

    class Browser,Gunicorn step;
    class Nginx warning;
    class Django success;

🔥 2. FastAPI + Uvicorn (ASGI)

flowchart TB

    Browser["🌍 Browser"]

    Nginx["Nginx<br>:80 / :443"]

    Uvicorn["Uvicorn<br>ASGI Server"]

    Loop["asyncio Event Loop"]

    FastAPI["FastAPI<br>ASGI App"]

    Browser --> Nginx

    Nginx -->|"reverse proxy"| Uvicorn

    Uvicorn --> Loop

    Loop --> FastAPI

    classDef step     fill:#eceff1,stroke:#546e7a,stroke-width:1px;
    classDef decision fill:#e3f2fd,stroke:#1565c0,stroke-width:2px;
    classDef success  fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    classDef warning  fill:#fff8e1,stroke:#e65100,stroke-width:2px;

    class Browser,Uvicorn step;
    class Nginx warning;
    class Loop decision;
    class FastAPI success;

🔥 3. Full Production Networking Stack

flowchart TB

    subgraph USER["USER SPACE"]
        App["FastAPI / Django / Flask"]
        Server["Uvicorn / Gunicorn"]
    end

    subgraph KERNEL["KERNEL SPACE"]
        TCP["TCP/IP Stack"]
        Buffers["Socket Buffers"]
        Scheduler["Scheduler"]
        Epoll["epoll/select"]
    end

    NIC["🌐 NIC Driver"]

    Internet["🌍 Internet"]

    App --> Server

    Server -->|"syscalls"| TCP

    TCP --> Buffers
    TCP --> Scheduler
    TCP --> Epoll

    Buffers --> NIC

    NIC --> Internet

    classDef step     fill:#eceff1,stroke:#546e7a,stroke-width:1px;
    classDef success  fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    classDef warning  fill:#fff8e1,stroke:#e65100,stroke-width:2px;

    class App,Server success;
    class TCP,Buffers,Scheduler,Epoll warning;
    class NIC,Internet step;

🔥 4. Gunicorn Worker Model

flowchart TB

    Master["Gunicorn Master Process"]

    W1["Worker 1"]
    W2["Worker 2"]
    W3["Worker 3"]

    Flask["Flask/Django App"]

    Master --> W1
    Master --> W2
    Master --> W3

    W1 --> Flask
    W2 --> Flask
    W3 --> Flask

    classDef step     fill:#eceff1,stroke:#546e7a,stroke-width:1px;
    classDef success  fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    classDef warning  fill:#fff8e1,stroke:#e65100,stroke-width:2px;

    class Master warning;
    class W1,W2,W3 step;
    class Flask success;

🔥 5. Uvicorn Event Loop Model


flowchart LR

    EventLoop["🔄 asyncio Event Loop"]

    Socket1["Socket A"]
    Socket2["Socket B"]
    Socket3["Socket C"]

    FastAPI["FastAPI ASGI App"]

    EventLoop --> Socket1
    EventLoop --> Socket2
    EventLoop --> Socket3

    Socket1 --> FastAPI
    Socket2 --> FastAPI
    Socket3 --> FastAPI

    classDef step     fill:#eceff1,stroke:#546e7a,stroke-width:1px;
    classDef success  fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    classDef warning  fill:#fff8e1,stroke:#e65100,stroke-width:2px;

    class EventLoop warning;
    class Socket1,Socket2,Socket3 step;
    class FastAPI success;

🔥 6. recv() Through Kernel Boundary

sequenceDiagram

    participant Python as Uvicorn/Gunicorn
    participant Kernel as OS Kernel
    participant NIC as Network Card

    Python->>Kernel: recv()

    Kernel->>Kernel: check socket buffer

    alt buffer empty
        Kernel->>Python: BLOCK process/thread
    end

    NIC->>Kernel: packet arrived

    Kernel->>Kernel: copy bytes into receive buffer

    Kernel-->>Python: return bytes

🔥 7. Development Server vs Production Server

flowchart LR

    subgraph DEV["❌ Development"]
        FlaskRun["app.run()"]
        Single["single process"]
        NoWorkers["no worker management"]
    end

    subgraph PROD["✅ Production"]
        Nginx["Nginx"]
        Gunicorn["Gunicorn/Uvicorn"]
        Workers["multiple workers"]
        Buffers["socket buffering"]
    end

    FlaskRun --> Single
    Single --> NoWorkers

    Nginx --> Gunicorn
    Gunicorn --> Workers
    Workers --> Buffers

    classDef success  fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    classDef error    fill:#ffebee,stroke:#c62828,stroke-width:3px;

    class FlaskRun,Single,NoWorkers error;
    class Nginx,Gunicorn,Workers,Buffers success;

🔥 8. Reverse Proxy Architecture

flowchart LR

    Browser["🌍 Browser"]

    Nginx["Nginx Reverse Proxy"]

    API1["FastAPI Worker 1"]
    API2["FastAPI Worker 2"]
    API3["FastAPI Worker 3"]

    Browser --> Nginx

    Nginx --> API1
    Nginx --> API2
    Nginx --> API3

    classDef step     fill:#eceff1,stroke:#546e7a,stroke-width:1px;
    classDef success  fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    classDef warning  fill:#fff8e1,stroke:#e65100,stroke-width:2px;

    class Browser step;
    class Nginx warning;
    class API1,API2,API3 success;

🔥 9. Socket Lifecycle in Production Server

stateDiagram-v2

    [*] --> socket

    socket --> bind

    bind --> listen

    listen --> accept

    accept --> recv

    recv --> process_request

    process_request --> send_response

    send_response --> close

    close --> [*]