GO — Healthy across the board

• Last commit 1w ago
• 24+ active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 70% of recent commits

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

Falcon is a minimalist ASGI/WSGI framework for building REST APIs and microservices in Python with a focus on reliability and performance at scale. It eliminates magic globals and unnecessary abstractions, providing native asyncio support, WebSocket handling, and strict RFC adherence while remaining intentionally lightweight (2M lines of Python core logic). Monorepo structure with falcon/ containing core framework code, docs/ for Sphinx documentation with API reference files (docs/api/app.rst, docs/api/cookies.rst, docs/api/cors.rst, docs/api/errors.rst, docs/api/hooks.rst), docker/ for benchmark environments, and .github/workflows/ orchestrating multi-stage testing including wheel building and mailman integration testing.

Backend developers and microservices architects building mission-critical HTTP APIs in Python who prioritize performance, code clarity, and explicit control over convention-heavy frameworks. Contributors are typically performance-focused Python developers maintaining high-reliability systems at scale.

Production-ready and actively maintained. The project has extensive CI/CD coverage (.github/workflows/ contains 8 workflow files including cibuildwheel, test-dist, test-wheels, tox-sdist), comprehensive test infrastructure (.coveragerc present), and documentation via ReadTheDocs (.readthedocs.yaml configured). Supports Python 3.9+ and PyPy 3.9+ with stable backwards-compatible interfaces.

Low risk for stability but requires attention to performance-critical details. The codebase includes Cython optimizations (33K lines) alongside pure Python (2M lines), meaning C-level bugs could affect performance without obvious symptoms. No evidence of single-maintainer risk from file list, but the 'no magic' philosophy means developers must understand HTTP/WSGI/ASGI deeply—framework won't hide mistakes.

Active development with comprehensive CI matrix testing (cibuildwheel.yaml, test-other.yaml, test-mailman.yaml), security scanning via zizmor.yaml, and newsFragments tracking in docs/_newsfragments/ suggesting organized release management. The project appears to be maintaining compatibility across CPython/PyPy and WSGI/ASGI simultaneously.

git clone https://github.com/falconry/falcon.git
cd falcon
pip install -e .
pip install -e '.[dev]'  # for development dependencies
make test  # run test suite via Makefile

Daily commands: Development: make (see docker/Makefile for build targets), benchmarks: docker/benchmark.sh, tests: tox or individual test suites via .github/workflows/tests.yaml. Framework itself runs via any WSGI/ASGI server (e.g., gunicorn app:app or uvicorn app:app).

• falcon/__init__.py — Main package entry point exporting core framework classes like App, Request, Response, and HTTP status codes.
• falcon/app.py — Core ASGI/WSGI application class that orchestrates routing, middleware, and request/response handling.
• falcon/routing.py — URI template routing engine that matches HTTP requests to resource handlers with parameter extraction.
• falcon/request.py — Request object wrapping HTTP input streams, query parameters, headers, and media parsing.
• falcon/response.py — Response object managing HTTP status codes, headers, body content, and media serialization.
• falcon/middleware.py — Base middleware classes and patterns for request/response interceptors and error handlers.
• setup.py — Build configuration and dependency declaration for package distribution and installation.

• App (WSGI/ASGI Dispatcher) (Python callables, WSGI environ dict, ASGI receive/send channels) — Entry point that invokes middleware, routes requests to resources, and coordinates response serialization.
  • Failure mode: Unhandled exceptions in responders bubble up; app catches HTTP errors and converts to error responses.
• Router (URI template parsing, string matching) — Matches HTTP method + URI path to resource classes using URI template syntax and extracts path parameters.
  • Failure mode: Returns 404 if no matching route; 405 if method not allowed on resource.
• Request (Stream reading, content-type parsing, query string decoding) — Wraps WSGI environ or ASGI scope/receive; provides query/header/body access and media deserialization.
  • Failure mode: Raises HTTP 400 or 413 on malformed input, oversized payloads, or missing required headers.
• Response (Header dictionaries, stream writing, media handler dispatch) — Accumulates status code, headers, cookies, and body content; serializes via media handlers for transmission.
  • Failure mode: Incomplete response if responder fails to set status; defaults to 500 Internal Server Error.
• Middleware Chain (Hook decorators, exception handlers) — Executes process/process_resource/process_response hooks to implement cross-cutting concerns (auth, logging, rate-limiting).
  • Failure mode: Exception in middleware halts request; process_exception() handler logs and returns error response.
