GO — Healthy across the board

• Last commit 6d ago
• 15 active contributors
• BSD-3-Clause licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 69% of recent commits

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests, cross-checked against dependency CVEs from deps.dev and OpenSSF Scorecard}

Uvicorn is a production-ready ASGI (Asynchronous Server Gateway Interface) web server implementation for Python that handles HTTP/1.1 and WebSocket connections with async/await support. It bridges the gap between Python async frameworks (like FastAPI, Starlette) and the network layer, replacing the synchronous WSGI standard to enable long-lived connections and true asynchronous request handling. Single-package structure: uvicorn/ contains the core server implementation (protocols, config, lifespan handling), tests/ mirrors this structure with unit and benchmark tests, docs/ provides MkDocs-based documentation (mkdocs.yml), and scripts/ contains bash utilities for common development tasks (check, lint, test, coverage). GitHub Actions workflows orchestrate CI and releases.

Python web developers and framework maintainers (FastAPI, Starlette, Quart users) who need to deploy async web applications in production environments where they require concurrent connection handling, WebSocket support, and event-driven architecture.

Highly mature and production-ready. The project has been actively maintained with comprehensive CI/CD pipelines (.github/workflows/main.yml, publish.yml), extensive test coverage (tests/ directory structure), proper semantic versioning in CHANGELOG.md, and regular deployment workflows. It's widely adopted in the Python async ecosystem.

Low risk for typical usage. The codebase is well-established with minimal surface area (Python + Shell only, no exotic dependencies visible). However, the specific fork 'Kludex/uvicorn' should be verified against the canonical tomchristie/uvicorn for divergence; check the fork's last commit date and whether it merges upstream changes regularly to avoid abandoned-fork risk.

Active development visible in main.yml workflow (automated testing on push), benchmark.yml (performance regression detection), and dependabot.yml (automated dependency updates). The presence of zizmor.yml suggests recent security scanning additions. Review the CHANGELOG.md for recent version notes and GitHub Actions runs to see current work.

git clone https://github.com/Kludex/uvicorn.git
cd uvicorn
pip install -e .[standard]
python -m uvicorn --help

Or run the example from README: create example.py with the provided ASGI app and execute uvicorn example:app.

Daily commands: Development mode with reload (requires watchfiles): uvicorn example:app --reload. Standard production run: uvicorn example:app --host 0.0.0.0 --port 8000. See docs/deployment/ for Docker and advanced configurations. Use scripts/test to run the full test suite.

• uvicorn/config.py — Central configuration object that parses CLI arguments and server settings; all deployments flow through here.
• uvicorn/main.py — Primary entry point that instantiates the server and manages the async event loop lifecycle.
• uvicorn/protocols/http.py — HTTP protocol handler implementing the ASGI connection interface for HTTP requests; handles nearly all incoming traffic.
• uvicorn/lifespan/on.py — Lifespan protocol manager handling application startup/shutdown events and graceful shutdown orchestration.
• uvicorn/logging.py — Logging configuration and ASGI message logging middleware used across all server instances.
• uvicorn/loops/auto.py — Event loop auto-detection that selects between asyncio, uvloop, or other backends based on availability.

• Config (config.py) (Python, Click, dataclasses) — Parses and validates all CLI/programmatic settings; single source of truth for server behavior
  • Failure mode: Invalid config halts startup; invalid settings silently use defaults
• HTTP Protocol Handler (protocols/http.py) (httptools, asyncio streams) — Parses incoming HTTP bytes via httptools; buffers request body; emits ASGI scope and receive messages
  • Failure mode: Malformed requests logged and connection closed; large bodies can cause memory exhaustion if not limited
• Lifespan Manager (lifespan/on.py) (asyncio, ASGI lifespan spec) — Invokes ASGI app startup on server init, shutdown on graceful exit; gates request handling until startup complete
  • Failure mode: Startup exceptions prevent requests; shutdown timeout kills connections abruptly