• Media Handlers (JSON, MessagePack, form encoding codecs) — Serialize resp.media to bytes and deserialize req.stream/req.bounded_stream to Python objects based on Content-Type.
  • Failure mode: Raises 415 Unsupported Media Type if handler not found; 400 Bad Request on parse errors.
• Error Handling (Exception catching, status code mapping) — Converts raised HTTPError and HTTPStatus subclasses into proper HTTP responses with headers/body.
  • Failure mode: Unhandled non-HTTP exceptions become 500; optionally logged and handled by middleware process_exception().

• WSGI/ASGI Server → App — Raw HTTP environ dict (WSGI) or scope+receive channels (ASGI) flow into app.call().
• Middleware → Router — After middleware.process() completes, app invokes router.find(method, path) to locate handler resource.
• Request → Resource Handler — Responder (on_get, on_post, etc.) receives req with parsed query params, headers, and deserialized media.
• Resource Handler → Response — Handler sets resp.status, resp.headers, resp.media, or resp.stream; middleware process_response() can further modify.
• Response → WSGI/ASGI Server — App serializes resp.media via media handler, writes status/headers/body to WSGI start_response or ASGI send.

Add a new REST API endpoint

1. Create a resource class with on_get, on_post, etc. responder methods that accept (req, resp, **kwargs). (falcon/routing.py)
2. Register the resource with app.add_route('/path/{id}', MyResource()) in your app initialization. (falcon/app.py)
3. Parse request body via req.media (auto-deserialized by content-type handler) or raw streams. (falcon/request.py)
4. Set resp.status, resp.headers, and resp.media to return JSON/other serialized content. (falcon/response.py)

Add custom middleware

1. Create a middleware class inheriting from falcon.middleware.Middleware or implementing process/process_resource/process_response hooks. (falcon/middleware.py)
2. Instantiate and pass to app=falcon.App(middleware=[MyMiddleware()]) during app creation. (falcon/app.py)
3. Implement hook methods to intercept requests before routing, modify responses, or catch errors. (falcon/middleware.py)

Register custom media type handler

1. Create a handler class with serialize(media, content_type) and deserialize(stream, content_type, content_length) methods. (falcon/media/handlers.py)
2. Register via app.req_options.media_handlers['application/custom'] = MyHandler() or resp_options.media_handlers. (falcon/request.py)
3. Falcon will automatically use your handler to parse req.media and serialize resp.media based on Content-Type negotiation. (falcon/media/__init__.py)

Add request/response hook decorators

1. Use @falcon.before() or @falcon.after() decorators on responder methods to inject pre/post-processing logic. (falcon/hooks.py)
2. Hook function receives (req, resp, resource, params) and can modify request state or response before handler runs. (falcon/hooks.py)
3. Compose multiple hooks on one responder; they execute in declaration order (before) or reverse order (after). (falcon/hooks.py)

• WSGI/ASGI dual support — Enables deployment flexibility across sync (uWSGI, Gunicorn) and async (Uvicorn, Hypercorn) servers without code changes.
• Minimal dependencies — Reduces supply-chain risk and installation bloat while keeping core framework lightweight and fast.
• URI template routing — Provides REST-friendly path parameters without regular expressions, balancing simplicity and expressiveness.
• Pluggable media handlers — Decouples request/response serialization logic, allowing JSON, MessagePack, YAML, or custom formats without framework changes.
• Hook and middleware chains — Enables cross-cutting concerns (logging, auth, rate-limiting) without invasive framework coupling or decorator stacking.

• No built-in ORM, auth, or database layer

  • Why: Falcon prioritizes minimalism and lets teams choose domain-specific libraries (SQLAlchemy, Django ORM, etc.).
  • Consequence: Reduces framework overhead but requires developers to wire up persistence and auth manually.

• Resource-based routing (not function-based like Flask)

  • Why: Encourages REST semantics where one resource class handles multiple HTTP methods for the same URI.
  • Consequence: Slightly more boilerplate per endpoint but clearer semantic grouping and reduced handler proliferation.

• Synchronous middleware by default (async in ASGI mode)

  • Why: Simplifies reasoning about request ordering and middleware composition in the common WSGI case.
  • Consequence: ASGI apps must use async-safe middleware; mixing sync and async middleware requires care.

• No automatic dependency injection or request context locals

  • Why: Avoids implicit magic and thread-local side effects; explicit parameter passing clarifies data flow.
  • Consequence: Requires more plumbing in handlers but makes request lifecycle transparent and testable.

• Does not provide built-in database ORM or migrations.
• Does not include authentication or authorization middleware (users must implement or integrate third-party).
• Does not offer frontend templating or asset pipelines (REST API server only).
• Does not provide WebSocket support in WSGI mode (ASGI-only feature).
• Does not auto-generate API documentation or OpenAPI schemas (community extensions available).

• Mixing sync and async middleware in ASGI mode (High) — falcon/asgi/app.py, falcon/middleware.py: Blocking I/O in async middleware or event-loop-unfriendly code will stall the entire ASGI worker.
• Modifying req/resp in middleware process_exception() (Medium) — falcon/middleware.py: Exception handlers may run after routing; modifying response after responder failure can cause undefined behavior or double-response.
• Unbounded request streaming without checking Content-Length (Medium) — falcon/request.py: Consuming req.stream without respecting Content-Length or using bounded_stream risks resource exhaustion attacks.
• Relying on implicit middleware ordering (Low) — falcon/app.py: Middleware list order matters for hooks (process, process_resource, process_response); undocumented reliance causes subtle bugs.

• falcon/routing.py (Algorithm Complexity) — URI template matching is linear scan of registered routes; O(n) per request. Fast in practice but no radix tree optimization.
• falcon/media/__init__.py (Algorithm Complexity) — Content-Type negotiation iterates all registered handlers; O(m) per request where m = handler count.
• falcon/ (undefined) — undefined

Cython builds require C compiler toolchain (gcc/clang) and Python dev headers for optimization—pure Python fallback exists but loses performance. The 'no magic' design requires developers to explicitly handle WSGI/ASGI semantics (e.g., streaming responses, body encoding). Middleware order matters significantly for request/response processing. Request body is not automatically parsed—use req.bounded_stream or explicit media handlers. Response status must be set explicitly (no implicit 200); typos won't be caught by the framework.

• WSGI (Web Server Gateway Interface) — Falcon is WSGI-native; understanding request/response cycle as callable(environ, start_response) is essential to debugging production issues
• ASGI (Asynchronous Server Gateway Interface) — Modern async alternative to WSGI that Falcon supports natively; required for asyncio features and concurrent request handling
• Middleware Pipeline Pattern — Falcon's request/response processing relies on ordered middleware execution; critical to understanding how hooks and middleware interact
• Resource-Oriented Architecture — Falcon routes requests to Resource classes with on_get/on_post methods instead of function-based views; fundamental to its design philosophy
• Bounded Streams and Streaming Responses — Falcon does not auto-buffer request bodies; developers must understand req.bounded_stream for large payloads and resp.stream for efficient responses
• Media Type Handlers (Content Negotiation) — Falcon's media handlers (JSON, XML, etc.) are pluggable; understanding how to register and override them is essential for custom serialization
• Hook System (before/after decorators) — Falcon's DRY request processing relies on before/after hooks at method level; enables cross-cutting concerns without middleware overhead

• encode/starlette — ASGI-focused competitor with similar minimalist philosophy but more opinionated; useful for comparing routing and middleware approaches
• pallets/flask — Heavier WSGI alternative that influenced Falcon's design; study differences in magic globals vs explicit request handling
• encode/httpx — Companion library commonly used to test Falcon apps; handles HTTP requests with both sync and async support
• falconry/falcon-cors — Official CORS middleware addon referenced in docs/api/cors.rst; example of extending Falcon via middleware pattern
• psf/requests — The HTTP client analogue Falcon developers use; inspired Falcon's philosophy of 'talking HTTP directly without abstractions'

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 ASGI WebSocket integration tests

The repo has docs/api/websocket.rst and ASGI support, but the test suite lacks dedicated WebSocket scenario tests. Given Falcon's focus on reliability at scale, adding integration tests for WebSocket connections, disconnections, error handling, and concurrent connections would catch regressions and improve confidence in this critical feature.

• [ ] Review existing tests in tests/ directory for WebSocket coverage gaps
• [ ] Create tests/test_asgi_websocket_integration.py with scenarios: basic connect/disconnect, message ordering, concurrent connections, error handling
• [ ] Add tests for WebSocket middleware interaction and hooks execution
• [ ] Ensure tests run in .github/workflows/tests.yaml CI pipeline

Implement missing CORS middleware type hints and validation tests

docs/api/cors.rst documents CORS functionality, but there's no dedicated test file for the CORS middleware with modern type hints. Add comprehensive type stubs and validation tests to ensure type checkers catch configuration errors early, improving the developer experience for API developers using strict typing.

• [ ] Create tests/test_cors_middleware_validation.py with parametrized tests for valid/invalid CORS configurations
• [ ] Add type hints to falcon/asgi/middleware/cors.py and falcon/wsgi/middleware/cors.py if missing
• [ ] Test edge cases: wildcard origins, multiple allowed headers, credential handling
• [ ] Verify tests run in existing .github/workflows/tests.yaml