• Event Loop Abstraction (loops/) (asyncio, uvloop, signal module) — Wraps platform-specific event loop (asyncio/uvloop); installs signal handlers; runs the server
  • Failure mode: Loop crash halts all requests; signal handling failure prevents graceful shutdown
• Process Supervisor (supervisors/multiprocess.py) (multiprocessing, os.fork, signal) — Spawns and monitors worker processes; distributes incoming connections via SO_REUSEPORT
  • Failure mode: Worker crash not auto-restarted; signal propagation failure causes orphaned workers
• Logging Middleware (logging.py) (Python logging, ASGI message filtering) — Wraps ASGI app; logs HTTP request/response details and protocol lifecycle events
  • Failure mode: Large request bodies can be logged unbounded; misconfigured formatters cause startup failure
• Reload Supervisor (supervisors/reload.py) (watchfiles, subprocess, signal) — Monitors source files via watchfiles; restarts worker on code change for development
  • Failure mode: False-positive reloads on log file writes; syntax errors in app prevent restart

• Client Socket → HTTP Protocol Handler — TCP bytes arrive; httptools parser extracts HTTP method, path, headers, body
• HTTP Protocol Handler → ASGI App (via __call__) — Scope dict, receive callable, and send callable passed to app; app awaits receive() and calls send()
• ASGI App → HTTP Protocol Handler — App calls send() with response start (status, headers) and response body messages
• HTTP Protocol Handler → Client Socket — Protocol handler buffers response and writes HTTP bytes back to client
• Signal (SIGTERM/SIGINT) → Event Loop & Lifespan — OS signal triggers graceful shutdown; lifespan shutdown hooks invoked; pending requests drained

Add a New ASGI Protocol Handler

1. Create new file in uvicorn/protocols/ implementing the protocol handler class with init, call methods (uvicorn/protocols/my_protocol.py)
2. Import and register handler in config.py's protocol selection logic (uvicorn/config.py)
3. Add tests in tests/protocols/test_my_protocol.py following existing test patterns (tests/protocols/test_my_protocol.py)

Add a New Middleware Layer

1. Create middleware class in uvicorn/middleware/ that wraps the ASGI app and intercepts messages (uvicorn/middleware/my_middleware.py)
2. Add configuration flag in uvicorn/config.py to enable/disable the middleware (uvicorn/config.py)
3. Wrap the app in uvicorn/main.py's Server.init method if enabled (uvicorn/main.py)
4. Add tests in tests/middleware/test_my_middleware.py (tests/middleware/test_my_middleware.py)

Add a New Event Loop Backend

1. Create loop wrapper class in uvicorn/loops/my_loop.py implementing install_signal_handlers() and run() (uvicorn/loops/my_loop.py)
2. Register loop in uvicorn/loops/auto.py's detection logic (uvicorn/loops/auto.py)
3. Add configuration option in uvicorn/config.py to explicitly select the loop (uvicorn/config.py)
4. Add tests in tests/ verifying loop selection and basic operation (tests/test_auto_detection.py)

Add CLI Option or Server Setting

1. Add new Config field with type hint and default value in uvicorn/config.py (uvicorn/config.py)
2. Add click parameter in uvicorn/main.py or update existing CLI group (uvicorn/__main__.py)
3. Use the setting in uvicorn/main.py's Server class or appropriate handler (uvicorn/main.py)
4. Add test case in tests/test_config.py or tests/test_cli.py (tests/test_config.py)

• ASGI Specification — Standard async interface decoupling server from application frameworks (FastAPI, Starlette, Django Async)
• asyncio / uvloop — Enables high concurrency; uvloop offers 2–4× speedup over standard asyncio for I/O-bound workloads
• Python 3.7+ type hints — Type safety and IDE support; enables static analysis and clearer API contracts
• Click for CLI — User-friendly command-line argument parsing with auto-generated help

• Single-threaded async model (one event loop per process)

  • Why: Simpler concurrency model; avoids thread synchronization overhead
  • Consequence: CPU-bound work blocks event loop; users must run multiple processes or use thread pools for CPU-heavy tasks