Add multipart form data edge case tests and security validation

docs/api/multipart.rst exists but the test coverage for multipart parsing likely misses security edge cases (file bombs, malformed boundaries, massive headers). Add focused tests to ensure Falcon safely handles malicious multipart payloads at scale, critical for production reliability.

• [ ] Create tests/test_multipart_security.py with scenarios: oversized files, malformed MIME boundaries, deeply nested structures, memory exhaustion attempts
• [ ] Reference falcon/asgi/stream.py and falcon/media/multipart.py implementation details
• [ ] Add integration test with real file uploads and streaming to verify performance under stress
• [ ] Ensure new tests integrate with .github/workflows/test-other.yaml workflow

• Add missing test coverage for cookie handling edge cases in falcon/cookies.py (likely low coverage for domain/path/secure flag combinations based on presence of docs/api/cookies.rst)
• Expand CORS middleware documentation with real-world examples showing preflight request handling—docs/api/cors.rst exists but likely needs runnable examples in docs/_content/
• Create a troubleshooting guide in docs/ for common WSGI vs ASGI migration issues, since the framework supports both but no dedicated migration guide appears in the file list

The Falcon framework repository shows good security hygiene with no critical vulnerabilities evident from the file structure analysis. The codebase includes CI/CD pipelines, proper documentation, and appears to follow standard Python project conventions. However, detailed security analysis requires reviewing actual code files and configuration contents, particularly: GitHub Actions workflows, Docker configurations, dependency specifications (setup.py/pyproject.toml), and the main source code for injection vulnerabilities. The framework itself is well-established and widely used, suggesting ongoing security maintenance. Recommendations focus on automated security scanning and configuration hardening rather than reactive fixes.

• Low · GitHub Actions Workflow Security - Potential Token Exposure — .github/workflows/. Multiple GitHub Actions workflows are configured (.github/workflows/*.yaml). While visible in the file structure, the actual workflow content is not provided. However, workflows in public repositories can potentially expose secrets if not properly configured with restricted permissions and proper secret management. Fix: Ensure all workflows use 'permissions: read-only' by default, explicitly grant only necessary permissions, use GitHub's built-in secret management, and avoid passing secrets to third-party actions. Review workflow files for hardcoded credentials.
• Low · Docker Build Configuration Review Needed — docker/. Multiple Docker build files are present (bench_py3.Dockerfile, bench_py3_cython.Dockerfile, bench_pypy3.Dockerfile). Without reviewing their contents, potential risks include: using base images without security tags, running containers as root, or including unnecessary dependencies. Fix: Review all Dockerfile configurations to: use specific version tags for base images, run containers as non-root users, implement multi-stage builds, and minimize attack surface by removing unnecessary packages. Scan images with tools like Trivy.
• Low · ReadTheDocs Configuration Present — .readthedocs.yaml. A .readthedocs.yaml configuration file exists. Documentation build pipelines can be security vectors if not properly configured. Fix: Ensure the ReadTheDocs configuration: uses pinned dependency versions, doesn't execute untrusted code, and has appropriate build isolation. Review the file contents for security best practices.
• Informational · Public Repository - Consider Security Scanning — Repository root. This is a public open-source framework. While beneficial for community, it increases exposure to security research and potential vulnerability discovery. Fix: Implement automated security scanning: enable GitHub's Dependabot for dependency updates, use SAST tools (e.g., Bandit, Semgrep), enable branch protection requiring security checks, and maintain a security policy (SECURITY.md). Consider a responsible disclosure program.

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/falconry/falcon 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 falconry/falcon repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/falconry/falcon.

What it runs against: a local clone of falconry/falcon — 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 falconry/falcon | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 40 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of falconry/falcon. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/falconry/falcon.git
#   cd falcon
#
# 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 falconry/falcon and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "falcon/__init__.py" \\
  && ok "falcon/__init__.py" \\
  || miss "missing critical file: falcon/__init__.py"
test -f "falcon/app.py" \\
  && ok "falcon/app.py" \\
  || miss "missing critical file: falcon/app.py"
test -f "falcon/routing.py" \\
  && ok "falcon/routing.py" \\
  || miss "missing critical file: falcon/routing.py"
test -f "falcon/request.py" \\
  && ok "falcon/request.py" \\
  || miss "missing critical file: falcon/request.py"
test -f "falcon/response.py" \\
  && ok "falcon/response.py" \\
  || miss "missing critical file: falcon/response.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 40 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~10d)"
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/falconry/falcon"
  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.