• Lifespan protocol separate from request/response

  • Why: Clean separation of app initialization from request handling
  • Consequence: Startup/shutdown failures must be handled explicitly; more boilerplate for simple apps

• Pluggable event loop backend (asyncio vs uvloop)

  • Why: Allows users to trade startup complexity for raw throughput
  • Consequence: Requires detection logic and testing against multiple backends; uvloop has platform/Python version constraints

• Middleware wrapping at server level (not app level)

  • Why: Centralizes cross-cutting concerns (logging, proxy headers) independent of app code
  • Consequence: Server must reload on middleware config changes; cannot be modified at runtime by the app

• Does not provide authentication, authorization, or security headers—delegate to app or middleware
• Does not manage database connections or sessions—app responsibility
• Does not implement request routing—ASGI app handles routing
• Does not provide built-in caching—use middleware or app-level solutions
• Does not support synchronous (non-async) ASGI applications natively—use WSGI adapter if needed

• Avg cyclomatic complexity: ~6.5 — Protocol handlers deal with state machines (HTTP parsing, Web

• Unbounded Message Logging (Medium) — uvicorn/logging.py (message_logger): Request/response bodies logged without size limit; can exhaust memory or disk on large payloads
• Signal Handler Set in App Event Loop (Low) — uvicorn/loops/asyncio.py (install_signal_handlers): Signal handlers installed after event loop starts; SIGINT during startup may not be caught cleanly
• Implicit Lifespan Scope Mutation (Low) — uvicorn/lifespan/on.py: Lifespan scope dict modified in place during startup/shutdown; hard to reason about state transitions
• Exception Swallowing in Protocol Handlers (Medium) — uvicorn/protocols/http.py: Exceptions during ASGI app call logged but not always propagated; partial responses may be sent
• Global State in Config Singleton (Low) — uvicorn/config.py: Config object used as source of truth; changes to config after server start ignored silently

• uvicorn/protocols/http.py (receive buffer) (Memory/I/O) — Entire HTTP request body buffered in memory before ASGI app receives; large uploads block event loop
• uvicorn/supervisors/multiprocess.py (SO_REUSEPORT accept) (Concurrency) — All worker processes wake on single accept event (thundering herd); scales poorly beyond 4–8 workers
• uvicorn/logging.py (synchronous log writes) (I/O) — Logging calls block if handler is synchronous (file, syslog); can delay request handling under heavy load
• uvicorn/loops/auto.py (import time detection) (Startup) — Event loop selection happens at startup; importing uvloop or uvicorn itself can be slow on first run

No major hidden traps detected. However: (1) Optional dependencies (httptools, uvloop, websockets) are not installed by default—use pip install 'uvicorn[standard]' to get production-optimized versions; (2) The --reload flag requires watchfiles, which is not in the base install; (3) Windows users need colorama for colored logs, installed only in [standard] extras; (4) The fork path (Kludex/uvicorn) may diverge from canonical upstream (tomchristie/uvicorn)—verify you're tracking the right version.

• ASGI (Asynchronous Server Gateway Interface) — ASGI is the fundamental protocol uvicorn implements; understanding its callable signature (scope, receive, send) is essential to knowing what uvicorn actually does
• Event-driven async I/O (asyncio) — Uvicorn's entire architecture is built on Python's asyncio event loop; knowing how tasks, coroutines, and the event loop interact is critical for debugging performance issues
• WebSocket handshake and framing — Uvicorn's websocket.py implements RFC 6455; understanding frame masking, opcode handling, and handshake validation is needed to fix WebSocket protocol bugs
• HTTP/1.1 persistent connections and pipelining — Uvicorn's HTTP protocol handlers must manage keep-alive, chunked encoding, and pipeline buffering correctly; misunderstanding causes connection leaks or protocol violations
• Lifespan protocol (startup/shutdown lifecycle) — ASGI's lifespan protocol lets apps initialize resources (DB connections) on server startup and clean up on shutdown; docs/concepts/lifespan.md covers this, but it's often misunderstood
• Multi-process worker model and signal handling — Uvicorn can spawn multiple worker processes (--workers flag); understanding SIGTERM/SIGINT propagation and graceful shutdown across forked processes prevents silent failures

• encode/starlette — Companion ASGI framework that builds on top of uvicorn; many users run Starlette apps via uvicorn servers
• tiangolo/fastapi — Most popular FastAPI users deploy via uvicorn; tightly integrated ecosystem for async Python web development
• pallets/werkzeug — Predecessor WSGI toolkit; understanding its limitations (no long-lived connections) motivates why ASGI and uvicorn exist
• django/asgi — Django's ASGI adapter; users running Django async views rely on uvicorn as the server implementation
• hypercorn/hypercorn — Alternative ASGI server with H2/HTTP/2 support; direct competitor for same use cases, helps understand uvicorn's design trade-offs

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test coverage for uvicorn/protocols/http.py with edge cases

The tests/protocols/test_http.py file exists but uvicorn is an ASGI server handling HTTP protocols - a critical component. New contributors should add tests for edge cases like malformed headers, chunked encoding, HTTP/2 upgrade requests, and connection timeout scenarios. This improves robustness of the core HTTP protocol handler.

• [ ] Review tests/protocols/test_http.py to identify coverage gaps
• [ ] Identify untested code paths in the HTTP protocol implementation
• [ ] Add tests for malformed request handling, header edge cases, and connection state transitions
• [ ] Run coverage tools to verify improvement in protocol handler coverage

Add integration tests for WebSocket protocol edge cases in tests/protocols/

The file structure shows tests/protocols/ exists with test_http.py but no test_websockets.py file is visible. Given that docs/concepts/websockets.md exists and ws.py benchmark exists, WebSocket protocol handling needs dedicated test coverage for connection upgrades, frame parsing, ping/pong handling, and graceful closes.

• [ ] Create tests/protocols/test_websockets.py
• [ ] Add tests for WebSocket upgrade negotiation
• [ ] Add tests for frame parsing and message handling
• [ ] Add tests for connection close scenarios and ping/pong mechanics

Add GitHub Actions workflow for Python dependency vulnerability scanning

The .github/workflows/ directory contains main.yml, benchmark.yml, publish.yml, and zizmor.yml, but there's no dedicated security vulnerability scanning for Python dependencies. Adding a workflow using tools like safety or pip-audit would catch vulnerable dependencies early, matching industry best practices for production ASGI server projects.

• [ ] Create .github/workflows/security.yml
• [ ] Configure pip-audit or safety to scan pyproject.toml dependencies
• [ ] Set up the workflow to run on pull requests and schedule weekly scans
• [ ] Configure appropriate failure thresholds and reporting

• Add type hints to uvicorn/config.py settings class—currently incomplete typing would catch configuration errors earlier and improve IDE support for users
• Expand docs/concepts/lifespan.md with a runnable example of startup/shutdown event handlers—currently sparse, confuses new users on when/how to use lifespan events
• Add benchmarks for WebSocket frame handling under high throughput to tests/benchmarks/—websocket.py lacks performance regression tests, unlike http.py

The uvicorn codebase appears to be a well-structured ASGI web server with comprehensive test coverage including security-relevant areas (SSL, proxy headers, WSGI middleware, logging). However, several medium-severity concerns exist around subprocess handling in reload/supervisor logic, proxy header trust configuration, and WSGI middleware security. The lack of visible dependency file content and actual implementation code prevents a more thorough assessment. The project demonstrates good security practices with dedicated test suites for security features, but would benefit from explicit security headers configuration, documented vulnerability disclosure policy, and stricter configuration defaults for proxy trust. Overall security posture is above average for a web server project, but improvements in configuration safety defaults are recommended.

• Medium · Potential Command Injection in Supervisor/Reload Logic — uvicorn core server implementation (not visible in provided file structure). The presence of supervisor and reload functionality in uvicorn (as evidenced by test files in tests/supervisors/test_reload.py and tests/supervisors/test_multiprocess.py) suggests subprocess spawning. Without seeing the actual implementation, there's a risk of command injection if user input or configuration parameters are passed unsanitized to subprocess calls, particularly in the reload watcher functionality. Fix: Ensure all subprocess calls use list-based arguments (not shell=True), validate and sanitize any user-provided configuration that affects process spawning, and use shlex.quote() for any shell-escaped arguments if necessary.
• Medium · Potential WSGI Middleware Security Issues — tests/middleware/test_wsgi.py and related WSGI middleware implementation. The presence of tests/middleware/test_wsgi.py indicates WSGI middleware integration. WSGI bridges can introduce security issues if not properly configured, including potential header injection, request smuggling, or improper handling of malicious input from upstream proxies. Fix: Validate and sanitize all headers from WSGI applications, implement strict HTTP parsing, use security headers middleware, and thoroughly test edge cases in request/response handling.
• Medium · Proxy Headers Trust Configuration — tests/middleware/test_proxy_headers.py and related proxy middleware. The test file tests/middleware/test_proxy_headers.py suggests proxy header handling functionality. If misconfigured, this could allow header spoofing attacks (X-Forwarded-For, X-Real-IP, etc.) if uvicorn trusts proxy headers from untrusted sources. Fix: Implement strict whitelist of trusted proxies, default to not trusting proxy headers, provide clear configuration documentation, and validate all proxy-related headers against expected formats.
• Low · Missing Security Headers by Default — tests/test_default_headers.py and uvicorn core server implementation. The test file tests/test_default_headers.py suggests basic header handling, but without viewing the actual implementation, it's unclear if comprehensive security headers (HSTS, CSP, X-Frame-Options, etc.) are set by default. Fix: Implement and document default security headers, provide easy configuration options for additional security headers, and include security headers in the default middleware stack.
• Low · SSL/TLS Configuration Assessment Needed — tests/test_ssl.py and uvicorn SSL/TLS implementation. The test file tests/test_ssl.py indicates SSL support, but the actual security of SSL implementation (cipher suites, TLS version enforcement, certificate validation) cannot be fully assessed without examining the implementation details. Fix: Enforce minimum TLS 1.2 (preferably 1.3), use strong cipher suites, validate certificates properly, provide clear documentation on SSL configuration, and consider using system defaults when possible.
• Low · Missing Security.txt or Vulnerability Disclosure Policy — Repository root. No visible .well-known/security.txt or SECURITY.md file in the repository structure, which could hinder responsible vulnerability disclosure. Fix: Create a SECURITY.md file documenting the vulnerability disclosure process and contact information for security researchers.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Kludex/uvicorn shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Kludex/uvicorn repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Kludex/uvicorn.

What it runs against: a local clone of Kludex/uvicorn — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Kludex/uvicorn | Confirms the artifact applies here, not a fork | | 2 | License is still BSD-3-Clause | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 36 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Kludex/uvicorn. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Kludex/uvicorn.git
#   cd uvicorn
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Kludex/uvicorn and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Kludex/uvicorn(\\.git)?\\b" \\
  && ok "origin remote is Kludex/uvicorn" \\
  || miss "origin remote is not Kludex/uvicorn (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(BSD-3-Clause)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"BSD-3-Clause\"" package.json 2>/dev/null) \\
  && ok "license is BSD-3-Clause" \\
  || miss "license drift — was BSD-3-Clause at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "uvicorn/config.py" \\
  && ok "uvicorn/config.py" \\
  || miss "missing critical file: uvicorn/config.py"
test -f "uvicorn/main.py" \\
  && ok "uvicorn/main.py" \\
  || miss "missing critical file: uvicorn/main.py"
test -f "uvicorn/protocols/http.py" \\
  && ok "uvicorn/protocols/http.py" \\
  || miss "missing critical file: uvicorn/protocols/http.py"
test -f "uvicorn/lifespan/on.py" \\
  && ok "uvicorn/lifespan/on.py" \\
  || miss "missing critical file: uvicorn/lifespan/on.py"
test -f "uvicorn/logging.py" \\
  && ok "uvicorn/logging.py" \\
  || miss "missing critical file: uvicorn/logging.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 36 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~6d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Kludex/uvicorn"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.