Compare commits
4 Commits
main
...
fm/test-de
| Author | SHA1 | Date | |
|---|---|---|---|
|
f3f335f33a | ||
|
|
be62da7f15 | ||
|
|
9bd30c08d1 | ||
|
|
b1848c913a |
68
.github/ISSUE_TEMPLATE/1-issue.yml
vendored
68
.github/ISSUE_TEMPLATE/1-issue.yml
vendored
@ -1,68 +0,0 @@
|
||||
name: Issue
|
||||
description: Report a bug or unexpected behavior. 🙏
|
||||
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: Thank you for contributing to Uvicorn! ✊
|
||||
|
||||
- type: checkboxes
|
||||
id: checks
|
||||
attributes:
|
||||
label: Initial Checks
|
||||
description: Just making sure you open a discussion first. 🙏
|
||||
options:
|
||||
- label: I confirm this was discussed, and the maintainers suggest I open an issue.
|
||||
required: true
|
||||
- label: I'm aware that if I created this issue without a discussion, it may be closed without a response.
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: discussion
|
||||
attributes:
|
||||
label: Discussion Link
|
||||
description: |
|
||||
Please link to the discussion that led to this issue.
|
||||
|
||||
If you haven't discussed this issue yet, please do so before opening an issue.
|
||||
render: Text
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: description
|
||||
attributes:
|
||||
label: Description
|
||||
description: |
|
||||
Please explain what you're seeing and what you would expect to see.
|
||||
|
||||
Please provide as much detail as possible to make understanding and solving your problem as quick as possible. 🙏
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: example
|
||||
attributes:
|
||||
label: Example Code
|
||||
description: >
|
||||
If applicable, please add a self-contained,
|
||||
[minimal, reproducible, example](https://stackoverflow.com/help/minimal-reproducible-example)
|
||||
demonstrating the bug.
|
||||
render: Python
|
||||
|
||||
- type: textarea
|
||||
id: version
|
||||
attributes:
|
||||
label: Python, Uvicorn & OS Version
|
||||
description: |
|
||||
Which version of Python & Uvicorn are you using, and which Operating System?
|
||||
|
||||
Please run the following command and copy the output below:
|
||||
|
||||
```bash
|
||||
python -m uvicorn --version
|
||||
```
|
||||
|
||||
render: Text
|
||||
validations:
|
||||
required: true
|
||||
53
.github/ISSUE_TEMPLATE/2-bug-report.md
vendored
Normal file
53
.github/ISSUE_TEMPLATE/2-bug-report.md
vendored
Normal file
@ -0,0 +1,53 @@
|
||||
---
|
||||
name: Bug report
|
||||
about: Report a bug to help improve this project
|
||||
---
|
||||
|
||||
### Checklist
|
||||
|
||||
<!-- Please make sure you check all these items before submitting your bug report. -->
|
||||
|
||||
- [ ] The bug is reproducible against the latest release and/or `master`.
|
||||
- [ ] There are no similar issues or pull requests to fix it yet.
|
||||
|
||||
### Describe the bug
|
||||
|
||||
<!-- A clear and concise description of what the bug is. -->
|
||||
|
||||
### To reproduce
|
||||
|
||||
<!-- Provide a *minimal* example with steps to reproduce the bug locally.
|
||||
|
||||
NOTE: try to keep any external dependencies *at an absolute minimum* .
|
||||
In other words, remove anything that doesn't make the bug go away.
|
||||
|
||||
-->
|
||||
|
||||
### Expected behavior
|
||||
|
||||
<!-- A clear and concise description of what you expected to happen. -->
|
||||
|
||||
### Actual behavior
|
||||
|
||||
<!-- A clear and concise description of what actually happens. -->
|
||||
|
||||
### Debugging material
|
||||
|
||||
<!-- Any tracebacks, screenshots, etc. that can help understanding the problem.
|
||||
|
||||
NOTE:
|
||||
- Please list tracebacks in full (don't truncate them).
|
||||
- If relevant, consider turning on DEBUG or TRACE logs for additional details (see the Logging section on https://www.uvicorn.org/settings/ specifically the `log-level` flag).
|
||||
- Consider using `<details>` to make tracebacks/logs collapsible if they're very large (see https://gist.github.com/ericclemmons/b146fe5da72ca1f706b2ef72a20ac39d).
|
||||
-->
|
||||
|
||||
### Environment
|
||||
|
||||
- OS / Python / Uvicorn version: just run `uvicorn --version`
|
||||
- The exact command you're running uvicorn with, all flags you passed included. If you run it with gunicorn please do the same. If there is a reverse-proxy involved and you cannot reproduce without it please give the minimal config of it to reproduce.
|
||||
|
||||
### Additional context
|
||||
|
||||
<!-- Any additional information that can help understanding the problem.
|
||||
|
||||
Eg. linked issues, or a description of what you were trying to achieve. -->
|
||||
33
.github/ISSUE_TEMPLATE/3-feature-request.md
vendored
Normal file
33
.github/ISSUE_TEMPLATE/3-feature-request.md
vendored
Normal file
@ -0,0 +1,33 @@
|
||||
---
|
||||
name: Feature request
|
||||
about: Suggest an idea for this project.
|
||||
---
|
||||
|
||||
### Checklist
|
||||
|
||||
<!-- Please make sure you check all these items before submitting your feature request. -->
|
||||
|
||||
- [ ] There are no similar issues or pull requests for this yet.
|
||||
- [ ] I discussed this idea on the [community chat](https://gitter.im/encode/community) and feedback is positive.
|
||||
|
||||
### Is your feature related to a problem? Please describe.
|
||||
|
||||
<!-- A clear and concise description of what you are trying to achieve.
|
||||
|
||||
Eg "I want to be able to [...] but I can't because [...]". -->
|
||||
|
||||
## Describe the solution you would like.
|
||||
|
||||
<!-- A clear and concise description of what you would want to happen.
|
||||
|
||||
For API changes, try to provide a code snippet of what you would like the API to look like.
|
||||
-->
|
||||
|
||||
## Describe alternatives you considered
|
||||
|
||||
<!-- Please describe any alternative solutions or features you've considered to solve
|
||||
your problem and why they wouldn't solve it. -->
|
||||
|
||||
## Additional context
|
||||
|
||||
<!-- Provide any additional context, screenshots, tracebacks, etc. about the feature here. -->
|
||||
12
.github/ISSUE_TEMPLATE/config.yml
vendored
12
.github/ISSUE_TEMPLATE/config.yml
vendored
@ -1,9 +1,7 @@
|
||||
# Ref: https://help.github.com/en/github/building-a-strong-community/configuring-issue-templates-for-your-repository#configuring-the-template-chooser
|
||||
blank_issues_enabled: false
|
||||
blank_issues_enabled: true
|
||||
contact_links:
|
||||
- name: Discussions
|
||||
url: https://github.com/Kludex/uvicorn/discussions
|
||||
about: The "Discussions" forum is where you want to start. 💖
|
||||
- name: Chat
|
||||
url: https://discord.com/invite/SWU73HffbV
|
||||
about: Our community Discord server. 💬
|
||||
- name: Question
|
||||
url: https://gitter.im/encode/community
|
||||
about: >
|
||||
Ask a question
|
||||
|
||||
12
.github/PULL_REQUEST_TEMPLATE.md
vendored
12
.github/PULL_REQUEST_TEMPLATE.md
vendored
@ -1,12 +0,0 @@
|
||||
<!-- Thanks for contributing to Uvicorn! 💚
|
||||
Given this is a project maintained by volunteers, please read this template to not waste your time, or ours! 😁 -->
|
||||
|
||||
# Summary
|
||||
|
||||
<!-- Write a small summary about what is happening here. -->
|
||||
|
||||
# Checklist
|
||||
|
||||
- [ ] I understand that this PR may be closed in case there was no previous discussion. (This doesn't apply to typos!)
|
||||
- [ ] I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
|
||||
- [ ] I've updated the documentation accordingly.
|
||||
22
.github/dependabot.yml
vendored
22
.github/dependabot.yml
vendored
@ -1,22 +0,0 @@
|
||||
version: 2
|
||||
updates:
|
||||
- package-ecosystem: "uv"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "monthly"
|
||||
cooldown:
|
||||
default-days: 7
|
||||
groups:
|
||||
python-packages:
|
||||
patterns:
|
||||
- "*"
|
||||
- package-ecosystem: "github-actions"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: monthly
|
||||
cooldown:
|
||||
default-days: 7
|
||||
groups:
|
||||
github-actions:
|
||||
patterns:
|
||||
- "*"
|
||||
36
.github/workflows/benchmark.yml
vendored
36
.github/workflows/benchmark.yml
vendored
@ -1,36 +0,0 @@
|
||||
name: CodSpeed
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: ["main"]
|
||||
pull_request:
|
||||
branches: ["main"]
|
||||
|
||||
permissions:
|
||||
id-token: write
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
benchmarks:
|
||||
name: Run benchmarks
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: "actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd" # v6.0.2
|
||||
with:
|
||||
persist-credentials: false
|
||||
|
||||
- name: Install uv
|
||||
uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
|
||||
with:
|
||||
python-version: "3.13"
|
||||
enable-cache: true
|
||||
|
||||
- name: Install dependencies
|
||||
run: scripts/install
|
||||
shell: bash
|
||||
|
||||
- name: Run the benchmarks
|
||||
uses: CodSpeedHQ/action@db35df748deb45fdef0960669f57d627c1956c30 # v4
|
||||
with:
|
||||
mode: instrumentation
|
||||
run: uv run pytest tests/benchmarks/ --codspeed -n 0
|
||||
115
.github/workflows/main.yml
vendored
115
.github/workflows/main.yml
vendored
@ -1,115 +0,0 @@
|
||||
name: Test Suite
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: ["main"]
|
||||
pull_request:
|
||||
branches: ["main"]
|
||||
|
||||
jobs:
|
||||
tests:
|
||||
name: "Python ${{ matrix.python-version }} ${{ matrix.os }}"
|
||||
runs-on: "${{ matrix.os }}"
|
||||
timeout-minutes: 10
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
python-version: ["3.10", "3.11", "3.12", "3.13", "3.14", "3.14t"]
|
||||
os: [windows-latest, ubuntu-latest, macos-latest]
|
||||
|
||||
steps:
|
||||
- uses: "actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd" # v6.0.2
|
||||
with:
|
||||
persist-credentials: false
|
||||
|
||||
- name: Install uv
|
||||
uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
|
||||
with:
|
||||
python-version: ${{ matrix.python-version }}
|
||||
enable-cache: ${{ matrix.os != 'windows-latest' }}
|
||||
|
||||
- name: Install dependencies
|
||||
run: scripts/install
|
||||
shell: bash
|
||||
|
||||
- name: Run linting checks
|
||||
run: scripts/check
|
||||
if: "${{ matrix.os == 'ubuntu-latest'}}"
|
||||
|
||||
- name: "Build package & docs"
|
||||
run: scripts/build
|
||||
shell: bash
|
||||
|
||||
- name: "Run tests"
|
||||
run: scripts/test
|
||||
shell: bash
|
||||
|
||||
- name: "Enforce coverage"
|
||||
run: scripts/coverage
|
||||
shell: bash
|
||||
|
||||
docs-preview:
|
||||
if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
pull-requests: write
|
||||
|
||||
environment:
|
||||
name: cloudflare
|
||||
url: ${{ steps.deploy.outputs.deployment-url }}
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
|
||||
with:
|
||||
persist-credentials: false
|
||||
|
||||
- name: Install uv
|
||||
uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
|
||||
with:
|
||||
python-version: "3.12"
|
||||
enable-cache: false
|
||||
|
||||
- name: Install dependencies
|
||||
run: scripts/install
|
||||
|
||||
- name: Build docs
|
||||
run: uv run mkdocs build
|
||||
|
||||
- name: Deploy preview to Cloudflare Pages
|
||||
id: deploy
|
||||
uses: cloudflare/wrangler-action@da0e0dfe58b7a431659754fdf3f186c529afbe65 # v3.14.1
|
||||
with:
|
||||
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
|
||||
command: >
|
||||
pages deploy ./site
|
||||
--project-name uvicorn
|
||||
--commit-hash ${{ github.event.pull_request.head.sha }}
|
||||
--branch ${{ github.head_ref }}
|
||||
|
||||
- name: Comment preview URL on PR
|
||||
uses: thollander/actions-comment-pull-request@24bffb9b452ba05a4f3f77933840a6a841d1b32b # v3.0.1
|
||||
with:
|
||||
message: |
|
||||
:book: Docs preview: ${{ steps.deploy.outputs.deployment-url }}
|
||||
comment-tag: docs-preview
|
||||
|
||||
# https://github.com/marketplace/actions/alls-green#why
|
||||
check:
|
||||
if: always()
|
||||
needs: [tests]
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
steps:
|
||||
- name: Decide whether the needed jobs succeeded or failed
|
||||
uses: re-actors/alls-green@05ac9388f0aebcb5727afa17fcccfecd6f8ec5fe # v1.2.2
|
||||
with:
|
||||
jobs: ${{ toJSON(needs) }}
|
||||
134
.github/workflows/publish.yml
vendored
134
.github/workflows/publish.yml
vendored
@ -1,129 +1,27 @@
|
||||
---
|
||||
name: Publish
|
||||
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- '*'
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
publish:
|
||||
name: "Publish release"
|
||||
runs-on: "ubuntu-latest"
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
|
||||
- uses: "actions/checkout@v2"
|
||||
- uses: "actions/setup-python@v2"
|
||||
with:
|
||||
persist-credentials: false
|
||||
|
||||
- name: Install uv
|
||||
uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
|
||||
with:
|
||||
python-version: "3.11"
|
||||
enable-cache: false
|
||||
|
||||
- name: Install dependencies
|
||||
run: scripts/install
|
||||
|
||||
- name: Build package & docs
|
||||
run: scripts/build
|
||||
|
||||
- name: Upload package distributions
|
||||
uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
|
||||
with:
|
||||
name: package-distributions
|
||||
path: dist/
|
||||
|
||||
- name: Upload documentation
|
||||
uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
|
||||
with:
|
||||
name: documentation
|
||||
path: site/
|
||||
|
||||
pypi-publish:
|
||||
runs-on: ubuntu-latest
|
||||
needs: build
|
||||
if: success() && startsWith(github.ref, 'refs/tags/')
|
||||
|
||||
permissions:
|
||||
id-token: write
|
||||
|
||||
environment:
|
||||
name: pypi
|
||||
url: https://pypi.org/project/uvicorn
|
||||
|
||||
steps:
|
||||
- name: Download artifacts
|
||||
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
|
||||
with:
|
||||
name: package-distributions
|
||||
path: dist/
|
||||
|
||||
- name: Publish distribution 📦 to PyPI
|
||||
uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
|
||||
|
||||
docs-publish:
|
||||
runs-on: ubuntu-latest
|
||||
needs: build
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
steps:
|
||||
# `mkdocs gh-deploy` pushes the built docs to `gh-pages`, so this job needs
|
||||
# a real checkout with the authenticated origin remote preserved.
|
||||
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 # zizmor: ignore[artipacked]
|
||||
- name: Download artifacts
|
||||
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
|
||||
with:
|
||||
name: documentation
|
||||
path: site/
|
||||
|
||||
- name: Configure Git Credentials
|
||||
run: |
|
||||
git config user.name github-actions[bot]
|
||||
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
|
||||
|
||||
- name: Install uv
|
||||
uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8.0.0
|
||||
with:
|
||||
python-version: "3.12"
|
||||
enable-cache: false
|
||||
|
||||
- name: Install dependencies
|
||||
run: scripts/install
|
||||
|
||||
- name: Publish documentation 📚 to GitHub Pages
|
||||
run: uv run mkdocs gh-deploy --force
|
||||
|
||||
docs-cloudflare:
|
||||
runs-on: ubuntu-latest
|
||||
needs: build
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
environment:
|
||||
name: cloudflare
|
||||
url: https://uvicorn.dev
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
|
||||
with:
|
||||
persist-credentials: false
|
||||
- name: Download artifacts
|
||||
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
|
||||
with:
|
||||
name: documentation
|
||||
path: site/
|
||||
|
||||
- uses: cloudflare/wrangler-action@da0e0dfe58b7a431659754fdf3f186c529afbe65 # v3.14.1
|
||||
with:
|
||||
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
|
||||
command: >
|
||||
pages deploy ./site
|
||||
--project-name uvicorn
|
||||
--commit-hash ${{ github.sha }}
|
||||
--branch main
|
||||
python-version: 3.7
|
||||
- name: "Install dependencies"
|
||||
run: "scripts/install"
|
||||
- name: "Build package & docs"
|
||||
run: "scripts/build"
|
||||
- name: "Publish to PyPI & deploy docs"
|
||||
run: "scripts/publish"
|
||||
env:
|
||||
TWINE_USERNAME: __token__
|
||||
TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
|
||||
|
||||
37
.github/workflows/test-suite.yml
vendored
Normal file
37
.github/workflows/test-suite.yml
vendored
Normal file
@ -0,0 +1,37 @@
|
||||
---
|
||||
name: Test Suite
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: ["master"]
|
||||
pull_request:
|
||||
branches: ["master"]
|
||||
|
||||
jobs:
|
||||
tests:
|
||||
name: "Python ${{ matrix.python-version }} ${{ matrix.os }}"
|
||||
runs-on: "${{ matrix.os }}"
|
||||
strategy:
|
||||
matrix:
|
||||
python-version: ["3.6", "3.7", "3.8", "3.9"]
|
||||
os: [windows-latest, ubuntu-latest]
|
||||
steps:
|
||||
- uses: "actions/checkout@v2"
|
||||
- uses: "actions/setup-python@v2"
|
||||
with:
|
||||
python-version: "${{ matrix.python-version }}"
|
||||
- name: "Install dependencies"
|
||||
run: "scripts/install"
|
||||
shell: bash
|
||||
- name: "Run linting checks"
|
||||
run: "scripts/check"
|
||||
shell: bash
|
||||
- name: "Build package & docs"
|
||||
run: "scripts/build"
|
||||
shell: bash
|
||||
- name: "Run tests"
|
||||
run: "scripts/test"
|
||||
shell: bash
|
||||
- name: "Enforce coverage"
|
||||
run: "scripts/coverage"
|
||||
shell: bash
|
||||
25
.github/workflows/zizmor.yml
vendored
25
.github/workflows/zizmor.yml
vendored
@ -1,25 +0,0 @@
|
||||
name: GitHub Actions Security Analysis
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: ["main"]
|
||||
pull_request:
|
||||
branches: ["**"]
|
||||
|
||||
permissions: {}
|
||||
|
||||
jobs:
|
||||
zizmor:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
permissions:
|
||||
security-events: write # Required for upload-sarif (used by zizmor-action) to upload SARIF files.
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
|
||||
with:
|
||||
persist-credentials: false
|
||||
|
||||
- name: Run zizmor 🌈
|
||||
uses: zizmorcore/zizmor-action@71321a20a9ded102f6e9ce5718a2fcec2c4f70d8 # v0.5.2
|
||||
3
.gitignore
vendored
3
.gitignore
vendored
@ -1,11 +1,8 @@
|
||||
.cache
|
||||
.coverage
|
||||
.coverage.*
|
||||
.mypy_cache/
|
||||
__pycache__/
|
||||
uvicorn.egg-info/
|
||||
venv/
|
||||
htmlcov/
|
||||
site/
|
||||
dist/
|
||||
.codspeed/
|
||||
|
||||
@ -1 +0,0 @@
|
||||
docs/release-notes.md
|
||||
160
CHANGELOG.md
Normal file
160
CHANGELOG.md
Normal file
@ -0,0 +1,160 @@
|
||||
# Change Log
|
||||
|
||||
## 0.13.1 - 2020-12-12
|
||||
|
||||
### Fixed
|
||||
|
||||
- Prevent exceptions when the ASGI application rejects a connection during the WebSocket handshake, when running on both `--ws wsproto` or `--ws websockets`. (Pull #704 and #881)
|
||||
- Ensure connection `scope` doesn't leak in logs when using JSON log formatters. (Pull #859 and #884)
|
||||
|
||||
## 0.13.0 - 2020-12-08
|
||||
|
||||
### Added
|
||||
|
||||
- Add `--factory` flag to support factory-style application imports. (#875) 2020-12-07 50fc0d1c
|
||||
- Skip installation of signal handlers when not in the main thread. Allows using `Server` in multithreaded contexts without having to override `.install_signal_handlers()`. (#871) 2020-12-07 ce2ef45a
|
||||
|
||||
## 0.12.3 - 2020-11-21
|
||||
|
||||
### Fixed
|
||||
- Fix race condition that leads Quart to hang with uvicorn (#848) 11/18/20 de213614
|
||||
- Use latin1 when decoding X-Forwarded-* headers (#701) 11/12/20 45e6e831
|
||||
- Rework IPv6 support (#837) 11/8/20 bdab488e
|
||||
- Cancel old keepalive-trigger before setting new one. (#832) 10/26/20 d5dcf80c
|
||||
|
||||
## 0.12.2 - 2020-10-19
|
||||
|
||||
### Added
|
||||
- Adding ability to decrypt ssl key file (#808) 10/12/20 90dbb6e0
|
||||
- Support .yml log config files (#799) 10/6/20 b468950e
|
||||
- Added python 3.9 support (#804) 10/6/20 08fd0559
|
||||
|
||||
### Fixed
|
||||
- Fixes watchgod with common prefixes (#817) 10/14/20 1b32f997
|
||||
- Fix reload with ipv6 host (#803) 10/14/20 5acaee5b
|
||||
- Added cli suport for headers containing colon (#813) 10/12/20 68732899
|
||||
- Sharing socket across workers on windows (#802) 10/12/20 103167a0
|
||||
- Note the need to configure trusted "ips" when using unix sockets (#796) 10/4/20 a504c569
|
||||
|
||||
## 0.12.1 - 2020-09-30
|
||||
|
||||
### Changed
|
||||
- Pinning h11 and python-dotenv to min versions (#789) 9/29/20 bbf19c66
|
||||
- Get docs/index.md in sync with README.md (#784) 9/29/20 70ebcfdf
|
||||
|
||||
### Fixed
|
||||
- Improve changelog by pointing out breaking changes (#792) 9/29/20 e2b75064
|
||||
|
||||
## 0.12.0 - 2020-09-28
|
||||
|
||||
### Added
|
||||
- Make reload delay configurable (#774) 9/28/20 98010027
|
||||
- Upgrade maximum h11 dependency version to 0.10 (#772) 8/28/20 54d729cc
|
||||
- Allow .json or .yaml --log-config files (#665) 8/18/20 093a1f7c
|
||||
- Add ASGI dict to the lifespan scope (#754) 8/15/20 8150c3eb
|
||||
- Upgrade wsproto to 0.15.0 (#750) 8/13/20 fbce393f
|
||||
- Use optional package installs (#666) 8/10/20 5fa99a11
|
||||
|
||||
### Changed
|
||||
- Dont set log level for root logger (#767) 8/28/20 df81b168
|
||||
- Uvicorn no longer ships extra dependencies `uvloop`, `websockets` and
|
||||
`httptools` as default. To install these dependencies use
|
||||
`uvicorn[standard]`.
|
||||
|
||||
### Fixed
|
||||
- Revert "Improve shutdown robustness when using `--reload` or multiprocessing (#620)" (#756) 8/28/20 ff4af12d
|
||||
- Fix terminate error in windows (#744) 8/27/20 dd3b842d
|
||||
- Fix bug where --log-config disables uvicorn loggers (#512) 8/11/20 a9c37cc4
|
||||
|
||||
## 0.11.8 - 2020-07-30
|
||||
|
||||
* Fix a regression that caused Uvicorn to crash when using `--interface=wsgi`. (Pull #730)
|
||||
* Fix a regression that caused Uvicorn to crash when using unix domain sockets. (Pull #729)
|
||||
|
||||
## 0.11.7 - 2020-28-07
|
||||
|
||||
* SECURITY FIX: Prevent sending invalid HTTP header names and values. (Pull #725)
|
||||
* SECURITY FIX: Ensure path value is escaped before logging to the console. (Pull #724)
|
||||
* Fix `--proxy-headers` client IP and host when using a Unix socket. (Pull #636)
|
||||
|
||||
## 0.11.6
|
||||
|
||||
* Fix overriding the root logger.
|
||||
|
||||
## 0.11.5
|
||||
|
||||
* Revert "Watch all files, not just .py" due to unexpected side effects.
|
||||
* Revert "Pass through gunicorn timeout config." due to unexpected side effects.
|
||||
|
||||
## 0.11.4
|
||||
|
||||
* Use `watchgod`, if installed, for watching code changes.
|
||||
* Watch all files, not just .py.
|
||||
* Pass through gunicorn timeout config.
|
||||
|
||||
## 0.11.3
|
||||
|
||||
* Update dependencies.
|
||||
|
||||
## 0.11.2
|
||||
|
||||
* Don't open socket until after application startup.
|
||||
* Support `--backlog`.
|
||||
|
||||
## 0.11.1
|
||||
|
||||
* Use a more liberal `h11` dependency. Either `0.8.*` or `0.9.*``.
|
||||
|
||||
## 0.11.0
|
||||
|
||||
* Fix reload/multiprocessing on Windows with Python 3.8.
|
||||
* Drop IOCP support. (Required for fix above.)
|
||||
* Add `uvicorn --version` flag.
|
||||
* Add `--use-colors` and `--no-use-colors` flags.
|
||||
* Display port correctly, when auto port selection isused with `--port=0`.
|
||||
|
||||
## 0.10.8
|
||||
|
||||
* Fix reload/multiprocessing error.
|
||||
|
||||
## 0.10.7
|
||||
|
||||
* Use resource_sharer.DupSocket to resolve socket sharing on Windows.
|
||||
|
||||
## 0.10.6
|
||||
|
||||
* Exit if `workers` or `reload` are use without an app import string style.
|
||||
* Reorganise supervisor processes to properly hand over sockets on windows.
|
||||
|
||||
## 0.10.5
|
||||
|
||||
* Update uvloop dependency to 0.14+
|
||||
|
||||
## 0.10.4
|
||||
|
||||
* Error clearly when `workers=<NUM>` is used with app instance, instead of an app import string.
|
||||
* Switch `--reload-dir` to current working directory by default.
|
||||
|
||||
## 0.10.3
|
||||
|
||||
* Add ``--log-level trace`
|
||||
|
||||
## 0.10.2
|
||||
|
||||
* Enable --proxy-headers by default.
|
||||
|
||||
## 0.10.1
|
||||
|
||||
* Resolve issues with logging when using `--reload` or `--workers`.
|
||||
* Setup up root logger to capture output for all logger instances, not just `uvicorn.error` and `uvicorn.access`.
|
||||
|
||||
## 0.10.0
|
||||
|
||||
* Support for Python 3.8
|
||||
* Separated out `uvicorn.error` and `uvicorn.access` logs.
|
||||
* Coloured log output when connected to a terminal.
|
||||
* Dropped `logger=` config setting.
|
||||
* Added `--log-config [FILE]` and `log_config=[str|dict]`. May either be a Python logging config dictionary or the file name of a logging configuration.
|
||||
* Added `--forwarded_allow_ips` and `forwarded_allow_ips`. Defaults to the value of the `$FORWARDED_ALLOW_IPS` environment variable or "127.0.0.1". The `--proxy-headers` flag now defaults to `True`, but only trusted IPs are used to populate forwarding info.
|
||||
* The `--workers` setting now defaults to the value of the `$WEB_CONCURRENCY` environment variable.
|
||||
* Added support for `--env-file`. Requires `python-dotenv`.
|
||||
23
CITATION.cff
23
CITATION.cff
@ -1,23 +0,0 @@
|
||||
# This CITATION.cff file was generated with cffinit.
|
||||
# Visit https://bit.ly/cffinit to generate yours today!
|
||||
|
||||
cff-version: 1.2.0
|
||||
title: Uvicorn
|
||||
message: >-
|
||||
If you use this software, please cite it using the
|
||||
metadata from this file.
|
||||
type: software
|
||||
authors:
|
||||
- given-names: Marcelo
|
||||
family-names: Trylesinski
|
||||
email: marcelotryle@gmail.com
|
||||
- given-names: Tom
|
||||
family-names: Christie
|
||||
email: tom@tomchristie.com
|
||||
repository-code: "https://github.com/Kludex/uvicorn"
|
||||
url: "https://uvicorn.dev/"
|
||||
abstract: Uvicorn is an ASGI web server implementation for Python.
|
||||
keywords:
|
||||
- asgi
|
||||
- server
|
||||
license: BSD-3-Clause
|
||||
@ -1,4 +1,4 @@
|
||||
Copyright © 2017-present, [Encode OSS Ltd](https://www.encode.io/).
|
||||
Copyright © 2017-present, [Encode OSS Ltd](http://www.encode.io/).
|
||||
All rights reserved.
|
||||
|
||||
Redistribution and use in source and binary forms, with or without
|
||||
|
||||
3
MANIFEST.in
Normal file
3
MANIFEST.in
Normal file
@ -0,0 +1,3 @@
|
||||
include LICENSE.md
|
||||
global-exclude __pycache__
|
||||
global-exclude *.py[co]
|
||||
96
README.md
96
README.md
@ -1,33 +1,29 @@
|
||||
<p align="center">
|
||||
<img width="320" height="320" src="https://raw.githubusercontent.com/tomchristie/uvicorn/main/docs/uvicorn.png" alt='uvicorn'>
|
||||
<img width="320" height="320" src="https://raw.githubusercontent.com/tomchristie/uvicorn/master/docs/uvicorn.png" alt='uvicorn'>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<em>An ASGI web server, for Python.</em>
|
||||
<em>The lightning-fast ASGI server.</em>
|
||||
</p>
|
||||
|
||||
---
|
||||
|
||||
[](https://github.com/Kludex/uvicorn/actions)
|
||||
[](https://github.com/encode/uvicorn/actions)
|
||||
[](https://pypi.python.org/pypi/uvicorn)
|
||||
[](https://pypi.org/project/uvicorn)
|
||||
[](https://discord.gg/RxKUF5JuHs)
|
||||
|
||||
---
|
||||
**Documentation**: [https://www.uvicorn.org](https://www.uvicorn.org)
|
||||
|
||||
**Documentation**: [https://uvicorn.dev](https://uvicorn.dev)
|
||||
**Community**: [https://discuss.encode.io/c/uvicorn](https://discuss.encode.io/c/uvicorn)
|
||||
|
||||
**Source Code**: [https://www.github.com/Kludex/uvicorn](https://www.github.com/Kludex/uvicorn)
|
||||
**Requirements**: Python 3.6+ (For Python 3.5 support, install version 0.8.6.)
|
||||
|
||||
---
|
||||
|
||||
Uvicorn is an ASGI web server implementation for Python.
|
||||
Uvicorn is a lightning-fast ASGI server implementation, using [uvloop][uvloop] and [httptools][httptools].
|
||||
|
||||
Until recently Python has lacked a minimal low-level server/application interface for
|
||||
async frameworks. The [ASGI specification][asgi] fills this gap, and means we're now able to
|
||||
start building a common set of tooling usable across all async frameworks.
|
||||
asyncio frameworks. The [ASGI specification][asgi] fills this gap, and means we're now able to
|
||||
start building a common set of tooling usable across all asyncio frameworks.
|
||||
|
||||
Uvicorn supports HTTP/1.1 and WebSockets.
|
||||
Uvicorn currently supports HTTP/1.1 and WebSockets. Support for HTTP/2 is planned.
|
||||
|
||||
## Quickstart
|
||||
|
||||
@ -40,7 +36,7 @@ $ pip install uvicorn
|
||||
This will install uvicorn with minimal (pure Python) dependencies.
|
||||
|
||||
```shell
|
||||
$ pip install 'uvicorn[standard]'
|
||||
$ pip install uvicorn[standard]
|
||||
```
|
||||
|
||||
This will install uvicorn with "Cython-based" dependencies (where possible) and other "optional extras".
|
||||
@ -53,7 +49,7 @@ In this context, "Cython-based" means the following:
|
||||
Moreover, "optional extras" means that:
|
||||
|
||||
- the websocket protocol will be handled by `websockets` (should you want to use `wsproto` you'd need to install it manually) if possible.
|
||||
- the `--reload` flag in development mode will use `watchfiles`.
|
||||
- the `--reloader` flag in development mode will use `watchgod`.
|
||||
- windows users will have `colorama` installed for the colored logs.
|
||||
- `python-dotenv` will be installed should you want to use the `--env-file` option.
|
||||
- `PyYAML` will be installed to allow you to provide a `.yaml` file to `--log-config`, if desired.
|
||||
@ -68,7 +64,7 @@ async def app(scope, receive, send):
|
||||
'type': 'http.response.start',
|
||||
'status': 200,
|
||||
'headers': [
|
||||
(b'content-type', b'text/plain'),
|
||||
[b'content-type', b'text/plain'],
|
||||
],
|
||||
})
|
||||
await send({
|
||||
@ -85,68 +81,8 @@ $ uvicorn example:app
|
||||
|
||||
---
|
||||
|
||||
## Why ASGI?
|
||||
|
||||
Most well established Python Web frameworks started out as WSGI-based frameworks.
|
||||
|
||||
WSGI applications are a single, synchronous callable that takes a request and returns a response.
|
||||
This doesn’t allow for long-lived connections, like you get with long-poll HTTP or WebSocket connections,
|
||||
which WSGI doesn't support well.
|
||||
|
||||
Having an async concurrency model also allows for options such as lightweight background tasks,
|
||||
and can be less of a limiting factor for endpoints that have long periods being blocked on network
|
||||
I/O such as dealing with slow HTTP requests.
|
||||
|
||||
---
|
||||
|
||||
## Alternative ASGI servers
|
||||
|
||||
A strength of the ASGI protocol is that it decouples the server implementation
|
||||
from the application framework. This allows for an ecosystem of interoperating
|
||||
webservers and application frameworks.
|
||||
|
||||
### Daphne
|
||||
|
||||
The first ASGI server implementation, originally developed to power Django Channels, is [the Daphne webserver][daphne].
|
||||
|
||||
It is run widely in production, and supports HTTP/1.1, HTTP/2, and WebSockets.
|
||||
|
||||
Any of the example applications given here can equally well be run using `daphne` instead.
|
||||
|
||||
```
|
||||
$ pip install daphne
|
||||
$ daphne app:App
|
||||
```
|
||||
|
||||
### Hypercorn
|
||||
|
||||
[Hypercorn][hypercorn] was initially part of the Quart web framework, before
|
||||
being separated out into a standalone ASGI server.
|
||||
|
||||
Hypercorn supports HTTP/1.1, HTTP/2, and WebSockets.
|
||||
|
||||
It also supports [the excellent `trio` async framework][trio], as an alternative to `asyncio`.
|
||||
|
||||
```
|
||||
$ pip install hypercorn
|
||||
$ hypercorn app:App
|
||||
```
|
||||
|
||||
### Mangum
|
||||
|
||||
[Mangum][mangum] is an adapter for using ASGI applications with AWS Lambda & API Gateway.
|
||||
|
||||
### Granian
|
||||
|
||||
[Granian][granian] is an ASGI compatible Rust HTTP server which supports HTTP/2, TLS and WebSockets.
|
||||
|
||||
---
|
||||
|
||||
<p align="center"><i>Uvicorn is <a href="https://github.com/Kludex/uvicorn/blob/main/LICENSE.md">BSD licensed</a> code.<br/>Designed & crafted with care.</i><br/>— 🦄 —</p>
|
||||
<p align="center"><i>Uvicorn is <a href="https://github.com/encode/uvicorn/blob/master/LICENSE.md">BSD licensed</a> code.<br/>Designed & built in Brighton, England.</i><br/>— 🦄 —</p>
|
||||
|
||||
[uvloop]: https://github.com/MagicStack/uvloop
|
||||
[httptools]: https://github.com/MagicStack/httptools
|
||||
[asgi]: https://asgi.readthedocs.io/en/latest/
|
||||
[daphne]: https://github.com/django/daphne
|
||||
[hypercorn]: https://github.com/pgjones/hypercorn
|
||||
[trio]: https://trio.readthedocs.io
|
||||
[mangum]: https://github.com/jordaneremieff/mangum
|
||||
[granian]: https://github.com/emmett-framework/granian
|
||||
|
||||
@ -1,279 +0,0 @@
|
||||
## ASGI
|
||||
|
||||
**Uvicorn** uses the [ASGI specification](https://asgi.readthedocs.io/en/latest/) for interacting with an application.
|
||||
|
||||
The application should expose an async callable which takes three arguments:
|
||||
|
||||
* `scope` - A dictionary containing information about the incoming connection.
|
||||
* `receive` - A channel on which to receive incoming messages from the server.
|
||||
* `send` - A channel on which to send outgoing messages to the server.
|
||||
|
||||
Two common patterns you might use are either function-based applications:
|
||||
|
||||
```python
|
||||
async def app(scope, receive, send):
|
||||
assert scope['type'] == 'http'
|
||||
...
|
||||
```
|
||||
|
||||
Or instance-based applications:
|
||||
|
||||
```python
|
||||
class App:
|
||||
async def __call__(self, scope, receive, send):
|
||||
assert scope['type'] == 'http'
|
||||
...
|
||||
|
||||
app = App()
|
||||
```
|
||||
|
||||
It's good practice for applications to raise an exception on scope types
|
||||
that they do not handle.
|
||||
|
||||
The content of the `scope` argument, and the messages expected by `receive` and `send` depend on the protocol being used.
|
||||
|
||||
The format for HTTP messages is described in the [ASGI HTTP Message format](https://asgi.readthedocs.io/en/latest/specs/www.html).
|
||||
|
||||
### HTTP Scope
|
||||
|
||||
An incoming HTTP request might have a connection `scope` like this:
|
||||
|
||||
```python
|
||||
{
|
||||
'type': 'http',
|
||||
'scheme': 'http',
|
||||
'root_path': '',
|
||||
'server': ('127.0.0.1', 8000),
|
||||
'http_version': '1.1',
|
||||
'method': 'GET',
|
||||
'path': '/',
|
||||
'headers': [
|
||||
(b'host', b'127.0.0.1:8000'),
|
||||
(b'user-agent', b'curl/7.51.0'),
|
||||
(b'accept', b'*/*')
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### HTTP Messages
|
||||
|
||||
The instance coroutine communicates back to the server by sending messages to the `send` coroutine.
|
||||
|
||||
```python
|
||||
await send({
|
||||
'type': 'http.response.start',
|
||||
'status': 200,
|
||||
'headers': [
|
||||
[b'content-type', b'text/plain'],
|
||||
]
|
||||
})
|
||||
await send({
|
||||
'type': 'http.response.body',
|
||||
'body': b'Hello, world!',
|
||||
})
|
||||
```
|
||||
|
||||
### Requests & responses
|
||||
|
||||
Here's an example that displays the method and path used in the incoming request:
|
||||
|
||||
```python
|
||||
async def app(scope, receive, send):
|
||||
"""
|
||||
Echo the method and path back in an HTTP response.
|
||||
"""
|
||||
assert scope['type'] == 'http'
|
||||
|
||||
body = f'Received {scope["method"]} request to {scope["path"]}'
|
||||
await send({
|
||||
'type': 'http.response.start',
|
||||
'status': 200,
|
||||
'headers': [
|
||||
[b'content-type', b'text/plain'],
|
||||
]
|
||||
})
|
||||
await send({
|
||||
'type': 'http.response.body',
|
||||
'body': body.encode('utf-8'),
|
||||
})
|
||||
```
|
||||
|
||||
### Reading the request body
|
||||
|
||||
You can stream the request body without blocking the asyncio task pool,
|
||||
by fetching messages from the `receive` coroutine.
|
||||
|
||||
```python
|
||||
async def read_body(receive):
|
||||
"""
|
||||
Read and return the entire body from an incoming ASGI message.
|
||||
"""
|
||||
body = b''
|
||||
more_body = True
|
||||
|
||||
while more_body:
|
||||
message = await receive()
|
||||
body += message.get('body', b'')
|
||||
more_body = message.get('more_body', False)
|
||||
|
||||
return body
|
||||
|
||||
|
||||
async def app(scope, receive, send):
|
||||
"""
|
||||
Echo the request body back in an HTTP response.
|
||||
"""
|
||||
body = await read_body(receive)
|
||||
await send({
|
||||
'type': 'http.response.start',
|
||||
'status': 200,
|
||||
'headers': [
|
||||
(b'content-type', b'text/plain'),
|
||||
(b'content-length', str(len(body)).encode())
|
||||
]
|
||||
})
|
||||
await send({
|
||||
'type': 'http.response.body',
|
||||
'body': body,
|
||||
})
|
||||
```
|
||||
|
||||
### Streaming responses
|
||||
|
||||
You can stream responses by sending multiple `http.response.body` messages to
|
||||
the `send` coroutine.
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
|
||||
|
||||
async def app(scope, receive, send):
|
||||
"""
|
||||
Send a slowly streaming HTTP response back to the client.
|
||||
"""
|
||||
await send({
|
||||
'type': 'http.response.start',
|
||||
'status': 200,
|
||||
'headers': [
|
||||
[b'content-type', b'text/plain'],
|
||||
]
|
||||
})
|
||||
for chunk in [b'Hello', b', ', b'world!']:
|
||||
await send({
|
||||
'type': 'http.response.body',
|
||||
'body': chunk,
|
||||
'more_body': True
|
||||
})
|
||||
await asyncio.sleep(1)
|
||||
await send({
|
||||
'type': 'http.response.body',
|
||||
'body': b'',
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Why ASGI?
|
||||
|
||||
Most well established Python Web frameworks started out as WSGI-based frameworks.
|
||||
|
||||
WSGI applications are a single, synchronous callable that takes a request and returns a response.
|
||||
This doesn’t allow for long-lived connections, like you get with long-poll HTTP or WebSocket connections,
|
||||
which WSGI doesn't support well.
|
||||
|
||||
Having an async concurrency model also allows for options such as lightweight background tasks,
|
||||
and can be less of a limiting factor for endpoints that have long periods being blocked on network
|
||||
I/O such as dealing with slow HTTP requests.
|
||||
|
||||
---
|
||||
|
||||
## Alternative ASGI servers
|
||||
|
||||
A strength of the ASGI protocol is that it decouples the server implementation
|
||||
from the application framework. This allows for an ecosystem of interoperating
|
||||
webservers and application frameworks.
|
||||
|
||||
### Daphne
|
||||
|
||||
The first ASGI server implementation, originally developed to power Django Channels, is
|
||||
[the Daphne webserver](https://github.com/django/daphne).
|
||||
|
||||
It is run widely in production, and supports HTTP/1.1, HTTP/2, and WebSockets.
|
||||
|
||||
Any of the example applications given here can equally well be run using `daphne` instead.
|
||||
|
||||
```shell
|
||||
pip install daphne
|
||||
daphne app:App
|
||||
```
|
||||
|
||||
### Hypercorn
|
||||
|
||||
[Hypercorn](https://github.com/pgjones/hypercorn) was initially part of the Quart web framework,
|
||||
before being separated out into a standalone ASGI server.
|
||||
|
||||
Hypercorn supports HTTP/1.1, HTTP/2, HTTP/3 and WebSockets.
|
||||
|
||||
```shell
|
||||
pip install hypercorn
|
||||
hypercorn app:App
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ASGI frameworks
|
||||
|
||||
You can use Uvicorn, Daphne, or Hypercorn to run any ASGI framework.
|
||||
|
||||
For small services you can also write ASGI applications directly.
|
||||
|
||||
### Starlette
|
||||
|
||||
[Starlette](https://github.com/Kludex/starlette) is a lightweight ASGI framework/toolkit.
|
||||
|
||||
It is ideal for building high performance asyncio services, and supports both HTTP and WebSockets.
|
||||
|
||||
### Django Channels
|
||||
|
||||
The ASGI specification was originally designed for use with [Django Channels](https://channels.readthedocs.io/en/latest/).
|
||||
|
||||
Channels is a little different to other ASGI frameworks in that it provides
|
||||
an asynchronous frontend onto a threaded-framework backend. It allows Django
|
||||
to support WebSockets, background tasks, and long-running connections,
|
||||
with application code still running in a standard threaded context.
|
||||
|
||||
### Quart
|
||||
|
||||
[Quart](https://pgjones.gitlab.io/quart/) is a Flask-like ASGI web framework.
|
||||
|
||||
### FastAPI
|
||||
|
||||
[**FastAPI**](https://github.com/tiangolo/fastapi) is an API framework based on **Starlette** and **Pydantic**, heavily inspired by previous server versions of **APIStar**.
|
||||
|
||||
You write your API function parameters with Python 3.6+ type declarations and get automatic data conversion, data validation, OpenAPI schemas (with JSON Schemas) and interactive API documentation UIs.
|
||||
|
||||
### BlackSheep
|
||||
|
||||
[BlackSheep](https://www.neoteroi.dev/blacksheep/) is a web framework based on ASGI, inspired by Flask and ASP.NET Core.
|
||||
|
||||
Its most distinctive features are built-in support for dependency injection, automatic binding of parameters by request handler's type annotations, and automatic generation of OpenAPI documentation and Swagger UI.
|
||||
|
||||
### Falcon
|
||||
|
||||
[Falcon](https://falconframework.org) is a minimalist REST and app backend framework for Python, with a focus on reliability, correctness, and performance at scale.
|
||||
|
||||
### Muffin
|
||||
|
||||
[Muffin](https://github.com/klen/muffin) is a fast, lightweight and asynchronous ASGI web-framework for Python 3.
|
||||
|
||||
### Litestar
|
||||
|
||||
[Litestar](https://litestar.dev) is a powerful, lightweight and flexible ASGI framework.
|
||||
|
||||
It includes everything that's needed to build modern APIs - from data serialization and validation to websockets, ORM integration, session management, authentication and more.
|
||||
|
||||
### Panther
|
||||
|
||||
[Panther](https://PantherPy.github.io/) is a fast & friendly web framework for building async APIs with Python 3.10+.
|
||||
|
||||
It has built-in Document-oriented Database, Caching System, Authentication and Permission Classes, Visual API Monitoring and also supports Websocket, Throttling, Middlewares.
|
||||
@ -1,75 +0,0 @@
|
||||
# Event Loop
|
||||
|
||||
Uvicorn provides two event loop implementations that you can choose from using the [`--loop`](../settings.md#implementation) option:
|
||||
|
||||
```bash
|
||||
uvicorn main:app --loop <auto|asyncio|uvloop>
|
||||
```
|
||||
|
||||
By default, Uvicorn uses `--loop auto`, which automatically selects:
|
||||
|
||||
1. **uvloop** - If [uvloop](https://github.com/MagicStack/uvloop) is installed, Uvicorn will use it for maximum performance
|
||||
2. **asyncio** - If uvloop is not available, Uvicorn falls back to Python's built-in asyncio event loop
|
||||
|
||||
Since `uvloop` is not compatible with Windows or PyPy, it is not available on these platforms.
|
||||
|
||||
On Windows, the asyncio implementation uses the standard [`ProactorEventLoop`][asyncio.ProactorEventLoop] in single-process mode.
|
||||
When running with `--reload` or multiple workers, it uses [`SelectorEventLoop`][asyncio.SelectorEventLoop] instead.
|
||||
|
||||
??? info "Why can `ProactorEventLoop` fail with multiple processes on Windows?"
|
||||
If you want to know more about it, you can read the issue [#cpython/122240](https://github.com/python/cpython/issues/122240).
|
||||
|
||||
## Custom Event Loop
|
||||
|
||||
You can use custom event loop implementations by specifying a module path and function name using the colon notation:
|
||||
|
||||
```bash
|
||||
uvicorn main:app --loop <module>:<function>
|
||||
```
|
||||
|
||||
The function should return a callable that creates a new event loop instance.
|
||||
|
||||
### rloop
|
||||
|
||||
[rloop](https://github.com/gi0baro/rloop) is an experimental AsyncIO event loop implemented in Rust on top of the [mio](https://github.com/tokio-rs/mio) crate. It aims to provide high performance through Rust's systems programming capabilities.
|
||||
|
||||
You can install it with:
|
||||
|
||||
=== "pip"
|
||||
```bash
|
||||
pip install rloop
|
||||
```
|
||||
=== "uv"
|
||||
```bash
|
||||
uv add rloop
|
||||
```
|
||||
|
||||
You can run `uvicorn` with `rloop` with the following command:
|
||||
|
||||
```bash
|
||||
uvicorn main:app --loop rloop:new_event_loop
|
||||
```
|
||||
|
||||
!!! warning "Experimental"
|
||||
rloop is currently **experimental** and **not suited for production usage**. It is only available on **Unix systems**.
|
||||
|
||||
### Winloop
|
||||
|
||||
[Winloop](https://github.com/Vizonex/Winloop) is an alternative library that brings uvloop-like performance to Windows. Since uvloop is based on libuv and doesn't support Windows, Winloop provides a Windows-compatible implementation with significant performance improvements over the standard Windows event loop policies.
|
||||
|
||||
You can install it with:
|
||||
|
||||
=== "pip"
|
||||
```bash
|
||||
pip install winloop
|
||||
```
|
||||
=== "uv"
|
||||
```bash
|
||||
uv add winloop
|
||||
```
|
||||
|
||||
You can run `uvicorn` with `Winloop` with the following command:
|
||||
|
||||
```bash
|
||||
uvicorn main:app --loop winloop:new_event_loop
|
||||
```
|
||||
@ -1,109 +0,0 @@
|
||||
Since Uvicorn is an ASGI server, it supports the
|
||||
[ASGI lifespan protocol](https://asgi.readthedocs.io/en/latest/specs/lifespan.html).
|
||||
This allows you to run **startup** and **shutdown** events for your application.
|
||||
|
||||
The lifespan protocol is useful for initializing resources that need to be available throughout
|
||||
the lifetime of the application, such as database connections, caches, or other services.
|
||||
|
||||
Keep in mind that the lifespan is executed **only once per application instance**. If you have
|
||||
multiple workers, each worker will execute the lifespan independently.
|
||||
|
||||
## Lifespan Architecture
|
||||
|
||||
The lifespan protocol runs as a sibling task alongside your main application, allowing both to execute concurrently.
|
||||
|
||||
Let's see how Uvicorn handles the lifespan and main application tasks:
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Server as Uvicorn Server
|
||||
participant LifespanTask as Lifespan Task
|
||||
participant AppTask as Application Task
|
||||
participant UserApp as User Application
|
||||
|
||||
Note over Server: ✅ Server starts
|
||||
|
||||
Server->>+LifespanTask: spawn_task(lifespan_handler)
|
||||
|
||||
LifespanTask->>UserApp: {"type": "lifespan.startup"}
|
||||
|
||||
Note over UserApp: Initialize databases, caches, etc.
|
||||
|
||||
UserApp-->>LifespanTask: {"type": "lifespan.startup.complete"}
|
||||
LifespanTask->>Server: ✅ Startup complete
|
||||
|
||||
Server->>+AppTask: spawn_task(application_handler)
|
||||
Note over AppTask: ✅ Ready for requests
|
||||
|
||||
rect rgb(240, 248, 255)
|
||||
Note over LifespanTask, AppTask: Both tasks running concurrently
|
||||
|
||||
par Lifespan maintains state
|
||||
LifespanTask->>LifespanTask: Keep lifespan connection alive
|
||||
and Application serves requests
|
||||
AppTask->>UserApp: HTTP/WebSocket requests
|
||||
UserApp-->>AppTask: Responses
|
||||
end
|
||||
end
|
||||
|
||||
Note over Server: Shutdown signal received
|
||||
|
||||
Server->>AppTask: Stop accepting new connections
|
||||
AppTask->>AppTask: Complete pending requests
|
||||
|
||||
LifespanTask->>UserApp: {"type": "lifespan.shutdown"}
|
||||
|
||||
Note over UserApp: Cleanup databases, caches, etc.
|
||||
|
||||
UserApp-->>LifespanTask: {"type": "lifespan.shutdown.complete"}
|
||||
|
||||
LifespanTask->>-Server: Lifespan task complete
|
||||
AppTask->>-Server: Application task complete
|
||||
|
||||
Note over Server: ✅ Server stopped
|
||||
```
|
||||
|
||||
Having the lifespan task run as a sibling task is a deliberate design choice. It could have been implemented as a parent task that spawns the
|
||||
application task. This decision has the implication that if you create a [`ContextVar`][contextvars.ContextVar]
|
||||
in the lifespan task, it will not be available in the application task.
|
||||
|
||||
## Usage
|
||||
|
||||
Let's see an example of a minimal (but complete) ASGI application that implements the lifespan protocol:
|
||||
|
||||
```python title="ASGI application with lifespan" hl_lines="3-11"
|
||||
async def app(scope, receive, send):
|
||||
if scope['type'] == 'lifespan':
|
||||
while True:
|
||||
message = await receive()
|
||||
if message['type'] == 'lifespan.startup':
|
||||
print("Application is starting up...")
|
||||
await send({'type': 'lifespan.startup.complete'})
|
||||
elif message['type'] == 'lifespan.shutdown':
|
||||
print("Application is shutting down...")
|
||||
await send({'type': 'lifespan.shutdown.complete'})
|
||||
return
|
||||
elif scope['type'] == 'http':
|
||||
await send({
|
||||
'type': 'http.response.start',
|
||||
'status': 200,
|
||||
'headers': [(b'content-type', b'text/plain')],
|
||||
})
|
||||
await send({'type': 'http.response.body', 'body': b'Hello, World!'})
|
||||
else:
|
||||
raise RuntimeError("This server doesn't support WebSocket.")
|
||||
```
|
||||
|
||||
You can run the above application with `uvicorn main:app`. Then you'll see the print statements when the
|
||||
application starts. You can also try to send some HTTP requests to it, and it will respond with "Hello, World!".
|
||||
And if you stop the server (`CTRL + C`), it will print `"Application is shutting down..."`.
|
||||
|
||||
## Disabling Lifespan
|
||||
|
||||
If you want to disable the lifespan protocol, you can do so by setting the `lifespan` option to `off` when running Uvicorn:
|
||||
|
||||
```bash
|
||||
uvicorn main:app --lifespan off
|
||||
```
|
||||
|
||||
By default, Uvicorn will automatically enable the lifespan protocol if the application supports it.
|
||||
@ -1,319 +0,0 @@
|
||||
Uvicorn uses Python's built-in [`logging`](https://docs.python.org/3/library/logging.html)
|
||||
module, and provides three loggers out of the box:
|
||||
|
||||
| Logger name | Purpose |
|
||||
|------------------|----------------------------------------------------|
|
||||
| `uvicorn` | Parent logger (rarely used directly) |
|
||||
| `uvicorn.error` | Server-level messages (startup, shutdown, errors) |
|
||||
| `uvicorn.access` | Per-request access log lines |
|
||||
|
||||
!!! note
|
||||
Despite its name, `uvicorn.error` is **not** limited to error messages.
|
||||
It is the general-purpose server logger, similar to how Gunicorn names its
|
||||
main logger. See [#562](https://github.com/encode/uvicorn/issues/562) for
|
||||
background.
|
||||
|
||||
## Default Configuration
|
||||
|
||||
By default, Uvicorn applies the following
|
||||
[`dictConfig()`](https://docs.python.org/3/library/logging.config.html#logging.config.dictConfig)
|
||||
configuration:
|
||||
|
||||
```python
|
||||
LOGGING_CONFIG = {
|
||||
"version": 1,
|
||||
"disable_existing_loggers": False,
|
||||
"formatters": {
|
||||
"default": {
|
||||
"()": "uvicorn.logging.DefaultFormatter",
|
||||
"fmt": "%(levelprefix)s %(message)s",
|
||||
"use_colors": None,
|
||||
},
|
||||
"access": {
|
||||
"()": "uvicorn.logging.AccessFormatter",
|
||||
"fmt": '%(levelprefix)s %(client_addr)s - "%(request_line)s" %(status_code)s',
|
||||
},
|
||||
},
|
||||
"handlers": {
|
||||
"default": {
|
||||
"formatter": "default",
|
||||
"class": "logging.StreamHandler",
|
||||
"stream": "ext://sys.stderr",
|
||||
},
|
||||
"access": {
|
||||
"formatter": "access",
|
||||
"class": "logging.StreamHandler",
|
||||
"stream": "ext://sys.stdout",
|
||||
},
|
||||
},
|
||||
"loggers": {
|
||||
"uvicorn": {"handlers": ["default"], "level": "INFO", "propagate": False},
|
||||
"uvicorn.error": {"level": "INFO"},
|
||||
"uvicorn.access": {"handlers": ["access"], "level": "INFO", "propagate": False},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Custom Logging Configuration
|
||||
|
||||
You can supply a custom logging configuration file with the `--log-config`
|
||||
option (or `log_config` when calling `uvicorn.run()`).
|
||||
|
||||
Uvicorn supports three file formats:
|
||||
|
||||
| Extension | Loader | Notes |
|
||||
|----------------|------------------------------|---------------------------------------------|
|
||||
| `.json` | `logging.config.dictConfig` | Standard JSON `dictConfig` schema. |
|
||||
| `.yaml`/`.yml` | `logging.config.dictConfig` | Requires **PyYAML** (`uvicorn[standard]`). |
|
||||
| Any other | `logging.config.fileConfig` | Classic INI-style format. |
|
||||
|
||||
### YAML Example
|
||||
|
||||
Create a file named `log_config.yaml`:
|
||||
|
||||
```yaml
|
||||
version: 1
|
||||
disable_existing_loggers: false
|
||||
formatters:
|
||||
default:
|
||||
"()": uvicorn.logging.DefaultFormatter
|
||||
fmt: "%(asctime)s - %(levelprefix)s %(message)s"
|
||||
datefmt: "%Y-%m-%d %H:%M:%S"
|
||||
use_colors: null
|
||||
access:
|
||||
"()": uvicorn.logging.AccessFormatter
|
||||
fmt: '%(asctime)s - %(levelprefix)s %(client_addr)s - "%(request_line)s" %(status_code)s'
|
||||
datefmt: "%Y-%m-%d %H:%M:%S"
|
||||
handlers:
|
||||
default:
|
||||
formatter: default
|
||||
class: logging.StreamHandler
|
||||
stream: ext://sys.stderr
|
||||
access:
|
||||
formatter: access
|
||||
class: logging.StreamHandler
|
||||
stream: ext://sys.stdout
|
||||
loggers:
|
||||
uvicorn:
|
||||
handlers:
|
||||
- default
|
||||
level: INFO
|
||||
propagate: false
|
||||
uvicorn.error:
|
||||
level: INFO
|
||||
uvicorn.access:
|
||||
handlers:
|
||||
- access
|
||||
level: INFO
|
||||
propagate: false
|
||||
```
|
||||
|
||||
Then pass it to Uvicorn:
|
||||
|
||||
=== "CLI"
|
||||
|
||||
```bash
|
||||
uvicorn main:app --log-config log_config.yaml
|
||||
```
|
||||
|
||||
=== "Programmatic"
|
||||
|
||||
```python
|
||||
uvicorn.run("main:app", log_config="log_config.yaml")
|
||||
```
|
||||
|
||||
### JSON Example
|
||||
|
||||
Create a file named `log_config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"disable_existing_loggers": false,
|
||||
"formatters": {
|
||||
"default": {
|
||||
"()": "uvicorn.logging.DefaultFormatter",
|
||||
"fmt": "%(asctime)s - %(levelprefix)s %(message)s",
|
||||
"datefmt": "%Y-%m-%d %H:%M:%S",
|
||||
"use_colors": null
|
||||
},
|
||||
"access": {
|
||||
"()": "uvicorn.logging.AccessFormatter",
|
||||
"fmt": "%(asctime)s - %(levelprefix)s %(client_addr)s - \"%(request_line)s\" %(status_code)s",
|
||||
"datefmt": "%Y-%m-%d %H:%M:%S"
|
||||
}
|
||||
},
|
||||
"handlers": {
|
||||
"default": {
|
||||
"formatter": "default",
|
||||
"class": "logging.StreamHandler",
|
||||
"stream": "ext://sys.stderr"
|
||||
},
|
||||
"access": {
|
||||
"formatter": "access",
|
||||
"class": "logging.StreamHandler",
|
||||
"stream": "ext://sys.stdout"
|
||||
}
|
||||
},
|
||||
"loggers": {
|
||||
"uvicorn": {
|
||||
"handlers": ["default"],
|
||||
"level": "INFO",
|
||||
"propagate": false
|
||||
},
|
||||
"uvicorn.error": {
|
||||
"level": "INFO"
|
||||
},
|
||||
"uvicorn.access": {
|
||||
"handlers": ["access"],
|
||||
"level": "INFO",
|
||||
"propagate": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Programmatic `dictConfig`
|
||||
|
||||
You can also pass a dictionary directly when running programmatically:
|
||||
|
||||
```python
|
||||
import uvicorn
|
||||
|
||||
log_config = {
|
||||
"version": 1,
|
||||
"disable_existing_loggers": False,
|
||||
"formatters": {
|
||||
"default": {
|
||||
"()": "uvicorn.logging.DefaultFormatter",
|
||||
"fmt": "%(asctime)s - %(levelprefix)s %(message)s",
|
||||
"datefmt": "%Y-%m-%d %H:%M:%S",
|
||||
},
|
||||
"access": {
|
||||
"()": "uvicorn.logging.AccessFormatter",
|
||||
"fmt": '%(asctime)s - %(levelprefix)s %(client_addr)s - "%(request_line)s" %(status_code)s',
|
||||
"datefmt": "%Y-%m-%d %H:%M:%S",
|
||||
},
|
||||
},
|
||||
"handlers": {
|
||||
"default": {
|
||||
"formatter": "default",
|
||||
"class": "logging.StreamHandler",
|
||||
"stream": "ext://sys.stderr",
|
||||
},
|
||||
"access": {
|
||||
"formatter": "access",
|
||||
"class": "logging.StreamHandler",
|
||||
"stream": "ext://sys.stdout",
|
||||
},
|
||||
},
|
||||
"loggers": {
|
||||
"uvicorn": {"handlers": ["default"], "level": "INFO", "propagate": False},
|
||||
"uvicorn.error": {"level": "INFO"},
|
||||
"uvicorn.access": {"handlers": ["access"], "level": "INFO", "propagate": False},
|
||||
},
|
||||
}
|
||||
|
||||
uvicorn.run("main:app", log_config=log_config)
|
||||
```
|
||||
|
||||
## Common Recipes
|
||||
|
||||
### Writing Logs to a File
|
||||
|
||||
To write Uvicorn's server logs to a file in addition to the console, add a `FileHandler` to the `uvicorn` logger:
|
||||
|
||||
```yaml
|
||||
version: 1
|
||||
disable_existing_loggers: false
|
||||
formatters:
|
||||
default:
|
||||
"()": uvicorn.logging.DefaultFormatter
|
||||
fmt: "%(asctime)s - %(levelprefix)s %(message)s"
|
||||
datefmt: "%Y-%m-%d %H:%M:%S"
|
||||
use_colors: false
|
||||
access:
|
||||
"()": uvicorn.logging.AccessFormatter
|
||||
fmt: '%(asctime)s - %(levelprefix)s %(client_addr)s - "%(request_line)s" %(status_code)s'
|
||||
datefmt: "%Y-%m-%d %H:%M:%S"
|
||||
handlers:
|
||||
default:
|
||||
formatter: default
|
||||
class: logging.StreamHandler
|
||||
stream: ext://sys.stderr
|
||||
access:
|
||||
formatter: access
|
||||
class: logging.StreamHandler
|
||||
stream: ext://sys.stdout
|
||||
file:
|
||||
formatter: default
|
||||
class: logging.FileHandler
|
||||
filename: uvicorn.log
|
||||
loggers:
|
||||
uvicorn:
|
||||
handlers:
|
||||
- default
|
||||
- file
|
||||
level: INFO
|
||||
propagate: false
|
||||
uvicorn.error:
|
||||
level: INFO
|
||||
uvicorn.access:
|
||||
handlers:
|
||||
- access
|
||||
level: INFO
|
||||
propagate: false
|
||||
```
|
||||
|
||||
In this example, `uvicorn.access` still writes to stdout only. To write access
|
||||
logs to the file as well, add `file` to the `uvicorn.access.handlers` list.
|
||||
|
||||
### Disabling Access Logs
|
||||
|
||||
Use the `--no-access-log` CLI flag, or set `access_log=False` programmatically.
|
||||
This removes all handlers from `uvicorn.access` without affecting the
|
||||
`uvicorn.error` logger.
|
||||
|
||||
### Disabling Colors
|
||||
|
||||
Pass `--no-use-colors` on the command line, or set `use_colors=False`
|
||||
programmatically. When using a custom `--log-config`, set `use_colors: false`
|
||||
on each formatter that extends `uvicorn.logging.ColourizedFormatter`.
|
||||
|
||||
### Using a Standard Formatter
|
||||
|
||||
If you do not need Uvicorn's colorized output, you can use the standard
|
||||
`logging.Formatter` instead:
|
||||
|
||||
```yaml
|
||||
version: 1
|
||||
disable_existing_loggers: false
|
||||
formatters:
|
||||
default:
|
||||
format: "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
|
||||
datefmt: "%Y-%m-%d %H:%M:%S"
|
||||
handlers:
|
||||
default:
|
||||
formatter: default
|
||||
class: logging.StreamHandler
|
||||
stream: ext://sys.stderr
|
||||
loggers:
|
||||
uvicorn:
|
||||
handlers:
|
||||
- default
|
||||
level: INFO
|
||||
propagate: false
|
||||
uvicorn.error:
|
||||
level: INFO
|
||||
uvicorn.access:
|
||||
handlers:
|
||||
- default
|
||||
level: INFO
|
||||
propagate: false
|
||||
```
|
||||
|
||||
!!! warning
|
||||
When using a standard `logging.Formatter` for the access logger, the
|
||||
`%(client_addr)s`, `%(request_line)s`, and `%(status_code)s` placeholders
|
||||
are **not** available. The access log line will be formatted using only the
|
||||
standard `%(message)s` field.
|
||||
@ -1,107 +0,0 @@
|
||||
**Uvicorn** supports the WebSocket protocol as defined in [RFC 6455](https://datatracker.ietf.org/doc/html/rfc6455).
|
||||
|
||||
## Upgrade Process
|
||||
|
||||
The WebSocket protocol starts as an HTTP connection that gets "upgraded" to a WebSocket connection
|
||||
through a handshake process. Here's how it works:
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client
|
||||
participant Server
|
||||
participant ASGI App
|
||||
|
||||
Note over Client,ASGI App: WebSocket Handshake Process
|
||||
|
||||
Client->>Server: HTTP GET Request
|
||||
Note right of Client: Headers:<br/>Upgrade: websocket<br/>Connection: Upgrade<br/>Sec-WebSocket-Key: [key]<br/>Sec-WebSocket-Version: 13
|
||||
|
||||
Server->>ASGI App: websocket.connect event
|
||||
Note right of Server: Scope type: "websocket"
|
||||
|
||||
alt Connection Accepted
|
||||
ASGI App->>Server: {"type": "websocket.accept"}
|
||||
Server->>Client: HTTP 101 Switching Protocols
|
||||
Note right of Server: Headers:<br/>Upgrade: websocket<br/>Connection: Upgrade<br/>Sec-WebSocket-Accept: [hash]
|
||||
|
||||
Note over Client,ASGI App: WebSocket Connection Established
|
||||
|
||||
loop Message Exchange
|
||||
Client->>Server: WebSocket Frame
|
||||
Server->>ASGI App: websocket.receive event
|
||||
ASGI App->>Server: {"type": "websocket.send", "text": "..."}
|
||||
Server->>Client: WebSocket Frame
|
||||
end
|
||||
|
||||
alt Client Closes
|
||||
Client->>Server: Close Frame
|
||||
Server->>ASGI App: websocket.disconnect event
|
||||
else Server Closes
|
||||
ASGI App->>Server: {"type": "websocket.close"}
|
||||
Server->>Client: Close Frame
|
||||
end
|
||||
|
||||
else Connection Rejected
|
||||
ASGI App->>Server: {"type": "websocket.http.response.start", "status": 403}
|
||||
Server->>Client: HTTP 403 Forbidden
|
||||
end
|
||||
```
|
||||
|
||||
1. **Initial HTTP Request**: The client sends a regular HTTP GET request with special headers indicating it wants to upgrade to WebSocket:
|
||||
- `Upgrade: websocket`
|
||||
- `Connection: Upgrade`
|
||||
- `Sec-WebSocket-Key`: A base64-encoded random key
|
||||
- `Sec-WebSocket-Version: 13`
|
||||
|
||||
2. **Server Processing**: Uvicorn receives the request and creates a WebSocket scope, sending a `websocket.connect` event to the ASGI application.
|
||||
|
||||
3. **Application Decision**: The ASGI app decides whether to accept or reject the connection based on authentication, authorization, or other logic.
|
||||
|
||||
4. **Handshake Completion**: If accepted, the server responds with HTTP 101 status and the computed `Sec-WebSocket-Accept` header.
|
||||
|
||||
5. **Full-Duplex Communication**: Once upgraded, both client and server can send messages at any time using WebSocket frames.
|
||||
|
||||
6. **Connection Termination**: Either side can initiate closing the connection with a close frame.
|
||||
|
||||
## ASGI WebSocket Events
|
||||
|
||||
**Uvicorn** translates WebSocket protocol messages into ASGI events:
|
||||
|
||||
- `websocket.connect`: Sent when a client requests a WebSocket upgrade
|
||||
- `websocket.receive`: Sent when a message is received from the client
|
||||
- `websocket.disconnect`: Sent when the connection is closed
|
||||
|
||||
The ASGI app can respond with:
|
||||
|
||||
- `websocket.accept`: Accept the connection upgrade with an optional subprotocol
|
||||
- `websocket.send`: Send a message to the client
|
||||
- `websocket.close`: Close the connection with an optional status code
|
||||
|
||||
You can read more about it on the [ASGI documentation](https://asgi.readthedocs.io/en/latest/specs/www.html#websocket).
|
||||
|
||||
## Protocol Implementations
|
||||
|
||||
**Uvicorn** has three implementations of the WebSocket protocol.
|
||||
|
||||
### WSProto Protocol
|
||||
|
||||
This implementation was the first implemented. It uses the
|
||||
[`wsproto`](https://python-hyper.org/projects/wsproto/en/stable/) package underneath.
|
||||
|
||||
You can choose this protocol by setting the `--ws` option to `wsproto`.
|
||||
|
||||
### WebSocket Protocol
|
||||
|
||||
This implementation uses the [`websockets`](https://websockets.readthedocs.io/) package as dependency.
|
||||
|
||||
By default, if you have `websockets` installed, Uvicorn will use this protocol.
|
||||
|
||||
### WebSockets SansIO Protocol
|
||||
|
||||
Since `websockets` deprecated the API Uvicorn uses to run the previous protocol, we had to create this new
|
||||
protocol that uses the `websockets` SansIO API.
|
||||
|
||||
You can choose this protocol by setting the `--ws` option to `websockets-sansio`.
|
||||
|
||||
!!! note
|
||||
The SansIO implementation was released in Uvicorn version 0.35.0 in June 2025.
|
||||
@ -1,176 +0,0 @@
|
||||
# Contributing
|
||||
|
||||
Thank you for being interested in contributing to Uvicorn.
|
||||
There are many ways you can contribute to the project:
|
||||
|
||||
- Using Uvicorn on your stack and [reporting bugs/issues you find](https://github.com/Kludex/uvicorn/issues/new)
|
||||
- [Implementing new features and fixing bugs](https://github.com/Kludex/uvicorn/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)
|
||||
- [Review Pull Requests of others](https://github.com/Kludex/uvicorn/pulls)
|
||||
- Write documentation
|
||||
- Participate in discussions
|
||||
|
||||
## Reporting Bugs, Issues or Feature Requests
|
||||
|
||||
Found something that Uvicorn should support?
|
||||
Stumbled upon some unexpected behaviour?
|
||||
Need a missing functionality?
|
||||
|
||||
Contributions should generally start out from a previous discussion.
|
||||
You can reach out someone at the [community chat](https://discord.com/invite/SWU73HffbV)
|
||||
or at the [github discussions tab](https://github.com/Kludex/uvicorn/discussions).
|
||||
|
||||
When creating a new topic in the discussions tab, possible bugs may be raised
|
||||
as a "Potential Issue" discussion, feature requests may be raised as an
|
||||
"Ideas" discussion. We can then determine if the discussion needs
|
||||
to be escalated into an "Issue" or not, or if we'd consider a pull request.
|
||||
|
||||
Try to be more descriptive as you can and in case of a bug report,
|
||||
provide as much information as possible like:
|
||||
|
||||
- OS platform
|
||||
- Python version
|
||||
- Installed dependencies and versions (`python -m pip freeze`)
|
||||
- Code snippet
|
||||
- Error traceback
|
||||
|
||||
You should always try to reduce any examples to the *simplest possible case*
|
||||
that demonstrates the issue.
|
||||
|
||||
Some possibly useful tips for narrowing down potential issues...
|
||||
|
||||
- Does the issue exist with a specific supervisor like `Multiprocess` or more than one?
|
||||
- Does the issue exist on asgi, or wsgi, or both?
|
||||
- Are you running Uvicorn in conjunction with Gunicorn, others, or standalone?
|
||||
|
||||
## Development
|
||||
|
||||
To start developing Uvicorn create a **fork** of the
|
||||
[Uvicorn repository](https://github.com/Kludex/uvicorn) on GitHub.
|
||||
|
||||
Then clone your fork with the following command replacing `YOUR-USERNAME` with
|
||||
your GitHub username:
|
||||
|
||||
```shell
|
||||
$ git clone https://github.com/YOUR-USERNAME/uvicorn
|
||||
```
|
||||
|
||||
You can now install the project and its dependencies using:
|
||||
|
||||
```shell
|
||||
$ cd uvicorn
|
||||
$ scripts/install
|
||||
```
|
||||
|
||||
## Testing and Linting
|
||||
|
||||
We use custom shell scripts to automate testing, linting,
|
||||
and documentation building workflow.
|
||||
|
||||
To run the tests, use:
|
||||
|
||||
```shell
|
||||
$ scripts/test
|
||||
```
|
||||
|
||||
Any additional arguments will be passed to `pytest`. See the [pytest documentation](https://docs.pytest.org/en/latest/how-to/usage.html) for more information.
|
||||
|
||||
For example, to run a single test script:
|
||||
|
||||
```shell
|
||||
$ scripts/test tests/test_cli.py
|
||||
```
|
||||
|
||||
To run the code auto-formatting:
|
||||
|
||||
```shell
|
||||
$ scripts/lint
|
||||
```
|
||||
|
||||
Lastly, to run code checks separately (they are also run as part of `scripts/test`), run:
|
||||
|
||||
```shell
|
||||
$ scripts/check
|
||||
```
|
||||
|
||||
## Documenting
|
||||
|
||||
Documentation pages are located under the `docs/` folder.
|
||||
|
||||
To run the documentation site locally (useful for previewing changes), use:
|
||||
|
||||
```shell
|
||||
$ scripts/docs serve
|
||||
```
|
||||
|
||||
## Resolving Build / CI Failures
|
||||
|
||||
Once you've submitted your pull request, the test suite will
|
||||
automatically run, and the results will show up in GitHub.
|
||||
If the test suite fails, you'll want to click through to the
|
||||
"Details" link, and try to identify why the test suite failed.
|
||||
|
||||
<p align="center" style="margin: 0 0 10px">
|
||||
<img src="https://raw.githubusercontent.com/Kludex/uvicorn/main/docs/img/gh-actions-fail.png" alt='Failing PR commit status'>
|
||||
</p>
|
||||
|
||||
Here are some common ways the test suite can fail:
|
||||
|
||||
### Check Job Failed
|
||||
|
||||
<p align="center" style="margin: 0 0 10px">
|
||||
<img src="https://raw.githubusercontent.com/Kludex/uvicorn/main/docs/img/gh-actions-fail-check.png" alt='Failing GitHub action lint job'>
|
||||
</p>
|
||||
|
||||
This job failing means there is either a code formatting issue or type-annotation issue.
|
||||
You can look at the job output to figure out why it's failed or within a shell run:
|
||||
|
||||
```shell
|
||||
$ scripts/check
|
||||
```
|
||||
|
||||
It may be worth it to run `$ scripts/lint` to attempt auto-formatting the code
|
||||
and if that job succeeds commit the changes.
|
||||
|
||||
### Docs Job Failed
|
||||
|
||||
This job failing means the documentation failed to build. This can happen for
|
||||
a variety of reasons like invalid markdown or missing configuration within `mkdocs.yml`.
|
||||
|
||||
### Python 3.X Job Failed
|
||||
|
||||
This job failing means the unit tests failed or not all code paths are covered by unit tests.
|
||||
|
||||
If tests are failing you will see this message under the coverage report:
|
||||
|
||||
`=== 1 failed, 354 passed, 1 skipped, 1 xfailed in 37.08s ===`
|
||||
|
||||
If tests succeed but coverage doesn't reach 100%, you will see this
|
||||
message under the coverage report:
|
||||
|
||||
`Coverage failure: total of 98 is less than fail-under=100`
|
||||
|
||||
## Releasing
|
||||
|
||||
*This section is targeted at Uvicorn maintainers.*
|
||||
|
||||
Before releasing a new version, create a pull request that includes:
|
||||
|
||||
- **An update to the changelog**:
|
||||
- We follow the format from [keepachangelog](https://keepachangelog.com/en/1.0.0/).
|
||||
- [Compare](https://github.com/Kludex/uvicorn/compare/) `main` with the tag of the latest release, and list all entries that are of interest to our users:
|
||||
- Things that **must** go in the changelog: added, changed, deprecated or removed features, and bug fixes.
|
||||
- Things that **should not** go in the changelog: changes to documentation, tests or tooling.
|
||||
- Try sorting entries in descending order of impact / importance.
|
||||
- Keep it concise and to-the-point. 🎯
|
||||
- **A version bump**: see `__init__.py`.
|
||||
|
||||
For an example, see [#1006](https://github.com/Kludex/uvicorn/pull/1107).
|
||||
|
||||
Once the release PR is merged, create a
|
||||
[new release](https://github.com/Kludex/uvicorn/releases/new) including:
|
||||
|
||||
- Tag version like `0.13.3`.
|
||||
- Release title `Version 0.13.3`
|
||||
- Description copied from the changelog.
|
||||
|
||||
Once created this release will be automatically uploaded to PyPI.
|
||||
@ -1,57 +0,0 @@
|
||||
.md-nav__sponsors {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
align-items: center;
|
||||
gap: 0.5rem;
|
||||
margin: 1.2rem 0.4rem 0.6rem;
|
||||
padding: 0.9rem 0.6rem 0.8rem;
|
||||
background-color: color-mix(in srgb, var(--md-primary-fg-color) 8%, transparent);
|
||||
border-radius: 0.4rem;
|
||||
}
|
||||
|
||||
.md-nav__sponsors-title {
|
||||
margin: 0 0 0.1rem;
|
||||
font-size: 0.6rem;
|
||||
font-weight: 700;
|
||||
text-transform: uppercase;
|
||||
letter-spacing: 0.05em;
|
||||
color: var(--md-default-fg-color--light);
|
||||
}
|
||||
|
||||
.md-nav__sponsor {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
width: 100%;
|
||||
padding: 0.25rem;
|
||||
border-radius: 0.2rem;
|
||||
transition: opacity 0.15s;
|
||||
}
|
||||
|
||||
.md-nav__sponsor:hover {
|
||||
opacity: 0.75;
|
||||
}
|
||||
|
||||
.md-nav__sponsor img {
|
||||
max-width: 100%;
|
||||
max-height: 1.6rem;
|
||||
object-fit: contain;
|
||||
}
|
||||
|
||||
.md-nav__sponsor-cta {
|
||||
display: inline-block;
|
||||
margin-top: 0.15rem;
|
||||
padding: 0.25rem 0.6rem;
|
||||
font-size: 0.65rem;
|
||||
font-weight: 600;
|
||||
color: var(--md-primary-bg-color);
|
||||
background-color: var(--md-primary-fg-color);
|
||||
border-radius: 0.2rem;
|
||||
text-decoration: none;
|
||||
transition: opacity 0.15s;
|
||||
}
|
||||
|
||||
.md-nav__sponsor-cta:hover {
|
||||
opacity: 0.85;
|
||||
color: var(--md-primary-bg-color);
|
||||
}
|
||||
306
docs/deployment.md
Normal file
306
docs/deployment.md
Normal file
@ -0,0 +1,306 @@
|
||||
# Deployment
|
||||
|
||||
Server deployment is a complex area, that will depend on what kind of service you're deploying Uvicorn onto.
|
||||
|
||||
As a general rule, you probably want to:
|
||||
|
||||
* Run `uvicorn --reload` from the command line for local development.
|
||||
* Run `gunicorn -k uvicorn.workers.UvicornWorker` for production.
|
||||
* Additionally run behind Nginx for self-hosted deployments.
|
||||
* Finally, run everything behind a CDN for caching support, and serious DDOS protection.
|
||||
|
||||
## Running from the command line
|
||||
|
||||
Typically you'll run `uvicorn` from the command line.
|
||||
|
||||
```bash
|
||||
$ uvicorn example:app --reload --port 5000
|
||||
```
|
||||
|
||||
The ASGI application should be specified in the form `path.to.module:instance.path`.
|
||||
|
||||
When running locally, use `--reload` to turn on auto-reloading.
|
||||
|
||||
To see the complete set of available options, use `uvicorn --help`:
|
||||
|
||||
<!-- :cli_usage: -->
|
||||
```
|
||||
$ uvicorn --help
|
||||
Usage: uvicorn [OPTIONS] APP
|
||||
|
||||
Options:
|
||||
--host TEXT Bind socket to this host. [default:
|
||||
127.0.0.1]
|
||||
|
||||
--port INTEGER Bind socket to this port. [default: 8000]
|
||||
--uds TEXT Bind to a UNIX domain socket.
|
||||
--fd INTEGER Bind to socket from this file descriptor.
|
||||
--reload Enable auto-reload.
|
||||
--reload-dir TEXT Set reload directories explicitly, instead
|
||||
of using the current working directory.
|
||||
|
||||
--reload-delay FLOAT Delay between previous and next check if
|
||||
application needs to be. Defaults to 0.25s.
|
||||
[default: 0.25]
|
||||
|
||||
--workers INTEGER Number of worker processes. Defaults to the
|
||||
$WEB_CONCURRENCY environment variable if
|
||||
available. Not valid with --reload.
|
||||
|
||||
--loop [auto|asyncio|uvloop] Event loop implementation. [default: auto]
|
||||
--http [auto|h11|httptools] HTTP protocol implementation. [default:
|
||||
auto]
|
||||
|
||||
--ws [auto|none|websockets|wsproto]
|
||||
WebSocket protocol implementation.
|
||||
[default: auto]
|
||||
|
||||
--lifespan [auto|on|off] Lifespan implementation. [default: auto]
|
||||
--interface [auto|asgi3|asgi2|wsgi]
|
||||
Select ASGI3, ASGI2, or WSGI as the
|
||||
application interface. [default: auto]
|
||||
|
||||
--env-file PATH Environment configuration file.
|
||||
--log-config PATH Logging configuration file. Supported
|
||||
formats: .ini, .json, .yaml.
|
||||
|
||||
--log-level [critical|error|warning|info|debug|trace]
|
||||
Log level. [default: info]
|
||||
--access-log / --no-access-log Enable/Disable access log.
|
||||
--use-colors / --no-use-colors Enable/Disable colorized logging.
|
||||
--proxy-headers / --no-proxy-headers
|
||||
Enable/Disable X-Forwarded-Proto,
|
||||
X-Forwarded-For, X-Forwarded-Port to
|
||||
populate remote address info.
|
||||
|
||||
--forwarded-allow-ips TEXT Comma seperated list of IPs to trust with
|
||||
proxy headers. Defaults to the
|
||||
$FORWARDED_ALLOW_IPS environment variable if
|
||||
available, or '127.0.0.1'.
|
||||
|
||||
--root-path TEXT Set the ASGI 'root_path' for applications
|
||||
submounted below a given URL path.
|
||||
|
||||
--limit-concurrency INTEGER Maximum number of concurrent connections or
|
||||
tasks to allow, before issuing HTTP 503
|
||||
responses.
|
||||
|
||||
--backlog INTEGER Maximum number of connections to hold in
|
||||
backlog
|
||||
|
||||
--limit-max-requests INTEGER Maximum number of requests to service before
|
||||
terminating the process.
|
||||
|
||||
--timeout-keep-alive INTEGER Close Keep-Alive connections if no new data
|
||||
is received within this timeout. [default:
|
||||
5]
|
||||
|
||||
--ssl-keyfile TEXT SSL key file
|
||||
--ssl-certfile TEXT SSL certificate file
|
||||
--ssl-keyfile-password TEXT SSL keyfile password
|
||||
--ssl-version INTEGER SSL version to use (see stdlib ssl module's)
|
||||
[default: 2]
|
||||
|
||||
--ssl-cert-reqs INTEGER Whether client certificate is required (see
|
||||
stdlib ssl module's) [default: 0]
|
||||
|
||||
--ssl-ca-certs TEXT CA certificates file
|
||||
--ssl-ciphers TEXT Ciphers to use (see stdlib ssl module's)
|
||||
[default: TLSv1]
|
||||
|
||||
--header TEXT Specify custom default HTTP response headers
|
||||
as a Name:Value pair
|
||||
|
||||
--version Display the uvicorn version and exit.
|
||||
--app-dir TEXT Look for APP in the specified directory, by
|
||||
adding this to the PYTHONPATH. Defaults to
|
||||
the current working directory. [default: .]
|
||||
|
||||
--factory Treat APP as an application factory, i.e. a
|
||||
() -> <ASGI app> callable. [default: False]
|
||||
|
||||
--help Show this message and exit.
|
||||
```
|
||||
|
||||
See the [settings documentation](settings.md) for more details on the supported options for running uvicorn.
|
||||
|
||||
## Running programmatically
|
||||
|
||||
To run directly from within a Python program, you should use `uvicorn.run(app, **config)`. For example:
|
||||
|
||||
**example.py**:
|
||||
|
||||
```python
|
||||
import uvicorn
|
||||
|
||||
class App:
|
||||
...
|
||||
|
||||
app = App()
|
||||
|
||||
if __name__ == "__main__":
|
||||
uvicorn.run("example:app", host="127.0.0.1", port=5000, log_level="info")
|
||||
```
|
||||
|
||||
The set of configuration options is the same as for the command line tool.
|
||||
|
||||
Note that the application instance itself *can* be passed instead of the app
|
||||
import string.
|
||||
|
||||
```python
|
||||
uvicorn.run(app, host="127.0.0.1", port=5000, log_level="info")
|
||||
```
|
||||
|
||||
However, this style only works if you are not using multiprocessing (`workers=NUM`)
|
||||
or reloading (`reload=True`), so we recommend using the import string style.
|
||||
|
||||
## Using a process manager
|
||||
|
||||
Running Uvicorn using a process manager ensures that you can run multiple processes in a resilient manner, and allows you to perform server upgrades without dropping requests.
|
||||
|
||||
A process manager will handle the socket setup, start-up multiple server processes, monitor process aliveness, and listen for signals to provide for processes restarts, shutdowns, or dialing up and down the number of running processes.
|
||||
|
||||
Uvicorn provides a lightweight way to run multiple worker processes, for example `--workers 4`, but does not provide any process monitoring.
|
||||
|
||||
### Gunicorn
|
||||
|
||||
Gunicorn is probably the simplest way to run and manage Uvicorn in a production setting. Uvicorn includes a gunicorn worker class that means you can get set up with very little configuration.
|
||||
|
||||
The following will start Gunicorn with four worker processes:
|
||||
|
||||
`gunicorn -w 4 -k uvicorn.workers.UvicornWorker`
|
||||
|
||||
The `UvicornWorker` implementation uses the `uvloop` and `httptools` implementations. To run under PyPy you'll want to use pure-python implementation instead. You can do this by using the `UvicornH11Worker` class.
|
||||
|
||||
`gunicorn -w 4 -k uvicorn.workers.UvicornH11Worker`
|
||||
|
||||
Gunicorn provides a different set of configuration options to Uvicorn, so some options such as `--limit-concurrency` are not yet supported when running with Gunicorn.
|
||||
|
||||
### Supervisor
|
||||
|
||||
To use `supervisor` as a process manager you should either:
|
||||
|
||||
* Hand over the socket to uvicorn using its file descriptor, which supervisor always makes available as `0`, and which must be set in the `fcgi-program` section.
|
||||
* Or use a UNIX domain socket for each `uvicorn` process.
|
||||
|
||||
A simple supervisor configuration might look something like this:
|
||||
|
||||
**supervisord.conf**:
|
||||
|
||||
```ini
|
||||
[supervisord]
|
||||
|
||||
[fcgi-program:uvicorn]
|
||||
socket=tcp://localhost:8000
|
||||
command=venv/bin/uvicorn --fd 0 example:App
|
||||
numprocs=4
|
||||
process_name=uvicorn-%(process_num)d
|
||||
stdout_logfile=/dev/stdout
|
||||
stdout_logfile_maxbytes=0
|
||||
```
|
||||
|
||||
Then run with `supervisord -n`.
|
||||
|
||||
### Circus
|
||||
|
||||
To use `circus` as a process manager, you should either:
|
||||
|
||||
* Hand over the socket to uvicorn using its file descriptor, which circus makes available as `$(circus.sockets.web)`.
|
||||
* Or use a UNIX domain socket for each `uvicorn` process.
|
||||
|
||||
A simple circus configuration might look something like this:
|
||||
|
||||
**circus.ini**:
|
||||
|
||||
```ini
|
||||
[watcher:web]
|
||||
cmd = venv/bin/uvicorn --fd $(circus.sockets.web) example:App
|
||||
use_sockets = True
|
||||
numprocesses = 4
|
||||
|
||||
[socket:web]
|
||||
host = 0.0.0.0
|
||||
port = 8000
|
||||
```
|
||||
|
||||
Then run `circusd circus.ini`.
|
||||
|
||||
## Running behind Nginx
|
||||
|
||||
Using Nginx as a proxy in front of your Uvicorn processes may not be neccessary, but is recommended for additional resiliance. Nginx can deal with serving your static media and buffering slow requests, leaving your application servers free from load as much as possible.
|
||||
|
||||
In managed environments such as `Heroku`, you wont typically need to configure Nginx, as your server processes will already be running behind load balancing proxies.
|
||||
|
||||
The recommended configuration for proxying from Nginx is to use a UNIX domain socket between Nginx and whatever the process manager that is being used to run Uvicorn.
|
||||
Note that when doing this you will need run Uvicorn with `--forwarded-allow-ips='*'` to ensure that the domain socket is trusted as a source from which to proxy headers.
|
||||
|
||||
When fronting the application with a proxy server you want to make sure that the proxy sets headers to ensure that application can properly determine the client address of the incoming connection, and if the connection was over `http` or `https`.
|
||||
|
||||
You should ensure that the `X-Forwarded-For` and `X-Forwarded-Proto` headers are set by the proxy, and that Uvicorn is run using the `--proxy-headers` setting. This ensure that the ASGI scope includes correct `client` and `scheme` information.
|
||||
|
||||
Here's how a simple Nginx configuration might look. This example includes setting proxy headers, and using a UNIX domain socket to communicate with the application server.
|
||||
|
||||
```conf
|
||||
http {
|
||||
server {
|
||||
listen 80;
|
||||
client_max_body_size 4G;
|
||||
|
||||
server_name example.com;
|
||||
|
||||
location / {
|
||||
proxy_set_header Host $http_host;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_redirect off;
|
||||
proxy_buffering off;
|
||||
proxy_pass http://uvicorn;
|
||||
}
|
||||
|
||||
location /static {
|
||||
# path for static files
|
||||
root /path/to/app/static;
|
||||
}
|
||||
}
|
||||
|
||||
upstream uvicorn {
|
||||
server unix:/tmp/uvicorn.sock;
|
||||
}
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
Uvicorn's `--proxy-headers` behavior may not be sufficient for more complex proxy configurations that use different combinations of headers, or where the application is running behind more than one intermediary proxying service.
|
||||
|
||||
In those cases you might want to use an ASGI middleware to set the `client` and `scheme` dependant on the request headers.
|
||||
|
||||
## Running behind a CDN
|
||||
|
||||
Running behind a content delivery network, such as Cloudflare or Cloud Front, provides a serious layer of protection against DDOS attacks. Your sevice will be running behind huge clusters of proxies and load balancers that are designed for handling huge amounts of traffic, and have capabilities for detecting and closing off connections from DDOS attacks.
|
||||
|
||||
Proper usage of cache control headers can mean that a CDN is able to serve large amounts of data without always having to forward the request on to your server.
|
||||
|
||||
Content Delivery Networks can also be a low-effort way to provide HTTPS termination.
|
||||
|
||||
## Running with HTTPS
|
||||
|
||||
To run uvicorn with https, a certificate and a private key are required.
|
||||
The recommended way to get them is using [Let's Encrypt][letsencrypt].
|
||||
|
||||
For local development with https, it's possible to use [mkcert][mkcert]
|
||||
to generate a valid certificate and private key.
|
||||
|
||||
```bash
|
||||
$ uvicorn example:app --port 5000 --ssl-keyfile=./key.pem --ssl-certfile=./cert.pem
|
||||
```
|
||||
|
||||
### Running gunicorn worker
|
||||
|
||||
It also possible to use certificates with uvicorn's worker for gunicorn
|
||||
|
||||
```bash
|
||||
$ gunicorn --keyfile=./key.pem --certfile=./cert.pem -k uvicorn.workers.UvicornWorker example:app
|
||||
```
|
||||
|
||||
[letsencrypt]: https://letsencrypt.org/
|
||||
[mkcert]: https://github.com/FiloSottile/mkcert
|
||||
@ -1,153 +0,0 @@
|
||||
# Dockerfile
|
||||
|
||||
**Docker** is a popular choice for modern application deployment. However, creating a good Dockerfile from scratch can be challenging. This guide provides a **solid foundation** that works well for most Python projects.
|
||||
|
||||
While the example below won't fit every use case, it offers an excellent starting point that you can adapt to your specific needs.
|
||||
|
||||
|
||||
## Quickstart
|
||||
|
||||
For this example, we'll need to install [`docker`](https://docs.docker.com/get-docker/),
|
||||
[docker-compose](https://docs.docker.com/compose/install/) and
|
||||
[`uv`](https://docs.astral.sh/uv/getting-started/installation/).
|
||||
|
||||
Then, let's create a new project with `uv`:
|
||||
|
||||
```bash
|
||||
uv init app
|
||||
```
|
||||
|
||||
This will create a new project with a basic structure:
|
||||
|
||||
```bash
|
||||
app/
|
||||
├── main.py
|
||||
├── pyproject.toml
|
||||
└── README.md
|
||||
```
|
||||
|
||||
On `main.py`, let's create a simple ASGI application:
|
||||
|
||||
```python title="main.py"
|
||||
async def app(scope, receive, send):
|
||||
body = "Hello, world!"
|
||||
await send(
|
||||
{
|
||||
"type": "http.response.start",
|
||||
"status": 200,
|
||||
"headers": [
|
||||
[b"content-type", b"text/plain"],
|
||||
[b"content-length", len(body)],
|
||||
],
|
||||
}
|
||||
)
|
||||
await send(
|
||||
{
|
||||
"type": "http.response.body",
|
||||
"body": body.encode("utf-8"),
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
We need to include `uvicorn` in the dependencies:
|
||||
|
||||
```bash
|
||||
uv add uvicorn
|
||||
```
|
||||
|
||||
This will also create a `uv.lock` file. :sunglasses:
|
||||
|
||||
??? tip "What is `uv.lock`?"
|
||||
|
||||
`uv.lock` is a `uv` specific lockfile. A lockfile is a file that contains the exact versions of the dependencies
|
||||
that were installed when the `uv.lock` file was created.
|
||||
|
||||
This allows for deterministic builds and consistent deployments.
|
||||
|
||||
Just to make sure everything is working, let's run the application:
|
||||
|
||||
```bash
|
||||
uv run uvicorn main:app
|
||||
```
|
||||
|
||||
You should see the following output:
|
||||
|
||||
```bash
|
||||
INFO: Started server process [62727]
|
||||
INFO: Waiting for application startup.
|
||||
INFO: ASGI 'lifespan' protocol appears unsupported.
|
||||
INFO: Application startup complete.
|
||||
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
|
||||
```
|
||||
|
||||
## Dockerfile
|
||||
|
||||
We'll create a **cache-aware Dockerfile** that optimizes build times. The key strategy is to install dependencies first, then copy the project files. This approach leverages Docker's caching mechanism to significantly speed up rebuilds.
|
||||
|
||||
```dockerfile title="Dockerfile"
|
||||
FROM python:3.12-slim
|
||||
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
|
||||
|
||||
# Change the working directory to the `app` directory
|
||||
WORKDIR /app
|
||||
|
||||
# Install dependencies
|
||||
RUN --mount=type=cache,target=/root/.cache/uv \
|
||||
--mount=type=bind,source=uv.lock,target=uv.lock \
|
||||
--mount=type=bind,source=pyproject.toml,target=pyproject.toml \
|
||||
uv sync --frozen --no-install-project
|
||||
|
||||
# Copy the project into the image
|
||||
ADD . /app
|
||||
|
||||
# Sync the project
|
||||
RUN --mount=type=cache,target=/root/.cache/uv \
|
||||
uv sync --frozen
|
||||
|
||||
# Run with uvicorn
|
||||
CMD ["uv", "run", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
|
||||
```
|
||||
|
||||
A common question is **"how many workers should I run?"**. The image above uses a single Uvicorn worker.
|
||||
The recommended approach is to let your orchestration system manage the number of deployed containers rather than
|
||||
relying on the process manager inside the container.
|
||||
|
||||
You can read more about this in the
|
||||
[Decouple applications](https://docs.docker.com/build/building/best-practices/#decouple-applications) section
|
||||
of the Docker documentation.
|
||||
|
||||
!!! warning "For production, create a non-root user!"
|
||||
When running in production, you should create a non-root user and run the container as that user.
|
||||
|
||||
To make sure it works, let's build the image and run it:
|
||||
|
||||
```bash
|
||||
docker build -t my-app .
|
||||
docker run -p 8000:8000 my-app
|
||||
```
|
||||
|
||||
For more information on using uv with Docker, refer to the
|
||||
[official uv Docker integration guide](https://docs.astral.sh/uv/guides/integration/docker/).
|
||||
|
||||
## Docker Compose
|
||||
|
||||
When running in development, it's often useful to have a way to hot-reload the application when code changes.
|
||||
|
||||
Let's create a `docker-compose.yml` file to run the application:
|
||||
|
||||
```yaml title="docker-compose.yml"
|
||||
services:
|
||||
backend:
|
||||
build: .
|
||||
ports:
|
||||
- "8000:8000"
|
||||
environment:
|
||||
- UVICORN_RELOAD=true
|
||||
volumes:
|
||||
- .:/app
|
||||
tty: true
|
||||
```
|
||||
|
||||
You can run the application with `docker compose up` and it will automatically rebuild the image when code changes.
|
||||
|
||||
Now you have a fully working development environment! :tada:
|
||||
@ -1,297 +0,0 @@
|
||||
Server deployment is a complex area, that will depend on what kind of service you're deploying Uvicorn onto.
|
||||
|
||||
As a general rule, you probably want to:
|
||||
|
||||
* Run `uvicorn --reload` from the command line for local development.
|
||||
* Run `gunicorn -k uvicorn.workers.UvicornWorker` for production.
|
||||
* Additionally run behind Nginx for self-hosted deployments.
|
||||
* Finally, run everything behind a CDN for caching support, and serious DDOS protection.
|
||||
|
||||
## Running from the command line
|
||||
|
||||
Typically you'll run `uvicorn` from the command line.
|
||||
|
||||
```bash
|
||||
$ uvicorn main:app --reload --port 5000
|
||||
```
|
||||
|
||||
The ASGI application should be specified in the form `path.to.module:instance.path`.
|
||||
|
||||
When running locally, use `--reload` to turn on auto-reloading.
|
||||
|
||||
The `--reload` and `--workers` arguments are **mutually exclusive**.
|
||||
|
||||
To see the complete set of available options, use `uvicorn --help`:
|
||||
|
||||
```bash
|
||||
{{ uvicorn_help }}
|
||||
```
|
||||
|
||||
See the [settings documentation](../settings.md) for more details on the supported options for running uvicorn.
|
||||
|
||||
## Running programmatically
|
||||
|
||||
To run directly from within a Python program, you should use `uvicorn.run(app, **config)`. For example:
|
||||
|
||||
```py title="main.py"
|
||||
import uvicorn
|
||||
|
||||
class App:
|
||||
...
|
||||
|
||||
app = App()
|
||||
|
||||
if __name__ == "__main__":
|
||||
uvicorn.run("main:app", host="127.0.0.1", port=5000, log_level="info")
|
||||
```
|
||||
|
||||
The set of configuration options is the same as for the command line tool.
|
||||
|
||||
Note that the application instance itself *can* be passed instead of the app
|
||||
import string.
|
||||
|
||||
```python
|
||||
uvicorn.run(app, host="127.0.0.1", port=5000, log_level="info")
|
||||
```
|
||||
|
||||
However, this style only works if you are not using multiprocessing (`workers=NUM`)
|
||||
or reloading (`reload=True`), so we recommend using the import string style.
|
||||
|
||||
Also note that in this case, you should put `uvicorn.run` into `if __name__ == '__main__'` clause in the main module.
|
||||
|
||||
!!! note
|
||||
The `reload` and `workers` parameters are **mutually exclusive**.
|
||||
|
||||
## Using a process manager
|
||||
|
||||
Running Uvicorn using a process manager ensures that you can run multiple processes in a resilient manner, and allows you to perform server upgrades without dropping requests.
|
||||
|
||||
A process manager will handle the socket setup, start-up multiple server processes, monitor process aliveness, and listen for signals to provide for processes restarts, shutdowns, or dialing up and down the number of running processes.
|
||||
|
||||
### Built-in
|
||||
|
||||
Uvicorn includes a `--workers` option that allows you to run multiple worker processes.
|
||||
|
||||
```bash
|
||||
$ uvicorn main:app --workers 4
|
||||
```
|
||||
|
||||
Unlike gunicorn, uvicorn does not use pre-fork, but uses [`spawn`](https://docs.python.org/3/library/multiprocessing.html#contexts-and-start-methods), which allows uvicorn's multiprocess manager to still work well on Windows.
|
||||
|
||||
The default process manager monitors the status of child processes and automatically restarts child processes that die unexpectedly. Not only that, it will also monitor the status of the child process through the pipeline. When the child process is accidentally stuck, the corresponding child process will be killed through an unstoppable system signal or interface.
|
||||
|
||||
You can also manage child processes by sending specific signals to the main process. (Not supported on Windows.)
|
||||
|
||||
- `SIGHUP`: Work processes are graceful restarted one after another. If you update the code, the new worker process will use the new code.
|
||||
- `SIGTTIN`: Increase the number of worker processes by one.
|
||||
- `SIGTTOU`: Decrease the number of worker processes by one.
|
||||
|
||||
### Gunicorn
|
||||
|
||||
!!! warning
|
||||
The `uvicorn.workers` module is deprecated and will be removed in a future release.
|
||||
|
||||
You should use the [`uvicorn-worker`](https://github.com/Kludex/uvicorn-worker) package instead.
|
||||
|
||||
```bash
|
||||
python -m pip install uvicorn-worker
|
||||
```
|
||||
|
||||
Gunicorn is probably the simplest way to run and manage Uvicorn in a production setting. Uvicorn includes a gunicorn worker class that means you can get set up with very little configuration.
|
||||
|
||||
The following will start Gunicorn with four worker processes:
|
||||
|
||||
`gunicorn -w 4 -k uvicorn.workers.UvicornWorker`
|
||||
|
||||
The `UvicornWorker` implementation uses the `uvloop` and `httptools` implementations. To run under PyPy you'll want to use pure-python implementation instead. You can do this by using the `UvicornH11Worker` class.
|
||||
|
||||
`gunicorn -w 4 -k uvicorn.workers.UvicornH11Worker`
|
||||
|
||||
Gunicorn provides a different set of configuration options to Uvicorn, so some options such as `--limit-concurrency` are not yet supported when running with Gunicorn.
|
||||
|
||||
If you need to pass uvicorn's config arguments to gunicorn workers then you'll have to subclass `UvicornWorker`:
|
||||
|
||||
```python
|
||||
from uvicorn.workers import UvicornWorker
|
||||
|
||||
class MyUvicornWorker(UvicornWorker):
|
||||
CONFIG_KWARGS = {"loop": "asyncio", "http": "h11", "lifespan": "off"}
|
||||
```
|
||||
|
||||
### Supervisor
|
||||
|
||||
To use `supervisor` as a process manager you should either:
|
||||
|
||||
* Hand over the socket to uvicorn using its file descriptor, which supervisor always makes available as `0`, and which must be set in the `fcgi-program` section.
|
||||
* Or use a UNIX domain socket for each `uvicorn` process.
|
||||
|
||||
A simple supervisor configuration might look something like this:
|
||||
|
||||
```ini title="supervisord.conf"
|
||||
[supervisord]
|
||||
|
||||
[fcgi-program:uvicorn]
|
||||
socket=tcp://localhost:8000
|
||||
command=venv/bin/uvicorn --fd 0 main:App
|
||||
numprocs=4
|
||||
process_name=uvicorn-%(process_num)d
|
||||
stdout_logfile=/dev/stdout
|
||||
stdout_logfile_maxbytes=0
|
||||
```
|
||||
|
||||
Then run with `supervisord -n`.
|
||||
|
||||
## Running behind Nginx
|
||||
|
||||
Using Nginx as a proxy in front of your Uvicorn processes may not be necessary, but is recommended for additional resilience. Nginx can deal with serving your static media and buffering slow requests, leaving your application servers free from load as much as possible.
|
||||
|
||||
In managed environments such as `Heroku`, you won't typically need to configure Nginx, as your server processes will already be running behind load balancing proxies.
|
||||
|
||||
The recommended configuration for proxying from Nginx is to use a UNIX domain socket between Nginx and whatever the process manager that is being used to run Uvicorn. If using Uvicorn directly you can bind it to a UNIX domain socket using `uvicorn --uds /path/to/socket.sock <...>`.
|
||||
|
||||
When running your application behind one or more proxies you will want to make sure that each proxy sets appropriate headers to ensure that your application can properly determine the client address of the incoming connection, and if the connection was over `http` or `https`. For more information see [Proxies and Forwarded Headers](#proxies-and-forwarded-headers) below.
|
||||
|
||||
Here's how a simple Nginx configuration might look. This example includes setting proxy headers, and using a UNIX domain socket to communicate with the application server.
|
||||
|
||||
It also includes some basic configuration to forward websocket connections.
|
||||
For more info on this, check [Nginx recommendations](https://nginx.org/en/docs/http/websocket.html).
|
||||
|
||||
```conf
|
||||
http {
|
||||
server {
|
||||
listen 80;
|
||||
client_max_body_size 4G;
|
||||
|
||||
server_name example.com;
|
||||
|
||||
location / {
|
||||
proxy_set_header Host $http_host;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection $connection_upgrade;
|
||||
proxy_redirect off;
|
||||
proxy_buffering off;
|
||||
proxy_pass http://uvicorn;
|
||||
}
|
||||
|
||||
location /static {
|
||||
# path for static files
|
||||
root /path/to/app/static;
|
||||
}
|
||||
}
|
||||
|
||||
map $http_upgrade $connection_upgrade {
|
||||
default upgrade;
|
||||
'' close;
|
||||
}
|
||||
|
||||
upstream uvicorn {
|
||||
server unix:/tmp/uvicorn.sock;
|
||||
}
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
Uvicorn's `--proxy-headers` behavior may not be sufficient for more complex proxy configurations that use different combinations of headers, or where the application is running behind more than one intermediary proxying service.
|
||||
|
||||
In those cases, you might want to use an ASGI middleware to set the `client` and `scheme` dependant on the request headers.
|
||||
|
||||
## Running behind a CDN
|
||||
|
||||
Running behind a content delivery network, such as Cloudflare or Cloud Front, provides a serious layer of protection against DDoS attacks. Your service will be running behind huge clusters of proxies and load balancers that are designed for handling huge amounts of traffic, and have capabilities for detecting and closing off connections from DDoS attacks.
|
||||
|
||||
Proper usage of cache control headers can mean that a CDN is able to serve large amounts of data without always having to forward the request on to your server.
|
||||
|
||||
Content Delivery Networks can also be a low-effort way to provide HTTPS termination.
|
||||
|
||||
## Running with HTTPS
|
||||
|
||||
To run uvicorn with https, a certificate and a private key are required.
|
||||
The recommended way to get them is using [Let's Encrypt](https://letsencrypt.org/).
|
||||
|
||||
For local development with https, it's possible to use [mkcert](https://github.com/FiloSottile/mkcert)
|
||||
to generate a valid certificate and private key.
|
||||
|
||||
```bash
|
||||
$ uvicorn main:app --port 5000 --ssl-keyfile=./key.pem --ssl-certfile=./cert.pem
|
||||
```
|
||||
|
||||
### Running gunicorn worker
|
||||
|
||||
It's also possible to use certificates with uvicorn's worker for gunicorn.
|
||||
|
||||
```bash
|
||||
$ gunicorn --keyfile=./key.pem --certfile=./cert.pem -k uvicorn.workers.UvicornWorker main:app
|
||||
```
|
||||
|
||||
### Customizing the SSL context
|
||||
|
||||
For TLS scenarios that the `--ssl-*` flags don't cover (e.g., mutual TLS, custom `SSLContext.options`, bumping `minimum_version`, loading certificates from memory), pass an `ssl_context_factory` to `uvicorn.run()` or `Config`.
|
||||
|
||||
The factory receives the `Config` instance and a `default_ssl_context_factory` callable that builds the standard context from the `ssl_*` settings on `Config`. Use it to start from uvicorn's default and mutate it, or ignore it and build your own context from scratch - the `ssl_*` settings are only consumed by the default factory, so if you don't call it they're effectively unused.
|
||||
|
||||
```python
|
||||
import ssl
|
||||
from collections.abc import Callable
|
||||
|
||||
import uvicorn
|
||||
from uvicorn.config import Config
|
||||
|
||||
|
||||
def ssl_context_factory(config: Config, default_ssl_context_factory: Callable[[], ssl.SSLContext]) -> ssl.SSLContext:
|
||||
context = default_ssl_context_factory()
|
||||
context.minimum_version = ssl.TLSVersion.TLSv1_3
|
||||
return context
|
||||
|
||||
|
||||
uvicorn.run(
|
||||
"main:app",
|
||||
ssl_keyfile="key.pem",
|
||||
ssl_certfile="cert.pem",
|
||||
ssl_context_factory=ssl_context_factory,
|
||||
)
|
||||
```
|
||||
|
||||
The factory is called inside each worker process, so it works with `--reload` and `--workers > 1`. The factory itself must be picklable in those modes (a top-level function is fine; lambdas and local closures are not). The `ssl_*` settings on `Config` are only consumed by `default_ssl_context_factory()`; if you build the context yourself without calling it, those settings are ignored.
|
||||
|
||||
## Proxies and Forwarded Headers
|
||||
|
||||
When running an application behind one or more proxies, certain information about the request is lost.
|
||||
To avoid this most proxies will add headers containing this information for downstream servers to read.
|
||||
|
||||
Uvicorn currently supports the following headers:
|
||||
|
||||
- `X-Forwarded-For` ([MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For))
|
||||
- `X-Forwarded-Proto`([MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto))
|
||||
|
||||
Uvicorn can use these headers to correctly set the client and protocol in the request.
|
||||
However as anyone can set these headers you must configure which "clients" you will trust to have set them correctly.
|
||||
|
||||
Uvicorn can be configured to trust IP Addresses (e.g. `127.0.0.1`), IP Networks (e.g. `10.100.0.0/16`),
|
||||
or Literals (e.g. `/path/to/socket.sock`). When running from CLI these are configured using `--forwarded-allow-ips`.
|
||||
|
||||
!!! Warning "Only trust clients you can actually trust!"
|
||||
Incorrectly trusting other clients can lead to malicious actors spoofing their apparent client address to your application.
|
||||
|
||||
For more information, check [`ProxyHeadersMiddleware`](https://github.com/Kludex/uvicorn/blob/main/uvicorn/middleware/proxy_headers.py).
|
||||
|
||||
### Client Port
|
||||
|
||||
Currently if the `ProxyHeadersMiddleware` is able to retrieve a trusted client value then the client's port will be set to `0`.
|
||||
This is because port information is lost when using these headers.
|
||||
|
||||
### UNIX Domain Sockets (UDS)
|
||||
|
||||
Although it is common for UNIX Domain Sockets to be used for communicating between various HTTP servers, they can mess with some of the expected received values as they will be various non-address strings or missing values.
|
||||
|
||||
For example:
|
||||
|
||||
- when NGINX itself is running behind a UDS it will add the literal `unix:` as the client in the `X-Forwarded-For` header.
|
||||
- When Uvicorn is running behind a UDS the initial client will be `None`.
|
||||
|
||||
### Trust Everything
|
||||
|
||||
Rather than specifying what to trust, you can instruct Uvicorn to trust all clients using the literal `"*"`.
|
||||
You should only set this when you know you can trust all values within the forwarded headers (e.g. because
|
||||
your proxies remove the existing headers before setting their own).
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 19 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 129 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 32 KiB |
503
docs/index.md
503
docs/index.md
@ -1,82 +1,68 @@
|
||||
<style>
|
||||
.md-typeset h1,
|
||||
.md-content__button {
|
||||
display: none;
|
||||
}
|
||||
</style>
|
||||
|
||||
<p align="center">
|
||||
<img width="320" height="320" src="../../uvicorn.png" alt='uvicorn'>
|
||||
<img width="320" height="320" src="https://raw.githubusercontent.com/tomchristie/uvicorn/master/docs/uvicorn.png" alt='uvicorn'>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<em>An ASGI web server, for Python.</em>
|
||||
<em>The lightning-fast ASGI server.</em>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="https://github.com/Kludex/uvicorn/actions">
|
||||
<img src="https://github.com/Kludex/uvicorn/workflows/Test%20Suite/badge.svg" alt="Test Suite">
|
||||
<a href="https://github.com/encode/uvicorn/actions">
|
||||
<img src="https://github.com/encode/uvicorn/workflows/Test%20Suite/badge.svg" alt="Test Suite">
|
||||
</a>
|
||||
<a href="https://pypi.org/project/uvicorn/">
|
||||
<img src="https://badge.fury.io/py/uvicorn.svg" alt="Package version">
|
||||
</a>
|
||||
<a href="https://pypi.org/project/uvicorn" target="_blank">
|
||||
<img src="https://img.shields.io/pypi/pyversions/uvicorn.svg?color=%2334D058" alt="Supported Python versions">
|
||||
</a>
|
||||
<a href="https://discord.gg/RxKUF5JuHs">
|
||||
<img src="https://img.shields.io/discord/1051468649518616576?logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2" alt="Discord">
|
||||
</a>
|
||||
</p>
|
||||
|
||||
---
|
||||
|
||||
**Documentation**: [https://uvicorn.dev](https://uvicorn.dev)
|
||||
# Introduction
|
||||
|
||||
**Source Code**: [https://www.github.com/Kludex/uvicorn](https://www.github.com/Kludex/uvicorn)
|
||||
|
||||
---
|
||||
|
||||
**Uvicorn** is an [ASGI](concepts/asgi.md) web server implementation for Python.
|
||||
Uvicorn is a lightning-fast ASGI server implementation, using [uvloop][uvloop] and [httptools][httptools].
|
||||
|
||||
Until recently Python has lacked a minimal low-level server/application interface for
|
||||
async frameworks. The [ASGI specification](https://asgi.readthedocs.io/en/latest/) fills this gap,
|
||||
and means we're now able to start building a common set of tooling usable across all async frameworks.
|
||||
asyncio frameworks. The [ASGI specification][asgi] fills this gap, and means we're now able to
|
||||
start building a common set of tooling usable across all asyncio frameworks.
|
||||
|
||||
Uvicorn currently supports **HTTP/1.1** and **WebSockets**.
|
||||
ASGI should help enable an ecosystem of Python web frameworks that are highly competitive against Node
|
||||
and Go in terms of achieving high throughput in IO-bound contexts. It also provides support for HTTP/2 and
|
||||
WebSockets, which cannot be handled by WSGI.
|
||||
|
||||
## Sponsorship
|
||||
|
||||
Help us keep Uvicorn maintained and sustainable by [becoming a sponsor](https://github.com/sponsors/Kludex).
|
||||
|
||||
**Current sponsors:**
|
||||
|
||||
<div style="display: flex; flex-wrap: wrap; gap: 2rem; align-items: center; margin: 1rem 0;">
|
||||
<a href="https://fastapi.tiangolo.com">
|
||||
<img src="img/fastapi-logo.png" alt="FastAPI" style="height: 80px;">
|
||||
</a>
|
||||
</div>
|
||||
Uvicorn currently supports HTTP/1.1 and WebSockets. Support for HTTP/2 is planned.
|
||||
|
||||
## Quickstart
|
||||
|
||||
**Uvicorn** is available on [PyPI](https://pypi.org/project/uvicorn/) so installation is as simple as:
|
||||
Install using `pip`:
|
||||
|
||||
=== "pip"
|
||||
```bash
|
||||
pip install uvicorn
|
||||
```
|
||||
```shell
|
||||
$ pip install uvicorn
|
||||
```
|
||||
|
||||
=== "uv"
|
||||
```bash
|
||||
uv add uvicorn
|
||||
```
|
||||
This will install uvicorn with minimal (pure Python) dependencies.
|
||||
|
||||
See the [installation documentation](installation.md) for more information.
|
||||
```shell
|
||||
$ pip install uvicorn[standard]
|
||||
```
|
||||
|
||||
---
|
||||
This will install uvicorn with "Cython-based" dependencies (where possible) and other "optional extras".
|
||||
|
||||
Let's create a simple ASGI application to run with Uvicorn:
|
||||
In this context, "Cython-based" means the following:
|
||||
|
||||
```python title="main.py"
|
||||
- the event loop `uvloop` will be installed and used if possible.
|
||||
- the http protocol will be handled by `httptools` if possible.
|
||||
|
||||
Moreover, "optional extras" means that:
|
||||
|
||||
- the websocket protocol will be handled by `websockets` (should you want to use `wsproto` you'd need to install it manually) if possible.
|
||||
- the `--reloader` flag in development mode will use `watchgod`.
|
||||
- windows users will have `colorama` installed for the colored logs.
|
||||
- `python-dotenv` will be installed should you want to use the `--env-file` option.
|
||||
- `PyYAML` will be installed to allow you to provide a `.yaml` file to `--log-config`, if desired.
|
||||
|
||||
Create an application, in `example.py`:
|
||||
|
||||
```python
|
||||
async def app(scope, receive, send):
|
||||
assert scope['type'] == 'http'
|
||||
|
||||
@ -84,8 +70,7 @@ async def app(scope, receive, send):
|
||||
'type': 'http.response.start',
|
||||
'status': 200,
|
||||
'headers': [
|
||||
(b'content-type', b'text/plain'),
|
||||
(b'content-length', b'13'),
|
||||
[b'content-type', b'text/plain'],
|
||||
],
|
||||
})
|
||||
await send({
|
||||
@ -94,90 +79,140 @@ async def app(scope, receive, send):
|
||||
})
|
||||
```
|
||||
|
||||
Then we can run it with Uvicorn:
|
||||
Run the server:
|
||||
|
||||
```shell
|
||||
uvicorn main:app
|
||||
$ uvicorn example:app
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
The uvicorn command line tool is the easiest way to run your application.
|
||||
The uvicorn command line tool is the easiest way to run your application...
|
||||
|
||||
### Command line options
|
||||
|
||||
```bash
|
||||
{{ uvicorn_help }}
|
||||
<!-- :cli_usage: -->
|
||||
```
|
||||
$ uvicorn --help
|
||||
Usage: uvicorn [OPTIONS] APP
|
||||
|
||||
Options:
|
||||
--host TEXT Bind socket to this host. [default:
|
||||
127.0.0.1]
|
||||
|
||||
--port INTEGER Bind socket to this port. [default: 8000]
|
||||
--uds TEXT Bind to a UNIX domain socket.
|
||||
--fd INTEGER Bind to socket from this file descriptor.
|
||||
--reload Enable auto-reload.
|
||||
--reload-dir TEXT Set reload directories explicitly, instead
|
||||
of using the current working directory.
|
||||
|
||||
--reload-delay FLOAT Delay between previous and next check if
|
||||
application needs to be. Defaults to 0.25s.
|
||||
[default: 0.25]
|
||||
|
||||
--workers INTEGER Number of worker processes. Defaults to the
|
||||
$WEB_CONCURRENCY environment variable if
|
||||
available. Not valid with --reload.
|
||||
|
||||
--loop [auto|asyncio|uvloop] Event loop implementation. [default: auto]
|
||||
--http [auto|h11|httptools] HTTP protocol implementation. [default:
|
||||
auto]
|
||||
|
||||
--ws [auto|none|websockets|wsproto]
|
||||
WebSocket protocol implementation.
|
||||
[default: auto]
|
||||
|
||||
--lifespan [auto|on|off] Lifespan implementation. [default: auto]
|
||||
--interface [auto|asgi3|asgi2|wsgi]
|
||||
Select ASGI3, ASGI2, or WSGI as the
|
||||
application interface. [default: auto]
|
||||
|
||||
--env-file PATH Environment configuration file.
|
||||
--log-config PATH Logging configuration file. Supported
|
||||
formats: .ini, .json, .yaml.
|
||||
|
||||
--log-level [critical|error|warning|info|debug|trace]
|
||||
Log level. [default: info]
|
||||
--access-log / --no-access-log Enable/Disable access log.
|
||||
--use-colors / --no-use-colors Enable/Disable colorized logging.
|
||||
--proxy-headers / --no-proxy-headers
|
||||
Enable/Disable X-Forwarded-Proto,
|
||||
X-Forwarded-For, X-Forwarded-Port to
|
||||
populate remote address info.
|
||||
|
||||
--forwarded-allow-ips TEXT Comma seperated list of IPs to trust with
|
||||
proxy headers. Defaults to the
|
||||
$FORWARDED_ALLOW_IPS environment variable if
|
||||
available, or '127.0.0.1'.
|
||||
|
||||
--root-path TEXT Set the ASGI 'root_path' for applications
|
||||
submounted below a given URL path.
|
||||
|
||||
--limit-concurrency INTEGER Maximum number of concurrent connections or
|
||||
tasks to allow, before issuing HTTP 503
|
||||
responses.
|
||||
|
||||
--backlog INTEGER Maximum number of connections to hold in
|
||||
backlog
|
||||
|
||||
--limit-max-requests INTEGER Maximum number of requests to service before
|
||||
terminating the process.
|
||||
|
||||
--timeout-keep-alive INTEGER Close Keep-Alive connections if no new data
|
||||
is received within this timeout. [default:
|
||||
5]
|
||||
|
||||
--ssl-keyfile TEXT SSL key file
|
||||
--ssl-certfile TEXT SSL certificate file
|
||||
--ssl-keyfile-password TEXT SSL keyfile password
|
||||
--ssl-version INTEGER SSL version to use (see stdlib ssl module's)
|
||||
[default: 2]
|
||||
|
||||
--ssl-cert-reqs INTEGER Whether client certificate is required (see
|
||||
stdlib ssl module's) [default: 0]
|
||||
|
||||
--ssl-ca-certs TEXT CA certificates file
|
||||
--ssl-ciphers TEXT Ciphers to use (see stdlib ssl module's)
|
||||
[default: TLSv1]
|
||||
|
||||
--header TEXT Specify custom default HTTP response headers
|
||||
as a Name:Value pair
|
||||
|
||||
--version Display the uvicorn version and exit.
|
||||
--app-dir TEXT Look for APP in the specified directory, by
|
||||
adding this to the PYTHONPATH. Defaults to
|
||||
the current working directory. [default: .]
|
||||
|
||||
--factory Treat APP as an application factory, i.e. a
|
||||
() -> <ASGI app> callable. [default: False]
|
||||
|
||||
--help Show this message and exit.
|
||||
```
|
||||
|
||||
For more information, see the [settings documentation](settings.md).
|
||||
|
||||
### Running programmatically
|
||||
|
||||
There are several ways to run uvicorn directly from your application.
|
||||
To run uvicorn directly from your application...
|
||||
|
||||
#### `uvicorn.run`
|
||||
**example.py**:
|
||||
|
||||
If you're looking for a programmatic equivalent of the `uvicorn` command line interface, use `uvicorn.run()`:
|
||||
|
||||
```py title="main.py"
|
||||
```python
|
||||
import uvicorn
|
||||
|
||||
async def app(scope, receive, send):
|
||||
...
|
||||
|
||||
if __name__ == "__main__":
|
||||
uvicorn.run("main:app", port=5000, log_level="info")
|
||||
```
|
||||
|
||||
#### `Config` and `Server` instances
|
||||
|
||||
For more control over configuration and server lifecycle, use `uvicorn.Config` and `uvicorn.Server`:
|
||||
|
||||
```py title="main.py"
|
||||
import uvicorn
|
||||
|
||||
async def app(scope, receive, send):
|
||||
...
|
||||
|
||||
if __name__ == "__main__":
|
||||
config = uvicorn.Config("main:app", port=5000, log_level="info")
|
||||
server = uvicorn.Server(config)
|
||||
server.run()
|
||||
```
|
||||
|
||||
If you'd like to run Uvicorn from an already running async environment, use `uvicorn.Server.serve()` instead:
|
||||
|
||||
```py title="main.py"
|
||||
import asyncio
|
||||
import uvicorn
|
||||
|
||||
async def app(scope, receive, send):
|
||||
...
|
||||
|
||||
async def main():
|
||||
config = uvicorn.Config("main:app", port=5000, log_level="info")
|
||||
server = uvicorn.Server(config)
|
||||
await server.serve()
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
uvicorn.run("example:app", host="127.0.0.1", port=5000, log_level="info")
|
||||
```
|
||||
|
||||
### Running with Gunicorn
|
||||
|
||||
!!! warning
|
||||
The `uvicorn.workers` module is deprecated and will be removed in a future release.
|
||||
|
||||
You should use the [`uvicorn-worker`](https://github.com/Kludex/uvicorn-worker) package instead.
|
||||
|
||||
```bash
|
||||
python -m pip install uvicorn-worker
|
||||
```
|
||||
|
||||
[Gunicorn](https://gunicorn.org/) is a mature, fully featured server and process manager.
|
||||
[Gunicorn][gunicorn] is a mature, fully featured server and process manager.
|
||||
|
||||
Uvicorn includes a Gunicorn worker class allowing you to run ASGI applications,
|
||||
with all of Uvicorn's performance benefits, while also giving you Gunicorn's
|
||||
@ -192,20 +227,266 @@ For production deployments we recommend using gunicorn with the uvicorn worker c
|
||||
gunicorn example:app -w 4 -k uvicorn.workers.UvicornWorker
|
||||
```
|
||||
|
||||
For a [PyPy](https://pypy.org/) compatible configuration use `uvicorn.workers.UvicornH11Worker`.
|
||||
For a [PyPy][pypy] compatible configuration use `uvicorn.workers.UvicornH11Worker`.
|
||||
|
||||
For more information, see the [deployment documentation](deployment/index.md).
|
||||
For more information, see the [deployment documentation](deployment.md).
|
||||
|
||||
### Application factories
|
||||
|
||||
The `--factory` flag allows loading the application from a factory function, rather than an application instance directly. The factory will be called with no arguments and should return an ASGI application.
|
||||
|
||||
```py title="main.py"
|
||||
**example.py**:
|
||||
|
||||
```python
|
||||
def create_app():
|
||||
app = ...
|
||||
return app
|
||||
```
|
||||
|
||||
```shell
|
||||
uvicorn --factory main:create_app
|
||||
$ uvicorn --factory example:create_app
|
||||
```
|
||||
|
||||
## The ASGI interface
|
||||
|
||||
Uvicorn uses the [ASGI specification][asgi] for interacting with an application.
|
||||
|
||||
The application should expose an async callable which takes three arguments:
|
||||
|
||||
* `scope` - A dictionary containing information about the incoming connection.
|
||||
* `receive` - A channel on which to receive incoming messages from the server.
|
||||
* `send` - A channel on which to send outgoing messages to the server.
|
||||
|
||||
Two common patterns you might use are either function-based applications:
|
||||
|
||||
```python
|
||||
async def app(scope, receive, send):
|
||||
assert scope['type'] == 'http'
|
||||
...
|
||||
```
|
||||
|
||||
Or instance-based applications:
|
||||
|
||||
```python
|
||||
class App:
|
||||
async def __call__(self, scope, receive, send):
|
||||
assert scope['type'] == 'http'
|
||||
...
|
||||
|
||||
app = App()
|
||||
```
|
||||
|
||||
It's good practice for applications to raise an exception on scope types
|
||||
that they do not handle.
|
||||
|
||||
The content of the `scope` argument, and the messages expected by `receive` and `send` depend on the protocol being used.
|
||||
|
||||
The format for HTTP messages is described in the [ASGI HTTP Message format][asgi-http].
|
||||
|
||||
### HTTP Scope
|
||||
|
||||
An incoming HTTP request might have a connection `scope` like this:
|
||||
|
||||
```python
|
||||
{
|
||||
'type': 'http.request',
|
||||
'scheme': 'http',
|
||||
'root_path': '',
|
||||
'server': ('127.0.0.1', 8000),
|
||||
'http_version': '1.1',
|
||||
'method': 'GET',
|
||||
'path': '/',
|
||||
'headers': [
|
||||
[b'host', b'127.0.0.1:8000'],
|
||||
[b'user-agent', b'curl/7.51.0'],
|
||||
[b'accept', b'*/*']
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### HTTP Messages
|
||||
|
||||
The instance coroutine communicates back to the server by sending messages to the `send` coroutine.
|
||||
|
||||
```python
|
||||
await send({
|
||||
'type': 'http.response.start',
|
||||
'status': 200,
|
||||
'headers': [
|
||||
[b'content-type', b'text/plain'],
|
||||
]
|
||||
})
|
||||
await send({
|
||||
'type': 'http.response.body',
|
||||
'body': b'Hello, world!',
|
||||
})
|
||||
```
|
||||
|
||||
### Requests & responses
|
||||
|
||||
Here's an example that displays the method and path used in the incoming request:
|
||||
|
||||
```python
|
||||
async def app(scope, receive, send):
|
||||
"""
|
||||
Echo the method and path back in an HTTP response.
|
||||
"""
|
||||
assert scope['type'] == 'http'
|
||||
|
||||
body = f'Received {scope["method"]} request to {scope["path"]}'
|
||||
await send({
|
||||
'type': 'http.response.start',
|
||||
'status': 200,
|
||||
'headers': [
|
||||
[b'content-type', b'text/plain'],
|
||||
]
|
||||
})
|
||||
await send({
|
||||
'type': 'http.response.body',
|
||||
'body': body.encode('utf-8'),
|
||||
})
|
||||
```
|
||||
|
||||
### Reading the request body
|
||||
|
||||
You can stream the request body without blocking the asyncio task pool,
|
||||
by fetching messages from the `receive` coroutine.
|
||||
|
||||
```python
|
||||
async def read_body(receive):
|
||||
"""
|
||||
Read and return the entire body from an incoming ASGI message.
|
||||
"""
|
||||
body = b''
|
||||
more_body = True
|
||||
|
||||
while more_body:
|
||||
message = await receive()
|
||||
body += message.get('body', b'')
|
||||
more_body = message.get('more_body', False)
|
||||
|
||||
return body
|
||||
|
||||
|
||||
async def app(scope, receive, send):
|
||||
"""
|
||||
Echo the request body back in an HTTP response.
|
||||
"""
|
||||
body = await read_body(receive)
|
||||
await send({
|
||||
'type': 'http.response.start',
|
||||
'status': 200,
|
||||
'headers': [
|
||||
[b'content-type', b'text/plain'],
|
||||
]
|
||||
})
|
||||
await send({
|
||||
'type': 'http.response.body',
|
||||
'body': body,
|
||||
})
|
||||
```
|
||||
|
||||
### Streaming responses
|
||||
|
||||
You can stream responses by sending multiple `http.response.body` messages to
|
||||
the `send` coroutine.
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
|
||||
|
||||
async def app(scope, receive, send):
|
||||
"""
|
||||
Send a slowly streaming HTTP response back to the client.
|
||||
"""
|
||||
await send({
|
||||
'type': 'http.response.start',
|
||||
'status': 200,
|
||||
'headers': [
|
||||
[b'content-type', b'text/plain'],
|
||||
]
|
||||
})
|
||||
for chunk in [b'Hello', b', ', b'world!']:
|
||||
await send({
|
||||
'type': 'http.response.body',
|
||||
'body': chunk,
|
||||
'more_body': True
|
||||
})
|
||||
await asyncio.sleep(1)
|
||||
await send({
|
||||
'type': 'http.response.body',
|
||||
'body': b'',
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Alternative ASGI servers
|
||||
|
||||
### Daphne
|
||||
|
||||
The first ASGI server implementation, originally developed to power Django Channels, is [the Daphne webserver][daphne].
|
||||
|
||||
It is run widely in production, and supports HTTP/1.1, HTTP/2, and WebSockets.
|
||||
|
||||
Any of the example applications given here can equally well be run using `daphne` instead.
|
||||
|
||||
```
|
||||
$ pip install daphne
|
||||
$ daphne app:App
|
||||
```
|
||||
|
||||
### Hypercorn
|
||||
|
||||
[Hypercorn][hypercorn] was initially part of the Quart web framework, before
|
||||
being separated out into a standalone ASGI server.
|
||||
|
||||
Hypercorn supports HTTP/1.1, HTTP/2, and WebSockets.
|
||||
|
||||
```
|
||||
$ pip install hypercorn
|
||||
$ hypercorn app:App
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ASGI frameworks
|
||||
|
||||
You can use Uvicorn, Daphne, or Hypercorn to run any ASGI framework.
|
||||
|
||||
For small services you can also write ASGI applications directly.
|
||||
|
||||
### Starlette
|
||||
|
||||
[Starlette](https://github.com/encode/starlette) is a lightweight ASGI framework/toolkit.
|
||||
|
||||
It is ideal for building high performance asyncio services, and supports both HTTP and WebSockets.
|
||||
|
||||
### Django Channels
|
||||
|
||||
The ASGI specification was originally designed for use with [Django Channels](https://channels.readthedocs.io/en/latest/).
|
||||
|
||||
Channels is a little different to other ASGI frameworks in that it provides
|
||||
an asynchronous frontend onto a threaded-framework backend. It allows Django
|
||||
to support WebSockets, background tasks, and long-running connections,
|
||||
with application code still running in a standard threaded context.
|
||||
|
||||
### Quart
|
||||
|
||||
[Quart](https://pgjones.gitlab.io/quart/) is a Flask-like ASGI web framework.
|
||||
|
||||
### FastAPI
|
||||
|
||||
[**FastAPI**](https://github.com/tiangolo/fastapi) is an API framework based on **Starlette** and **Pydantic**, heavily inspired by previous server versions of **APIStar**.
|
||||
|
||||
You write your API function parameters with Python 3.6+ type declarations and get automatic data conversion, data validation, OpenAPI schemas (with JSON Schemas) and interactive API documentation UIs.
|
||||
|
||||
|
||||
[uvloop]: https://github.com/MagicStack/uvloop
|
||||
[httptools]: https://github.com/MagicStack/httptools
|
||||
[gunicorn]: http://gunicorn.org/
|
||||
[pypy]: https://pypy.org/
|
||||
[asgi]: https://asgi.readthedocs.io/en/latest/
|
||||
[asgi-http]: https://asgi.readthedocs.io/en/latest/specs/www.html
|
||||
[daphne]: https://github.com/django/daphne
|
||||
[hypercorn]: https://gitlab.com/pgjones/hypercorn
|
||||
|
||||
@ -1,75 +0,0 @@
|
||||
**Uvicorn** is available on [PyPI](https://pypi.org/project/uvicorn/) so installation is as simple as:
|
||||
|
||||
=== "pip"
|
||||
|
||||
```bash
|
||||
pip install uvicorn
|
||||
```
|
||||
|
||||
=== "uv"
|
||||
|
||||
```bash
|
||||
uv add uvicorn
|
||||
```
|
||||
|
||||
The above will install Uvicorn with the minimal set of dependencies:
|
||||
|
||||
- [`h11`](https://github.com/python-hyper/h11) — Pure Python sans-io HTTP/1.1 implementation.
|
||||
- [`click`](https://github.com/pallets/click) — Command line interface library.
|
||||
|
||||
If you are running on Python 3.10 or early versions,
|
||||
[`typing_extensions`](https://github.com/python/typing_extensions) will also be installed.
|
||||
|
||||
## Optional Dependencies
|
||||
|
||||
There are many optional dependencies that can be installed to add support for various features.
|
||||
|
||||
If you just want to install all of them at once, you can use the `standard` extra:
|
||||
|
||||
=== "pip"
|
||||
```bash
|
||||
pip install 'uvicorn[standard]'
|
||||
```
|
||||
|
||||
=== "uv"
|
||||
```bash
|
||||
uv add 'uvicorn[standard]'
|
||||
```
|
||||
|
||||
The `standard` extra installs the following dependencies:
|
||||
|
||||
- **[`uvloop`](https://github.com/MagicStack/uvloop) — Fast, drop-in replacement of the built-in asyncio event loop.**
|
||||
|
||||
When `uvloop` is installed, Uvicorn will use it by default.
|
||||
|
||||
- **[`httptools`](https://github.com/MagicStack/httptools) — Python binding for the Node.js HTTP parser.**
|
||||
|
||||
When `httptools` is installed, Uvicorn will use it by default for HTTP/1.1 parsing.
|
||||
|
||||
You can read this issue to understand how it compares with `h11`: [h11/issues/9](https://github.com/python-hyper/h11/issues/9).
|
||||
|
||||
- **[`websockets`](https://websockets.readthedocs.io/en/stable/) — WebSocket library for Python.**
|
||||
|
||||
When `websockets` is installed, Uvicorn will use it by default for WebSocket handling.
|
||||
|
||||
You can alternatively install **[`wsproto`](https://github.com/python-hyper/wsproto)** and set the `--ws`
|
||||
option to `wsproto` to use it instead.
|
||||
|
||||
- **[`watchfiles`](https://github.com/samuelcolvin/watchfiles) — Simple, modern and high performance file
|
||||
watching and code reload in python.**
|
||||
|
||||
When `watchfiles` is installed, Uvicorn will use it by default for the `--reload` option.
|
||||
|
||||
- **[`colorama`](https://github.com/tartley/colorama) — Cross-platform support for ANSI terminal
|
||||
colors.**
|
||||
|
||||
This is installed only on Windows, to provide colored logs.
|
||||
|
||||
- **[`python-dotenv`](https://github.com/theskumar/python-dotenv) — Reads key-value pairs from a `.env` file
|
||||
and adds them to the environment.**
|
||||
|
||||
This is installed to allow you to use the `--env-file` option.
|
||||
|
||||
- **[`PyYAML`](https://github.com/yaml/pyyaml) — YAML parser and emitter for Python.**
|
||||
|
||||
This is installed to allow you to provide a `.yaml` file to the `--log-config` option.
|
||||
3
docs/js/chat.js
Normal file
3
docs/js/chat.js
Normal file
@ -0,0 +1,3 @@
|
||||
((window.gitter = {}).chat = {}).options = {
|
||||
room: 'encode/community'
|
||||
};
|
||||
6
docs/js/sidecar-1.5.0.js
Normal file
6
docs/js/sidecar-1.5.0.js
Normal file
File diff suppressed because one or more lines are too long
@ -1,12 +0,0 @@
|
||||
{% extends "base.html" %}
|
||||
|
||||
{% block extrahead %}
|
||||
{{ super() }}
|
||||
<script>
|
||||
// Redirect starlette.io to starlette.dev
|
||||
if (window.location.hostname === 'www.uvicorn.org' || window.location.hostname === 'uvicorn.org') {
|
||||
const newUrl = window.location.href.replace(/^https?:\/\/(www\.)?uvicorn\.org/, 'https://uvicorn.dev');
|
||||
window.location.replace(newUrl);
|
||||
}
|
||||
</script>
|
||||
{% endblock %}
|
||||
@ -1,58 +0,0 @@
|
||||
{% import "partials/nav-item.html" as item with context %}
|
||||
|
||||
<!-- Determine class according to configuration -->
|
||||
{% set class = "md-nav md-nav--primary" %}
|
||||
{% if "navigation.tabs" in features %}
|
||||
{% set class = class ~ " md-nav--lifted" %}
|
||||
{% endif %}
|
||||
{% if "toc.integrate" in features %}
|
||||
{% set class = class ~ " md-nav--integrated" %}
|
||||
{% endif %}
|
||||
|
||||
<!-- Main navigation -->
|
||||
<nav
|
||||
class="{{ class }}"
|
||||
aria-label="{{ lang.t('nav.title') }}"
|
||||
data-md-level="0"
|
||||
>
|
||||
|
||||
<!-- Site title -->
|
||||
<label class="md-nav__title" for="__drawer">
|
||||
<a
|
||||
href="{{ config.extra.homepage | d(nav.homepage.url, true) | url }}"
|
||||
title="{{ config.site_name | e }}"
|
||||
class="md-nav__button md-logo"
|
||||
aria-label="{{ config.site_name }}"
|
||||
data-md-component="logo"
|
||||
>
|
||||
{% include "partials/logo.html" %}
|
||||
</a>
|
||||
{{ config.site_name }}
|
||||
</label>
|
||||
|
||||
<!-- Repository information -->
|
||||
{% if config.repo_url %}
|
||||
<div class="md-nav__source">
|
||||
{% include "partials/source.html" %}
|
||||
</div>
|
||||
{% endif %}
|
||||
|
||||
<!-- Navigation list -->
|
||||
<ul class="md-nav__list" data-md-scrollfix>
|
||||
{% for nav_item in nav %}
|
||||
{% set path = "__nav_" ~ loop.index %}
|
||||
{{ item.render(nav_item, path, 1) }}
|
||||
{% endfor %}
|
||||
</ul>
|
||||
|
||||
<!-- Sponsors -->
|
||||
<div class="md-nav__sponsors">
|
||||
<p class="md-nav__sponsors-title">Sponsors</p>
|
||||
<a href="https://fastapi.tiangolo.com" title="FastAPI" class="md-nav__sponsor">
|
||||
<img src="{{ 'img/fastapi-logo.png' | url }}" alt="FastAPI">
|
||||
</a>
|
||||
<a href="https://github.com/sponsors/Kludex" class="md-nav__sponsor-cta">
|
||||
Become a sponsor! ❤️
|
||||
</a>
|
||||
</div>
|
||||
</nav>
|
||||
@ -1,18 +0,0 @@
|
||||
<!-- Copied from https://github.com/squidfunk/mkdocs-material/issues/4827#issuecomment-1869812019 -->
|
||||
<li class="md-nav__item"></li>
|
||||
<a href="{{ toc_item.url }}" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
{{ toc_item.title }}
|
||||
</span>
|
||||
</a>
|
||||
|
||||
<!-- Table of contents list -->
|
||||
{% if toc_item.children %}
|
||||
<nav class="md-nav" aria-label="{{ toc_item.title | striptags }}">
|
||||
<ul class="md-nav__list">
|
||||
{% for toc_item in toc_item.children %}
|
||||
{% if not page.meta.toc_depth or toc_item.level <= page.meta.toc_depth %} {% include "partials/toc-item.html" %}
|
||||
{% endif %} {% endfor %} </ul>
|
||||
</nav>
|
||||
{% endif %}
|
||||
</li>
|
||||
@ -1,42 +0,0 @@
|
||||
from __future__ import annotations as _annotations
|
||||
|
||||
import re
|
||||
import subprocess
|
||||
from functools import lru_cache
|
||||
|
||||
from mkdocs.config import Config
|
||||
from mkdocs.structure.files import Files
|
||||
from mkdocs.structure.pages import Page
|
||||
|
||||
|
||||
def on_page_content(html: str, page: Page, config: Config, files: Files) -> str:
|
||||
"""Called on each page after the markdown is converted to HTML."""
|
||||
html = add_hyperlink_to_pull_request(html, page, config, files)
|
||||
return html
|
||||
|
||||
|
||||
def add_hyperlink_to_pull_request(html: str, page: Page, config: Config, files: Files) -> str:
|
||||
"""Add hyperlink on PRs mentioned on the release notes page.
|
||||
|
||||
If we find "(#\\d+)" it will be added an hyperlink to https://github.com/Kludex/uvicorn/pull/$1.
|
||||
"""
|
||||
if not page.file.name == "release-notes":
|
||||
return html
|
||||
|
||||
return re.sub(r"\(#(\d+)\)", r"(<a href='https://github.com/Kludex/uvicorn/pull/\1'>#\1</a>)", html)
|
||||
|
||||
|
||||
def on_page_markdown(markdown: str, page: Page, config: Config, files: Files) -> str:
|
||||
"""Called on each file after it is read and before it is converted to HTML."""
|
||||
markdown = uvicorn_print_help(markdown, page)
|
||||
return markdown
|
||||
|
||||
|
||||
def uvicorn_print_help(markdown: str, page: Page) -> str:
|
||||
return re.sub(r"{{ *uvicorn_help *}}", get_uvicorn_help(), markdown)
|
||||
|
||||
|
||||
@lru_cache
|
||||
def get_uvicorn_help():
|
||||
output = subprocess.run(["uvicorn", "--help"], capture_output=True, check=True)
|
||||
return output.stdout.decode()
|
||||
@ -1,806 +0,0 @@
|
||||
---
|
||||
toc_depth: 2
|
||||
---
|
||||
|
||||
## 0.47.0 (May 14, 2026)
|
||||
|
||||
### Added
|
||||
|
||||
* Add `ssl_context_factory` for custom `SSLContext` configuration (#2920)
|
||||
|
||||
### Changed
|
||||
|
||||
* Eagerly import the ASGI app in the parent process (#2919)
|
||||
|
||||
### Fixed
|
||||
|
||||
* Treat `fd=0` as a valid file descriptor with reload/workers (#2927)
|
||||
|
||||
## 0.46.0 (April 23, 2026)
|
||||
|
||||
### Added
|
||||
|
||||
* Support `ws_max_size` in `wsproto` implementation (#2915)
|
||||
* Support `ws_ping_interval` and `ws_ping_timeout` in `wsproto` implementation (#2916)
|
||||
|
||||
### Changed
|
||||
|
||||
* Use `bytearray` for incoming WebSocket message buffer in `websockets-sansio` (#2917)
|
||||
|
||||
## 0.45.0 (April 21, 2026)
|
||||
|
||||
### Added
|
||||
|
||||
* Add `--reset-contextvars` flag to isolate ASGI request context (#2912)
|
||||
* Accept `os.PathLike` for `log_config` (#2905)
|
||||
* Accept `log_level` strings case-insensitively (#2907)
|
||||
|
||||
### Changed
|
||||
|
||||
* Revert "Emit `http.disconnect` on server shutdown for streaming responses" (#2913)
|
||||
* Revert "Explicitly start ASGI run with empty context" (#2911)
|
||||
|
||||
### Fixed
|
||||
|
||||
* Preserve forwarded client ports in proxy headers middleware (#2903)
|
||||
* Raise helpful `ImportError` when PyYAML is missing for YAML log config (#2906)
|
||||
|
||||
## 0.44.0 (April 6, 2026)
|
||||
|
||||
### Added
|
||||
|
||||
* Implement websocket keepalive pings for websockets-sansio (#2888)
|
||||
|
||||
## 0.43.0 (April 3, 2026)
|
||||
|
||||
You can quit Uvicorn now. We heard you, @pamelafox - all 47 of your Ctrl+C's (thanks for flagging it, and thanks to @tiangolo for the fix 🙏). [See the tweet](https://x.com/pamelafox/status/2039097686155227623).
|
||||
|
||||
### Changed
|
||||
|
||||
* Emit `http.disconnect` ASGI `receive()` event on server shutting down for streaming responses (#2829)
|
||||
* Use native `context` parameter for `create_task` on Python 3.11+ (#2859)
|
||||
* Drop cast in ASGI types (#2875)
|
||||
|
||||
## 0.42.0 (March 16, 2026)
|
||||
|
||||
### Changed
|
||||
|
||||
* Use `bytearray` for request body accumulation to avoid O(n^2) allocation on fragmented bodies (#2845)
|
||||
|
||||
### Fixed
|
||||
|
||||
* Escape brackets and backslash in httptools `HEADER_RE` regex (#2824)
|
||||
* Fix multiple issues in websockets sans-io implementation (#2825)
|
||||
|
||||
## 0.41.0 (February 16, 2026)
|
||||
|
||||
### Added
|
||||
|
||||
* Add `--limit-max-requests-jitter` to stagger worker restarts (#2707)
|
||||
* Add socket path to `scope["server"]` (#2561)
|
||||
|
||||
### Changed
|
||||
|
||||
* Rename `LifespanOn.error_occured` to `error_occurred` (#2776)
|
||||
|
||||
### Fixed
|
||||
|
||||
* Ignore permission denied errors in watchfiles reloader (#2817)
|
||||
* Ensure lifespan shutdown runs when `should_exit` is set during startup (#2812)
|
||||
* Reduce the log level of 'request limit exceeded' messages (#2788)
|
||||
|
||||
## 0.40.0 (December 21, 2025)
|
||||
|
||||
### Remove
|
||||
|
||||
* Drop support for Python 3.9 (#2772)
|
||||
|
||||
## 0.39.0 (December 21, 2025)
|
||||
|
||||
### Fixed
|
||||
|
||||
* Send close frame on ASGI return for WebSockets (#2769)
|
||||
* Explicitly start ASGI run with empty context (#2742)
|
||||
|
||||
## 0.38.0 (October 18, 2025)
|
||||
|
||||
### Added
|
||||
|
||||
* Support Python 3.14 (#2723)
|
||||
|
||||
## 0.37.0 (September 23, 2025)
|
||||
|
||||
### Added
|
||||
|
||||
* Add `--timeout-worker-healthcheck` option (#2711)
|
||||
* Add `os.PathLike[str]` type to `ssl_ca_certs` (#2676)
|
||||
|
||||
## 0.36.1 (September 23, 2025)
|
||||
|
||||
### Fixed
|
||||
|
||||
* Raise an exception when calling removed `Config.setup_event_loop()` (#2709)
|
||||
|
||||
## 0.36.0 (September 20, 2025)
|
||||
|
||||
### Added
|
||||
|
||||
* Support custom IOLOOPs (#2435)
|
||||
* Allow to provide importable string in `--http`, `--ws` and `--loop` (#2658)
|
||||
|
||||
## 0.35.0 (June 28, 2025)
|
||||
|
||||
### Added
|
||||
|
||||
* Add `WebSocketsSansIOProtocol` (#2540)
|
||||
|
||||
### Changed
|
||||
|
||||
* Refine help message for option `--proxy-headers` (#2653)
|
||||
|
||||
## 0.34.3 (June 1, 2025)
|
||||
|
||||
### Fixed
|
||||
|
||||
* Don't include `cwd()` when non-empty `--reload-dirs` is passed (#2598)
|
||||
* Apply `get_client_addr` formatting to WebSocket logging (#2636)
|
||||
|
||||
## 0.34.2 (April 19, 2025)
|
||||
|
||||
### Fixed
|
||||
|
||||
* Flush stdout buffer on Windows to trigger reload (#2604)
|
||||
|
||||
## 0.34.1 (April 13, 2025)
|
||||
|
||||
### Deprecated
|
||||
|
||||
* Deprecate `ServerState` in the main module (#2581)
|
||||
|
||||
## 0.34.0 (December 15, 2024)
|
||||
|
||||
### Added
|
||||
|
||||
* Add `content-length` to 500 response in `wsproto` implementation (#2542)
|
||||
|
||||
### Removed
|
||||
|
||||
* Drop support for Python 3.8 (#2543)
|
||||
|
||||
## 0.33.0 (December 14, 2024)
|
||||
|
||||
### Removed
|
||||
|
||||
* Remove `WatchGod` support for `--reload` (#2536)
|
||||
|
||||
## 0.32.1 (November 20, 2024)
|
||||
|
||||
### Fixed
|
||||
|
||||
* Drop ASGI spec version to 2.3 on HTTP scope (#2513)
|
||||
* Enable httptools lenient data on `httptools >= 0.6.3` (#2488)
|
||||
|
||||
## 0.32.0 (October 15, 2024)
|
||||
|
||||
### Added
|
||||
|
||||
* Officially support Python 3.13 (#2482)
|
||||
* Warn when `max_request_limit` is exceeded (#2430)
|
||||
|
||||
## 0.31.1 (October 9, 2024)
|
||||
|
||||
### Fixed
|
||||
|
||||
* Support WebSockets 0.13.1 (#2471)
|
||||
* Restore support for `[*]` in trusted hosts (#2480)
|
||||
* Add `PathLike[str]` type hint for `ssl_keyfile` (#2481)
|
||||
|
||||
## 0.31.0 (September 27, 2024)
|
||||
|
||||
### Added
|
||||
|
||||
Improve `ProxyHeadersMiddleware` (#2468) and (#2231):
|
||||
|
||||
- Fix the host for requests from clients running on the proxy server itself.
|
||||
- Fallback to host that was already set for empty x-forwarded-for headers.
|
||||
- Also allow to specify IP Networks as trusted hosts. This greatly simplifies deployments
|
||||
on docker swarm/kubernetes, where the reverse proxy might have a dynamic IP.
|
||||
- This includes support for IPv6 Address/Networks.
|
||||
|
||||
## 0.30.6 (August 13, 2024)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Don't warn when upgrade is not WebSocket and dependencies are installed (#2360)
|
||||
|
||||
## 0.30.5 (August 2, 2024)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Don't close connection before receiving body on H11 (#2408)
|
||||
|
||||
## 0.30.4 (July 31, 2024)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Close connection when `h11` sets client state to `MUST_CLOSE` (#2375)
|
||||
|
||||
## 0.30.3 (July 20, 2024)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Suppress `KeyboardInterrupt` from CLI and programmatic usage (#2384)
|
||||
- `ClientDisconnect` inherits from `OSError` instead of `IOError` (#2393)
|
||||
|
||||
## 0.30.2 (July 20, 2024)
|
||||
|
||||
### Added
|
||||
|
||||
- Add `reason` support to [`websocket.disconnect`](https://asgi.readthedocs.io/en/latest/specs/www.html#disconnect-receive-event-ws) event (#2324)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Iterate subprocesses in-place on the process manager (#2373)
|
||||
|
||||
## 0.30.1 (June 2, 2024)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Allow horizontal tabs `\t` in response header values (#2345)
|
||||
|
||||
## 0.30.0 (May 28, 2024)
|
||||
|
||||
### Added
|
||||
|
||||
- New multiprocess manager (#2183)
|
||||
- Allow `ConfigParser` or a `io.IO[Any]` on `log_config` (#1976)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Suppress side-effects of signal propagation (#2317)
|
||||
- Send `content-length` header on 5xx (#2304)
|
||||
|
||||
### Deprecated
|
||||
|
||||
- Deprecate the `uvicorn.workers` module (#2302)
|
||||
|
||||
## 0.29.0 (March 19, 2024)
|
||||
|
||||
### Added
|
||||
|
||||
- Cooperative signal handling (#1600)
|
||||
|
||||
## 0.28.1 (March 19, 2024)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Revert raise `ClientDisconnected` on HTTP (#2276)
|
||||
|
||||
## 0.28.0 (March 9, 2024)
|
||||
|
||||
### Added
|
||||
|
||||
- Raise `ClientDisconnected` on `send()` when client disconnected (#2220)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Except `AttributeError` on `sys.stdin.fileno()` for Windows IIS10 (#1947)
|
||||
- Use `X-Forwarded-Proto` for WebSockets scheme when the proxy provides it (#2258)
|
||||
|
||||
## 0.27.1 (February 10, 2024)
|
||||
|
||||
- Fix spurious LocalProtocolError errors when processing pipelined requests (#2243)
|
||||
|
||||
## 0.27.0.post1 (January 29, 2024)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Fix nav overrides for newer version of Mkdocs Material (#2233)
|
||||
|
||||
## 0.27.0 (January 22, 2024)
|
||||
|
||||
### Added
|
||||
|
||||
- Raise `ClientDisconnect(IOError)` on `send()` when client disconnected (#2218)
|
||||
- Bump ASGI WebSocket spec version to 2.4 (#2221)
|
||||
|
||||
## 0.26.0 (January 16, 2024)
|
||||
|
||||
### Changed
|
||||
|
||||
- Update `--root-path` to include the root path prefix in the full ASGI `path` as per the ASGI spec (#2213)
|
||||
- Use `__future__.annotations` on some internal modules (#2199)
|
||||
|
||||
## 0.25.0 (December 17, 2023)
|
||||
|
||||
### Added
|
||||
|
||||
- Support the WebSocket Denial Response ASGI extension (#1916)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Allow explicit hidden file paths on `--reload-include` (#2176)
|
||||
- Properly annotate `uvicorn.run()` (#2158)
|
||||
|
||||
## 0.24.0.post1 (November 6, 2023)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Revert mkdocs-material from 9.1.21 to 9.2.6 (#2148)
|
||||
|
||||
## 0.24.0 (November 4, 2023)
|
||||
|
||||
### Added
|
||||
|
||||
- Support Python 3.12 (#2145)
|
||||
- Allow setting `app` via environment variable `UVICORN_APP` (#2106)
|
||||
|
||||
## 0.23.2 (July 31, 2023)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Maintain the same behavior of `websockets` from 10.4 on 11.0 (#2061)
|
||||
|
||||
## 0.23.1 (July 18, 2023)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Add `typing_extensions` for Python 3.10 and lower (#2053)
|
||||
|
||||
## 0.23.0 (July 10, 2023)
|
||||
|
||||
### Added
|
||||
|
||||
- Add `--ws-max-queue` parameter WebSockets (#2033)
|
||||
|
||||
### Removed
|
||||
|
||||
- Drop support for Python 3.7 (#1996)
|
||||
- Remove `asgiref` as typing dependency (#1999)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Set `scope["scheme"]` to `ws` or `wss` instead of `http` or `https` on `ProxyHeadersMiddleware` for WebSockets (#2043)
|
||||
|
||||
### Changed
|
||||
|
||||
- Raise `ImportError` on circular import (#2040)
|
||||
- Use `logger.getEffectiveLevel()` instead of `logger.level` to check if log level is `TRACE` (#1966)
|
||||
|
||||
## 0.22.0 (April 28, 2023)
|
||||
|
||||
### Added
|
||||
|
||||
- Add `--timeout-graceful-shutdown` parameter (#1950)
|
||||
- Handle `SIGBREAK` on Windows (#1909)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Shutdown event is now being triggered on Windows when using hot reload (#1584)
|
||||
- `--reload-delay` is effectively used on the `watchfiles` reloader (#1930)
|
||||
|
||||
## 0.21.1 (March 16, 2023)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Reset lifespan state on each request (#1903)
|
||||
|
||||
## 0.21.0 (March 9, 2023)
|
||||
|
||||
### Added
|
||||
|
||||
- Introduce lifespan state (#1818)
|
||||
- Allow headers to be sent as iterables on H11 implementation (#1782)
|
||||
- Improve discoverability when --port=0 is used (#1890)
|
||||
|
||||
### Changed
|
||||
|
||||
- Avoid importing `h11` and `pyyaml` when not needed to improve import time (#1846)
|
||||
- Replace current native `WSGIMiddleware` implementation by `a2wsgi` (#1825)
|
||||
- Change default `--app-dir` from "." (dot) to "" (empty string) (#1835)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Send code 1012 on shutdown for WebSockets (#1816)
|
||||
- Use `surrogateescape` to encode headers on `websockets` implementation (#1005)
|
||||
- Fix warning message on reload failure (#1784)
|
||||
|
||||
## 0.20.0 (November 20, 2022)
|
||||
|
||||
### Added
|
||||
|
||||
- Check if handshake is completed before sending frame on `wsproto` shutdown (#1737)
|
||||
- Add default headers to WebSockets implementations (#1606 & #1747)
|
||||
- Warn user when `reload` and `workers` flag are used together (#1731)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Use correct `WebSocket` error codes on `close` (#1753)
|
||||
- Send disconnect event on connection lost for `wsproto` (#996)
|
||||
- Add `SIGQUIT` handler to `UvicornWorker` (#1710)
|
||||
- Fix crash on exist with "--uds" if socket doesn't exist (#1725)
|
||||
- Annotate `CONFIG_KWARGS` in `UvicornWorker` class (#1746)
|
||||
|
||||
### Removed
|
||||
|
||||
- Remove conditional on `RemoteProtocolError.event_hint` on `wsproto` (#1486)
|
||||
- Remove unused `handle_no_connect` on `wsproto` implementation (#1759)
|
||||
|
||||
## 0.19.0 (October 19, 2022)
|
||||
|
||||
### Added
|
||||
|
||||
- Support Python 3.11 (#1652)
|
||||
- Bump minimal `httptools` version to `0.5.0` (#1645)
|
||||
- Ignore HTTP/2 upgrade and optionally ignore WebSocket upgrade (#1661)
|
||||
- Add `py.typed` to comply with PEP 561 (#1687)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Set `propagate` to `False` on "uvicorn" logger (#1288)
|
||||
- USR1 signal is now handled correctly on `UvicornWorker`. (#1565)
|
||||
- Use path with query string on `WebSockets` logs (#1385)
|
||||
- Fix behavior on which "Date" headers were not updated on the same connection (#1706)
|
||||
|
||||
### Removed
|
||||
|
||||
- Remove the `--debug` flag (#1640)
|
||||
- Remove the `DebugMiddleware` (#1697)
|
||||
|
||||
## 0.18.3 (August 24, 2022)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Remove cyclic references on HTTP implementations. (#1604)
|
||||
|
||||
### Changed
|
||||
|
||||
- `reload_delay` default changed from `None` to `0.25` on `uvicorn.run()` and `Config`. `None` is not an acceptable value anymore. (#1545)
|
||||
|
||||
## 0.18.2 (June 27, 2022)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Add default `log_config` on `uvicorn.run()` (#1541)
|
||||
- Revert `logging` file name modification (#1543)
|
||||
|
||||
## 0.18.1 (June 23, 2022)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Use `DEFAULT_MAX_INCOMPLETE_EVENT_SIZE` as default to `h11_max_incomplete_event_size` on the CLI (#1534)
|
||||
|
||||
## 0.18.0 (June 23, 2022)
|
||||
|
||||
### Added
|
||||
|
||||
- The `reload` flag prioritizes `watchfiles` instead of the deprecated `watchgod` (#1437)
|
||||
- Annotate `uvicorn.run()` function (#1423)
|
||||
- Allow configuring `max_incomplete_event_size` for `h11` implementation (#1514)
|
||||
|
||||
### Removed
|
||||
|
||||
- Remove `asgiref` dependency (#1532)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Turn `raw_path` into bytes on both websockets implementations (#1487)
|
||||
- Revert log exception traceback in case of invalid HTTP request (#1518)
|
||||
- Set `asyncio.WindowsSelectorEventLoopPolicy()` when using multiple workers to avoid "WinError 87" (#1454)
|
||||
|
||||
## 0.17.6 (March 11, 2022)
|
||||
|
||||
### Changed
|
||||
|
||||
- Change `httptools` range to `>=0.4.0` (#1400)
|
||||
|
||||
## 0.17.5 (February 16, 2022)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Fix case where url is fragmented in httptools protocol (#1263)
|
||||
- Fix WSGI middleware not to explode quadratically in the case of a larger body (#1329)
|
||||
|
||||
### Changed
|
||||
|
||||
- Send HTTP 400 response for invalid request (#1352)
|
||||
|
||||
## 0.17.4 (February 4, 2022)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Replace `create_server` by `create_unix_server` (#1362)
|
||||
|
||||
## 0.17.3 (February 3, 2022)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Drop wsproto version checking. (#1359)
|
||||
|
||||
## 0.17.2 (February 3, 2022)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Revert #1332. While trying to solve the memory leak, it introduced an issue (#1345) when the server receives big chunks of data using the `httptools` implementation. (#1354)
|
||||
- Revert stream interface changes. This was introduced on 0.14.0, and caused an issue (#1226), which caused a memory leak when sending TCP pings. (#1355)
|
||||
- Fix wsproto version check expression (#1342)
|
||||
|
||||
## 0.17.1 (January 28, 2022)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Move all data handling logic to protocol and ensure connection is closed. (#1332)
|
||||
- Change `spec_version` field from "2.1" to "2.3", as Uvicorn is compliant with that version of the ASGI specifications. (#1337)
|
||||
|
||||
## 0.17.0.post1 (January 24, 2022)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Add the `python_requires` version specifier (#1328)
|
||||
|
||||
## 0.17.0 (January 14, 2022)
|
||||
|
||||
### Added
|
||||
|
||||
- Allow configurable websocket per-message-deflate setting (#1300)
|
||||
- Support extra_headers for WS accept message (#1293)
|
||||
- Add missing http version on websockets scope (#1309)
|
||||
|
||||
### Fixed/Removed
|
||||
|
||||
- Drop Python 3.6 support (#1261)
|
||||
- Fix reload process behavior when exception is raised (#1313)
|
||||
- Remove `root_path` from logs (#1294)
|
||||
|
||||
## 0.16.0 (December 8, 2021)
|
||||
|
||||
### Added
|
||||
|
||||
- Enable read of uvicorn settings from environment variables (#1279)
|
||||
- Bump `websockets` to 10.0. (#1180)
|
||||
- Ensure non-zero exit code when startup fails (#1278)
|
||||
- Increase `httptools` version range from "==0.2.*" to ">=0.2.0,<0.4.0". (#1243)
|
||||
- Override default asyncio event loop with reload only on Windows (#1257)
|
||||
- Replace `HttpToolsProtocol.pipeline` type from `list` to `deque`. (#1213)
|
||||
- Replace `WSGIResponder.send_queue` type from `list` to `deque`. (#1214)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Main process exit after startup failure on reloader classes (#1177)
|
||||
- Fix the need of `httptools` on minimal installation (#1135)
|
||||
- Fix ping parameters annotation in Config class (#1127)
|
||||
|
||||
## 0.15.0 (August 13, 2021)
|
||||
|
||||
### Added
|
||||
|
||||
- Change reload to be configurable with glob patterns. Currently only `.py` files are watched, which is different from the previous default behavior. (#820)
|
||||
- Add Python 3.10-rc.1 support. Now the server uses `asyncio.run` which will: start a fresh asyncio event loop, on shutdown cancel any background tasks rather than aborting them, `aexit` any remaining async generators, and shutdown the default `ThreadPoolExecutor`. (#1070)
|
||||
- Exit with status 3 when worker starts failed (#1077)
|
||||
- Add option to set websocket ping interval and timeout (#1048)
|
||||
- Adapt bind_socket to make it usable with multiple processes (#1009)
|
||||
- Add existence check to the reload directory(ies) (#1089)
|
||||
- Add missing trace log for websocket protocols (#1083)
|
||||
- Support disabling default Server and Date headers (#818)
|
||||
|
||||
### Changed
|
||||
|
||||
- Add PEP440 compliant version of click (#1099)
|
||||
- Bump asgiref to 3.4.0 (#1100)
|
||||
|
||||
### Fixed
|
||||
|
||||
- When receiving a `SIGTERM` supervisors now terminate their processes before joining them (#1069)
|
||||
- Fix `httptools` range to `>=0.4.0` (#1400)
|
||||
|
||||
## 0.14.0 (June 1, 2021)
|
||||
|
||||
### Added
|
||||
|
||||
- Defaults ws max_size on server to 16MB (#995)
|
||||
- Improve user feedback if no ws library installed (#926 and #1023)
|
||||
- Support 'reason' field in 'websocket.close' messages (#957)
|
||||
- Implemented lifespan.shutdown.failed (#755)
|
||||
|
||||
### Changed
|
||||
|
||||
- Upgraded websockets requirements (#1065)
|
||||
- Switch to asyncio streams API (#869)
|
||||
- Update httptools from 0.1.* to 0.2.* (#1024)
|
||||
- Allow Click 8.0, refs #1016 (#1042)
|
||||
- Add search for a trusted host in ProxyHeadersMiddleware (#591)
|
||||
- Up wsproto to 1.0.0 (#892)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Force reload_dirs to be a list (#978)
|
||||
- Fix gunicorn worker not running if extras not installed (#901)
|
||||
- Fix socket port 0 (#975)
|
||||
- Prevent garbage collection of main lifespan task (#972)
|
||||
|
||||
## 0.13.4 (February 20, 2021)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Fixed wsgi middleware PATH_INFO encoding (#962)
|
||||
- Fixed uvloop dependency (#952) then (#959)
|
||||
- Relax watchgod up bound (#946)
|
||||
- Return 'connection: close' header in response (#721)
|
||||
|
||||
### Added
|
||||
|
||||
- Docs: Nginx + websockets (#948)
|
||||
- Document the default value of 1 for workers (#940) (#943)
|
||||
- Enabled permessage-deflate extension in websockets (#764)
|
||||
|
||||
## 0.13.3 (December 29, 2020)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Prevent swallowing of return codes from `subprocess` when running with Gunicorn by properly resetting signals. (#895)
|
||||
- Tweak detection of app factories to be more robust. A warning is now logged when passing a factory without the `--factory` flag. (#914)
|
||||
- Properly clean tasks when handshake is aborted when running with `--ws websockets`. (#921)
|
||||
|
||||
## 0.13.2 (December 12, 2020)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Log full exception traceback in case of invalid HTTP request. (#886 and #888)
|
||||
|
||||
## 0.13.1 (December 12, 2020)
|
||||
|
||||
### Fixed
|
||||
|
||||
- Prevent exceptions when the ASGI application rejects a connection during the WebSocket handshake, when running on both `--ws wsproto` or `--ws websockets`. (#704 and #881)
|
||||
- Ensure connection `scope` doesn't leak in logs when using JSON log formatters. (#859 and #884)
|
||||
|
||||
## 0.13.0 (December 8, 2020)
|
||||
|
||||
### Added
|
||||
|
||||
- Add `--factory` flag to support factory-style application imports. (#875)
|
||||
- Skip installation of signal handlers when not in the main thread. Allows using `Server` in multithreaded contexts without having to override `.install_signal_handlers()`. (#871)
|
||||
|
||||
## 0.12.3 (November 21, 2020)
|
||||
|
||||
### Fixed
|
||||
- Fix race condition that leads Quart to hang with uvicorn (#848)
|
||||
- Use latin1 when decoding X-Forwarded-* headers (#701)
|
||||
- Rework IPv6 support (#837)
|
||||
- Cancel old keepalive-trigger before setting new one. (#832)
|
||||
|
||||
## 0.12.2 (October 19, 2020)
|
||||
|
||||
### Added
|
||||
- Adding ability to decrypt ssl key file (#808)
|
||||
- Support .yml log config files (#799)
|
||||
- Added python 3.9 support (#804)
|
||||
|
||||
### Fixed
|
||||
- Fixes watchgod with common prefixes (#817)
|
||||
- Fix reload with ipv6 host (#803)
|
||||
- Added cli support for headers containing colon (#813)
|
||||
- Sharing socket across workers on windows (#802)
|
||||
- Note the need to configure trusted "ips" when using unix sockets (#796)
|
||||
|
||||
## 0.12.1 (September 30, 2020)
|
||||
|
||||
### Changed
|
||||
- Pinning h11 and python-dotenv to min versions (#789)
|
||||
- Get docs/index.md in sync with README.md (#784)
|
||||
|
||||
### Fixed
|
||||
- Improve changelog by pointing out breaking changes (#792)
|
||||
|
||||
## 0.12.0 (September 28, 2020)
|
||||
|
||||
### Added
|
||||
- Make reload delay configurable (#774)
|
||||
- Upgrade maximum h11 dependency version to 0.10 (#772)
|
||||
- Allow .json or .yaml --log-config files (#665)
|
||||
- Add ASGI dict to the lifespan scope (#754)
|
||||
- Upgrade wsproto to 0.15.0 (#750)
|
||||
- Use optional package installs (#666)
|
||||
|
||||
### Changed
|
||||
- Don't set log level for root logger (#767) 8/28/20 df81b168
|
||||
- Uvicorn no longer ships extra dependencies `uvloop`, `websockets` and `httptools` as default.
|
||||
To install these dependencies use `uvicorn[standard]`.
|
||||
|
||||
### Fixed
|
||||
- Revert "Improve shutdown robustness when using `--reload` or multiprocessing (#620)" (#756)
|
||||
- Fix terminate error in windows (#744)
|
||||
- Fix bug where --log-config disables uvicorn loggers (#512)
|
||||
|
||||
## 0.11.8 (July 30, 2020)
|
||||
|
||||
* Fix a regression that caused Uvicorn to crash when using `--interface=wsgi`. (#730)
|
||||
* Fix a regression that caused Uvicorn to crash when using unix domain sockets. (#729)
|
||||
|
||||
## 0.11.7 (July 28, 2020)
|
||||
|
||||
* SECURITY FIX: Prevent sending invalid HTTP header names and values. (#725)
|
||||
* SECURITY FIX: Ensure path value is escaped before logging to the console. (#724)
|
||||
* Fix `--proxy-headers` client IP and host when using a Unix socket. (#636)
|
||||
|
||||
## 0.11.6 (July 17, 2020)
|
||||
|
||||
* Fix overriding the root logger.
|
||||
|
||||
## 0.11.5 (April 29, 2020)
|
||||
|
||||
* Revert "Watch all files, not just .py" due to unexpected side effects.
|
||||
* Revert "Pass through gunicorn timeout config." due to unexpected side effects.
|
||||
|
||||
## 0.11.4 (April 28, 2020)
|
||||
|
||||
* Use `watchgod`, if installed, for watching code changes.
|
||||
* Watch all files, not just .py.
|
||||
* Pass through gunicorn timeout config.
|
||||
|
||||
## 0.11.3 (February 17, 2020)
|
||||
|
||||
* Update dependencies.
|
||||
|
||||
## 0.11.2 (January 20, 2020)
|
||||
|
||||
* Don't open socket until after application startup.
|
||||
* Support `--backlog`.
|
||||
|
||||
## 0.11.1 (December 20, 2019)
|
||||
|
||||
* Use a more liberal `h11` dependency. Either `0.8.*` or `0.9.*``.
|
||||
|
||||
## 0.11.0 (December 20, 2019)
|
||||
|
||||
* Fix reload/multiprocessing on Windows with Python 3.8.
|
||||
* Drop IOCP support. (Required for fix above.)
|
||||
* Add `uvicorn --version` flag.
|
||||
* Add `--use-colors` and `--no-use-colors` flags.
|
||||
* Display port correctly, when auto port selection isused with `--port=0`.
|
||||
|
||||
## 0.10.8 (November 12, 2019)
|
||||
|
||||
* Fix reload/multiprocessing error.
|
||||
|
||||
## 0.10.7 (November 12, 2019)
|
||||
|
||||
* Use resource_sharer.DupSocket to resolve socket sharing on Windows.
|
||||
|
||||
## 0.10.6 (November 12, 2019)
|
||||
|
||||
* Exit if `workers` or `reload` are use without an app import string style.
|
||||
* Reorganise supervisor processes to properly hand over sockets on windows.
|
||||
|
||||
## 0.10.5 (November 12, 2019)
|
||||
|
||||
* Update uvloop dependency to 0.14+
|
||||
|
||||
## 0.10.4 (November 9, 2019)
|
||||
|
||||
* Error clearly when `workers=<NUM>` is used with app instance, instead of an app import string.
|
||||
* Switch `--reload-dir` to current working directory by default.
|
||||
|
||||
## 0.10.3 (November 1, 2019)
|
||||
|
||||
* Add ``--log-level trace`
|
||||
|
||||
## 0.10.2 (October 31, 2019)
|
||||
|
||||
* Enable --proxy-headers by default.
|
||||
|
||||
## 0.10.1 (October 31, 2019)
|
||||
|
||||
* Resolve issues with logging when using `--reload` or `--workers`.
|
||||
* Setup up root logger to capture output for all logger instances, not just `uvicorn.error` and `uvicorn.access`.
|
||||
|
||||
## 0.10.0 (October 29, 2019)
|
||||
|
||||
* Support for Python 3.8
|
||||
* Separated out `uvicorn.error` and `uvicorn.access` logs.
|
||||
* Coloured log output when connected to a terminal.
|
||||
* Dropped `logger=` config setting.
|
||||
* Added `--log-config [FILE]` and `log_config=[str|dict]`. May either be a Python logging config dictionary or the file name of a logging configuration.
|
||||
* Added `--forwarded_allow_ips` and `forwarded_allow_ips`. Defaults to the value of the `$FORWARDED_ALLOW_IPS` environment variable or "127.0.0.1". The `--proxy-headers` flag now defaults to `True`, but only trusted IPs are used to populate forwarding info.
|
||||
* The `--workers` setting now defaults to the value of the `$WEB_CONCURRENCY` environment variable.
|
||||
* Added support for `--env-file`. Requires `python-dotenv`.
|
||||
@ -20,7 +20,7 @@ HTTP headers are mandated to be case-insensitive. Uvicorn will always send respo
|
||||
|
||||
## Flow Control
|
||||
|
||||
Proper flow control ensures that large amounts of data do not become buffered on the transport when either side of a connection is sending data faster than its counterpart is able to handle.
|
||||
Proper flow control ensures that large amounts of data does not become buffered on the transport when either side of a connection is sending data faster than its counterpart is able to handle.
|
||||
|
||||
### Write flow control
|
||||
|
||||
@ -46,7 +46,7 @@ The `Expect: 100-Continue` header may be sent by clients to require a confirmati
|
||||
|
||||
Uvicorn ensures that any required `100 Continue` confirmations are only sent if the ASGI application calls `receive` to read the request body.
|
||||
|
||||
Note that proxy configurations may not necessarily forward on `Expect: 100-Continue` headers. In particular, Nginx defaults to buffering request bodies, and automatically sends `100 Continues` rather than passing the header on to the upstream server.
|
||||
Note that that proxy configurations may not necessarily forward on `Expect: 100-Continue` headers. In particular Nginx defaults to buffering request bodies, and automatically sends `100 Continues` rather than passing the header on to the upstream server.
|
||||
|
||||
### HEAD requests
|
||||
|
||||
@ -83,9 +83,6 @@ Server errors will be logged at the `error` log level. All logging defaults to b
|
||||
|
||||
If an exception is raised by an ASGI application, and a response has not yet been sent on the connection, then a `500 Server Error` HTTP response will be sent.
|
||||
|
||||
Uvicorn sends the headers and the status code as soon as it receives from the ASGI application. This means that if the application sends a [Response Start](https://asgi.readthedocs.io/en/latest/specs/www.html#response-start-send-event)
|
||||
message with a status code of `200 OK`, and then an exception is raised, the response will still be sent with a status code of `200 OK`.
|
||||
|
||||
### Invalid responses
|
||||
|
||||
Uvicorn will ensure that ASGI applications send the correct sequence of messages, and will raise errors otherwise. This includes checking for no response sent, partial response sent, or invalid message sequences being sent.
|
||||
|
||||
129
docs/settings.md
129
docs/settings.md
@ -2,84 +2,35 @@
|
||||
|
||||
Use the following options to configure Uvicorn, when running from the command line.
|
||||
|
||||
## Configuration Methods
|
||||
|
||||
There are three ways to configure Uvicorn:
|
||||
|
||||
1. **Command Line**: Use command line options when running Uvicorn directly.
|
||||
```bash
|
||||
uvicorn main:app --host 0.0.0.0 --port 8000
|
||||
```
|
||||
|
||||
2. **Programmatic**: Use keyword arguments when running programmatically with `uvicorn.run()`.
|
||||
```python
|
||||
uvicorn.run("main:app", host="0.0.0.0", port=8000)
|
||||
```
|
||||
|
||||
!!! note
|
||||
When using `reload=True` or `workers=NUM`, you should put `uvicorn.run` into
|
||||
an `if __name__ == '__main__'` clause in the main module.
|
||||
|
||||
3. **Environment Variables**: Use environment variables with the prefix `UVICORN_`.
|
||||
```bash
|
||||
export UVICORN_HOST="0.0.0.0"
|
||||
export UVICORN_PORT="8000"
|
||||
uvicorn main:app
|
||||
```
|
||||
|
||||
CLI options and the arguments for `uvicorn.run()` take precedence over environment variables.
|
||||
|
||||
Also note that `UVICORN_*` prefixed settings cannot be used from within an environment
|
||||
configuration file. Using an environment configuration file with the `--env-file` flag is
|
||||
intended for configuring the ASGI application that uvicorn runs, rather than configuring
|
||||
uvicorn itself.
|
||||
If you're running using programmatically, using `uvicorn.run(...)`, then use
|
||||
equivalent keyword arguments, eg. `uvicorn.run("example:app", port=5000, reload=True, access_log=False)`.
|
||||
|
||||
## Application
|
||||
|
||||
* `APP` - The ASGI application to run, in the format `"<module>:<attribute>"`.
|
||||
* `--factory` - Treat `APP` as an application factory, i.e. a `() -> <ASGI app>` callable.
|
||||
* `--app-dir <path>` - Look for APP in the specified directory by adding it to the PYTHONPATH. **Default:** *Current working directory*.
|
||||
* `--reset-contextvars` - Run each ASGI request in a fresh `contextvars.Context`. Workaround for a [context leak in asyncio](https://github.com/python/cpython/issues/140947); only relevant when using the `asyncio` event loop (uvloop is not affected). Enabling this hides any context set in the lifespan or by external instrumentation from ASGI handlers. **Default:** *False*.
|
||||
|
||||
## Socket Binding
|
||||
|
||||
* `--host <str>` - Bind socket to this host. Use `--host 0.0.0.0` to make the application available on your local network. IPv6 addresses are supported, for example: `--host '::'`. **Default:** *'127.0.0.1'*.
|
||||
* `--port <int>` - Bind to a socket with this port. If set to 0, an available port will be picked. **Default:** *8000*.
|
||||
* `--uds <path>` - Bind to a UNIX domain socket, for example `--uds /tmp/uvicorn.sock`. Useful if you want to run Uvicorn behind a reverse proxy.
|
||||
* `--port <int>` - Bind to a socket with this port. **Default:** *8000*.
|
||||
* `--uds <str>` - Bind to a UNIX domain socket. Useful if you want to run Uvicorn behind a reverse proxy.
|
||||
* `--fd <int>` - Bind to socket from this file descriptor. Useful if you want to run Uvicorn within a process manager.
|
||||
|
||||
## Development
|
||||
|
||||
* `--reload` - Enable auto-reload. Uvicorn supports two versions of auto-reloading behavior enabled by this option. **Default:** *False*.
|
||||
* `--reload-dir <path>` - Specify which directories to watch for python file changes. May be used multiple times. If unused, then by default the whole current directory will be watched. If you are running programmatically use `reload_dirs=[]` and pass a list of strings.
|
||||
* `--reload-delay <float>` - Delay between previous and next check if application needs to be reloaded. **Default:** *0.25*.
|
||||
* `--reload` - Enable auto-reload.
|
||||
* `--reload-dir <path>` - Specify which directories to watch for python file changes. May be used multiple times. If unused, then by default all directories in current directory will be watched.
|
||||
|
||||
### Reloading without watchfiles
|
||||
By default Uvicorn uses simple changes detection strategy that compares python files modification times few times a second. If this approach doesn't work for your project (eg. because of its complexity), you can install Uvicorn with optional `watchgod` dependency to use filesystem events instead:
|
||||
|
||||
If Uvicorn _cannot_ load [watchfiles](https://pypi.org/project/watchfiles/) at runtime, it will periodically look for changes in modification times to all `*.py` files (and only `*.py` files) inside of its monitored directories. See the `--reload-dir` option. Specifying other file extensions is not supported unless watchfiles is installed. See the `--reload-include` and `--reload-exclude` options for details.
|
||||
|
||||
### Reloading with watchfiles
|
||||
|
||||
For more nuanced control over which file modifications trigger reloads, install `uvicorn[standard]`, which includes watchfiles as a dependency. Alternatively, install [watchfiles](https://pypi.org/project/watchfiles/) where Uvicorn can see it.
|
||||
|
||||
Using Uvicorn with watchfiles will enable the following options (which are otherwise ignored):
|
||||
|
||||
* `--reload-include <glob-pattern>` - Specify a glob pattern to match files or directories which will be watched. May be used multiple times. By default the following patterns are included: `*.py`. These defaults can be overwritten by including them in `--reload-exclude`.
|
||||
* `--reload-exclude <glob-pattern>` - Specify a glob pattern to match files or directories which will excluded from watching. May be used multiple times. By default the following patterns are excluded: `.*, .py[cod], .sw.*, ~*`. These defaults can be overwritten by including them in `--reload-include`.
|
||||
|
||||
!!! tip
|
||||
When using Uvicorn through [WSL](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux), you might
|
||||
have to set the `WATCHFILES_FORCE_POLLING` environment variable, for file changes to trigger a reload.
|
||||
See [watchfiles documentation](https://watchfiles.helpmanual.io/api/watch/) for further details.
|
||||
```
|
||||
$ pip install uvicorn[watchgodreload]
|
||||
```
|
||||
|
||||
## Production
|
||||
|
||||
* `--workers <int>` - Number of worker processes. Defaults to the `$WEB_CONCURRENCY` environment variable if available, or 1. Not valid with `--reload`.
|
||||
* `--env-file <path>` - Environment configuration file for the ASGI application. **Default:** *None*.
|
||||
* `--timeout-worker-healthcheck <int>` - Maximum number of seconds to wait for a worker to respond to a healthcheck. **Default:** *5*.
|
||||
|
||||
!!! note
|
||||
The `--reload` and `--workers` arguments are mutually exclusive. You cannot use both at the same time.
|
||||
* `--workers <int>` - Use multiple worker processes. Defaults to the value of the `$WEB_CONCURRENCY` environment variable.
|
||||
|
||||
## Logging
|
||||
|
||||
@ -87,67 +38,45 @@ Using Uvicorn with watchfiles will enable the following options (which are other
|
||||
* If you wish to use a YAML file for your logging config, you will need to include PyYAML as a dependency for your project or install uvicorn with the `[standard]` optional extras.
|
||||
* `--log-level <str>` - Set the log level. **Options:** *'critical', 'error', 'warning', 'info', 'debug', 'trace'.* **Default:** *'info'*.
|
||||
* `--no-access-log` - Disable access log only, without changing log level.
|
||||
* `--use-colors / --no-use-colors` - Enable / disable colorized formatting of the log records. If not set, colors will be auto-detected. This option is ignored if the `--log-config` CLI option is used.
|
||||
* `--use-colors / --no-use-colors` - Enable / disable colorized formatting of the log records, in case this is not set it will be auto-detected. This option is ignored if the `--log-config` CLI option is used.
|
||||
|
||||
|
||||
## Implementation
|
||||
|
||||
* `--loop <str>` - Set the event loop implementation. The uvloop implementation provides greater performance, but is not compatible with Windows or PyPy. **Options:** *'auto', 'asyncio', 'uvloop'.* **Default:** *'auto'*.
|
||||
* `--http <str>` - Set the HTTP protocol implementation. The httptools implementation provides greater performance, but it not compatible with PyPy. **Options:** *'auto', 'h11', 'httptools'.* **Default:** *'auto'*.
|
||||
* `--ws <str>` - Set the WebSockets protocol implementation. Either of the `websockets` and `wsproto` packages are supported. There are two versions of `websockets` supported: `websockets` and `websockets-sansio`. Use `'none'` to ignore all websocket requests. **Options:** *'auto', 'none', 'websockets', 'websockets-sansio', 'wsproto'.* **Default:** *'auto'*.
|
||||
* `--ws-max-size <int>` - Set the WebSockets max message size, in bytes. **Default:** *16777216* (16 MB).
|
||||
* `--ws-max-queue <int>` - Set the maximum length of the WebSocket incoming message queue. Only available with the `websockets` protocol. **Default:** *32*.
|
||||
* `--ws-ping-interval <float>` - Set the WebSockets ping interval, in seconds. **Default:** *20.0*.
|
||||
* `--ws-ping-timeout <float>` - Set the WebSockets ping timeout, in seconds. **Default:** *20.0*.
|
||||
* `--ws-per-message-deflate <bool>` - Enable/disable WebSocket per-message-deflate compression. Only available with the `websockets` protocol. **Default:** *True*.
|
||||
* `--http <str>` - Set the HTTP protocol implementation. The httptools implementation provides greater performance, but it not compatible with PyPy, and requires compilation on Windows. **Options:** *'auto', 'h11', 'httptools'.* **Default:** *'auto'*.
|
||||
* `--ws <str>` - Set the WebSockets protocol implementation. Either of the `websockets` and `wsproto` packages are supported. Use `'none'` to deny all websocket requests. **Options:** *'auto', 'none', 'websockets', 'wsproto'.* **Default:** *'auto'*.
|
||||
* `--lifespan <str>` - Set the Lifespan protocol implementation. **Options:** *'auto', 'on', 'off'.* **Default:** *'auto'*.
|
||||
* `--h11-max-incomplete-event-size <int>` - Set the maximum number of bytes to buffer of an incomplete event. Only available for `h11` HTTP protocol implementation. **Default:** *16384* (16 KB).
|
||||
|
||||
## Application Interface
|
||||
|
||||
* `--interface <str>` - Select ASGI3, ASGI2, or WSGI as the application interface.
|
||||
* `--interface` - Select ASGI3, ASGI2, or WSGI as the application interface.
|
||||
Note that WSGI mode always disables WebSocket support, as it is not supported by the WSGI interface.
|
||||
**Options:** *'auto', 'asgi3', 'asgi2', 'wsgi'.* **Default:** *'auto'*.
|
||||
|
||||
!!! warning
|
||||
Uvicorn's native WSGI implementation is deprecated, you should switch
|
||||
to [a2wsgi](https://github.com/abersheeran/a2wsgi) (`pip install a2wsgi`).
|
||||
|
||||
## HTTP
|
||||
|
||||
* `--root-path <str>` - Set the ASGI `root_path` for applications submounted below a given URL path. **Default:** *""*.
|
||||
* `--proxy-headers / --no-proxy-headers` - Enable/Disable X-Forwarded-Proto, X-Forwarded-For to populate remote address info. Defaults to enabled, but is restricted to only trusting connecting IPs in the `forwarded-allow-ips` configuration.
|
||||
* `--forwarded-allow-ips <comma-separated-list>` - Comma separated list of IP Addresses, IP Networks, or literals (e.g. UNIX Socket path) to trust with proxy headers. Defaults to the `$FORWARDED_ALLOW_IPS` environment variable if available, or '127.0.0.1'. The literal `'*'` means trust everything.
|
||||
* `--server-header / --no-server-header` - Enable/Disable default `Server` header. **Default:** *True*.
|
||||
* `--date-header / --no-date-header` - Enable/Disable default `Date` header. **Default:** *True*.
|
||||
* `--header <name:value>` - Specify custom default HTTP response headers as a Name:Value pair. May be used multiple times.
|
||||
|
||||
!!! note
|
||||
The `--no-date-header` flag doesn't have effect on the `websockets` implementation.
|
||||
* `--root-path <str>` - Set the ASGI `root_path` for applications submounted below a given URL path.
|
||||
* `--proxy-headers` / `--no-proxy-headers` - Enable/Disable X-Forwarded-Proto, X-Forwarded-For, X-Forwarded-Port to populate remote address info. Defaults to enabled, but is restricted to only trusting
|
||||
connecting IPs in the `forwarded-allow-ips` configuration.
|
||||
* `--forwarded-allow-ips` <comma-separated-list> Comma separated list of IPs to trust with proxy headers. Defaults to the `$FORWARDED_ALLOW_IPS` environment variable if available, or '127.0.0.1'. A wildcard '*' means always trust.
|
||||
|
||||
## HTTPS
|
||||
|
||||
The [SSL context](https://docs.python.org/3/library/ssl.html#ssl.SSLContext) can be configured with the following options:
|
||||
|
||||
* `--ssl-keyfile <path>` - The SSL key file.
|
||||
* `--ssl-keyfile-password <str>` - The password to decrypt the ssl key.
|
||||
* `--ssl-certfile <path>` - The SSL certificate file.
|
||||
* `--ssl-version <int>` - The SSL version to use. **Default:** *ssl.PROTOCOL_TLS_SERVER*.
|
||||
* `--ssl-cert-reqs <int>` - Whether client certificate is required. **Default:** *ssl.CERT_NONE*.
|
||||
* `--ssl-ca-certs <str>` - The CA certificates file.
|
||||
* `--ssl-ciphers <str>` - The ciphers to use. **Default:** *"TLSv1"*.
|
||||
|
||||
To understand more about the SSL context options, please refer to the [Python documentation](https://docs.python.org/3/library/ssl.html).
|
||||
|
||||
For advanced TLS scenarios that the flags above don't cover (e.g., mutual TLS, certificate pinning, custom `SSLContext.options`), pass an `ssl_context_factory` to `uvicorn.run()` or `Config`. See [Running with HTTPS](deployment/index.md#customizing-the-ssl-context) for details.
|
||||
* `--ssl-keyfile <path>` - SSL key file
|
||||
* `--ssl-keyfile-password <str>` - Password to decrypt the ssl key
|
||||
* `--ssl-certfile <path>` - SSL certificate file
|
||||
* `--ssl-version <int>` - SSL version to use (see stdlib ssl module's)
|
||||
* `--ssl-cert-reqs <int>` - Whether client certificate is required (see stdlib ssl module's)
|
||||
* `--ssl-ca-certs <str>` - CA certificates file
|
||||
* `--ssl-ciphers <str>` - Ciphers to use (see stdlib ssl module's)
|
||||
|
||||
## Resource Limits
|
||||
|
||||
* `--limit-concurrency <int>` - Maximum number of concurrent connections or tasks to allow, before issuing HTTP 503 responses. Useful for ensuring known memory usage patterns even under over-resourced loads.
|
||||
* `--limit-max-requests <int>` - Maximum number of requests to service before terminating the process. Useful when running together with a process manager, for preventing memory leaks from impacting long-running processes.
|
||||
* `--limit-max-requests-jitter <int>` - Maximum jitter to add to `limit-max-requests`. Each worker adds a random number in the range `[0, jitter]`, staggering restarts to avoid all workers restarting simultaneously. **Default:** *0*.
|
||||
* `--backlog <int>` - Maximum number of connections to hold in backlog. Relevant for heavy incoming traffic. **Default:** *2048*.
|
||||
* `--backlog <int>` - Maximum number of connections to hold in backlog. Relevant for heavy incoming traffic. **Default:** *2048*
|
||||
|
||||
## Timeouts
|
||||
|
||||
* `--timeout-keep-alive <int>` - Close Keep-Alive connections if no new data is received within this timeout (in seconds). **Default:** *5*.
|
||||
* `--timeout-graceful-shutdown <int>` - Maximum number of seconds to wait for graceful shutdown. After this timeout, the server will start terminating requests.
|
||||
* `--timeout-keep-alive <int>` - Close Keep-Alive connections if no new data is received within this timeout. **Default:** *5*.
|
||||
|
||||
133
mkdocs.yml
133
mkdocs.yml
@ -1,132 +1,25 @@
|
||||
site_name: Uvicorn
|
||||
site_description: The lightning-fast ASGI server.
|
||||
site_url: https://uvicorn.dev
|
||||
|
||||
repo_name: Kludex/uvicorn
|
||||
repo_url: https://github.com/Kludex/uvicorn
|
||||
edit_uri: edit/main/docs/
|
||||
|
||||
strict: true
|
||||
|
||||
theme:
|
||||
name: material
|
||||
custom_dir: docs/overrides
|
||||
logo: uvicorn.png
|
||||
favicon: uvicorn.png
|
||||
palette:
|
||||
- scheme: "default"
|
||||
media: "(prefers-color-scheme: light)"
|
||||
toggle:
|
||||
icon: "material/lightbulb"
|
||||
name: "Switch to dark mode"
|
||||
- scheme: "slate"
|
||||
media: "(prefers-color-scheme: dark)"
|
||||
primary: "blue"
|
||||
toggle:
|
||||
icon: "material/lightbulb-outline"
|
||||
name: "Switch to light mode"
|
||||
icon:
|
||||
repo: fontawesome/brands/github
|
||||
features:
|
||||
- content.code.annotate
|
||||
- content.code.copy # https://squidfunk.github.io/mkdocs-material/upgrade/?h=content+copy#contentcodecopy
|
||||
- content.tabs.link
|
||||
- navigation.footer # https://squidfunk.github.io/mkdocs-material/upgrade/?h=content+copy#navigationfooter
|
||||
- navigation.path
|
||||
- navigation.sections # https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation
|
||||
- navigation.top # https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#back-to-top-button
|
||||
- navigation.tracking
|
||||
- search.suggest
|
||||
- search.highlight
|
||||
- toc.follow # https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#anchor-following
|
||||
name: 'material'
|
||||
|
||||
# https://www.mkdocs.org/user-guide/configuration/#validation
|
||||
validation:
|
||||
omitted_files: warn
|
||||
absolute_links: warn
|
||||
unrecognized_links: warn
|
||||
repo_name: encode/uvicorn
|
||||
repo_url: https://github.com/encode/uvicorn
|
||||
edit_uri: ""
|
||||
|
||||
nav:
|
||||
- Welcome: index.md
|
||||
- Installation: installation.md
|
||||
- Settings: settings.md
|
||||
- Server Behavior: server-behavior.md
|
||||
- Concepts:
|
||||
- ASGI: concepts/asgi.md
|
||||
- Lifespan: concepts/lifespan.md
|
||||
- Logging: concepts/logging.md
|
||||
- WebSockets: concepts/websockets.md
|
||||
- Event Loop: concepts/event-loop.md
|
||||
- Deployment:
|
||||
- Deployment: deployment/index.md
|
||||
- Docker: deployment/docker.md
|
||||
- Release Notes: release-notes.md
|
||||
- Contributing: contributing.md
|
||||
|
||||
extra:
|
||||
analytics:
|
||||
provider: google
|
||||
property: G-KTS6TXPD85
|
||||
social:
|
||||
- icon: fontawesome/brands/github-alt
|
||||
link: https://github.com/Kludex/uvicorn
|
||||
- icon: fontawesome/brands/discord
|
||||
link: https://discord.com/invite/RxKUF5JuHs
|
||||
- icon: fontawesome/brands/twitter
|
||||
link: https://x.com/marcelotryle
|
||||
- icon: fontawesome/brands/linkedin
|
||||
link: https://www.linkedin.com/in/marcelotryle
|
||||
- icon: fontawesome/solid/globe
|
||||
link: https://fastapiexpert.com
|
||||
|
||||
extra_css:
|
||||
- css/extra.css
|
||||
- Introduction: 'index.md'
|
||||
- Settings: 'settings.md'
|
||||
- Deployment: 'deployment.md'
|
||||
- Server Behavior: 'server-behavior.md'
|
||||
|
||||
markdown_extensions:
|
||||
- attr_list
|
||||
- admonition
|
||||
- codehilite:
|
||||
css_class: highlight
|
||||
- markdown.extensions.codehilite:
|
||||
guess_lang: false
|
||||
- toc:
|
||||
permalink: true
|
||||
- pymdownx.details
|
||||
- pymdownx.inlinehilite
|
||||
- pymdownx.snippets
|
||||
- pymdownx.superfences
|
||||
- pymdownx.tabbed:
|
||||
alternate_style: true
|
||||
- pymdownx.emoji:
|
||||
emoji_index: !!python/name:material.extensions.emoji.twemoji
|
||||
emoji_generator: !!python/name:material.extensions.emoji.to_svg
|
||||
- pymdownx.tasklist:
|
||||
custom_checkbox: true
|
||||
- pymdownx.extra:
|
||||
pymdownx.superfences:
|
||||
custom_fences:
|
||||
- name: mermaid
|
||||
class: mermaid
|
||||
format: !!python/name:pymdownx.superfences.fence_code_format
|
||||
|
||||
plugins:
|
||||
- search
|
||||
- mkdocstrings:
|
||||
handlers:
|
||||
python:
|
||||
inventories:
|
||||
- https://docs.python.org/3/objects.inv
|
||||
- llmstxt:
|
||||
full_output: llms-full.txt
|
||||
markdown_description: |-
|
||||
Uvicorn is a lightning-fast ASGI server implementation, designed to run asynchronous web applications.
|
||||
It supports the ASGI specification, which allows for both HTTP/1.1 and WebSocket protocols.
|
||||
sections:
|
||||
Sections:
|
||||
- index.md
|
||||
- settings.md
|
||||
- deployment/*.md
|
||||
- server-behavior.md
|
||||
Concepts:
|
||||
- concepts/*.md
|
||||
|
||||
hooks:
|
||||
- docs/plugins/main.py
|
||||
extra_javascript:
|
||||
- 'js/chat.js'
|
||||
- 'js/sidecar-1.5.0.js'
|
||||
|
||||
175
pyproject.toml
175
pyproject.toml
@ -1,175 +0,0 @@
|
||||
[build-system]
|
||||
requires = ["hatchling"]
|
||||
build-backend = "hatchling.build"
|
||||
|
||||
[project]
|
||||
name = "uvicorn"
|
||||
dynamic = ["version"]
|
||||
description = "The lightning-fast ASGI server."
|
||||
readme = "README.md"
|
||||
license = "BSD-3-Clause"
|
||||
license-files = ["LICENSE.md"]
|
||||
requires-python = ">=3.10"
|
||||
authors = [
|
||||
{ name = "Tom Christie", email = "tom@tomchristie.com" },
|
||||
]
|
||||
maintainers = [
|
||||
{ name = "Marcelo Trylesinski", email = "marcelotryle@gmail.com" },
|
||||
]
|
||||
classifiers = [
|
||||
"Development Status :: 4 - Beta",
|
||||
"Environment :: Web Environment",
|
||||
"Intended Audience :: Developers",
|
||||
"Operating System :: OS Independent",
|
||||
"Programming Language :: Python :: 3",
|
||||
"Programming Language :: Python :: 3.10",
|
||||
"Programming Language :: Python :: 3.11",
|
||||
"Programming Language :: Python :: 3.12",
|
||||
"Programming Language :: Python :: 3.13",
|
||||
"Programming Language :: Python :: 3.14",
|
||||
"Programming Language :: Python :: Implementation :: CPython",
|
||||
"Programming Language :: Python :: Implementation :: PyPy",
|
||||
"Topic :: Internet :: WWW/HTTP",
|
||||
]
|
||||
dependencies = [
|
||||
"click>=7.0",
|
||||
"h11>=0.8",
|
||||
"typing_extensions>=4.0; python_version < '3.11'",
|
||||
]
|
||||
|
||||
[project.optional-dependencies]
|
||||
standard = [
|
||||
"colorama>=0.4; sys_platform == 'win32'",
|
||||
"httptools>=0.6.3",
|
||||
"python-dotenv>=0.13",
|
||||
"PyYAML>=5.1",
|
||||
"uvloop>=0.15.1; sys_platform != 'win32' and (sys_platform != 'cygwin' and platform_python_implementation != 'PyPy')",
|
||||
"watchfiles>=0.20",
|
||||
"websockets>=10.4",
|
||||
]
|
||||
|
||||
[dependency-groups]
|
||||
dev = [
|
||||
# We add uvicorn[standard] so `uv sync` considers the extras.
|
||||
"uvicorn[standard]",
|
||||
"ruff==0.15.1",
|
||||
"pytest==9.0.3",
|
||||
"pytest-mock==3.15.1",
|
||||
"pytest-xdist[psutil]==3.8.0",
|
||||
"pytest-codspeed>=4.1.1",
|
||||
"mypy==1.19.1",
|
||||
"types-click==7.1.8",
|
||||
"types-pyyaml==6.0.12.20250915",
|
||||
"trustme==1.2.1",
|
||||
"cryptography>=44.0.3",
|
||||
"coverage==7.13.4",
|
||||
"coverage-conditional-plugin==0.9.0",
|
||||
"coverage-enable-subprocess==1.0",
|
||||
"httpx==0.28.1",
|
||||
# check dist
|
||||
"twine==6.2.0",
|
||||
# Explicit optionals,
|
||||
"a2wsgi==1.10.10",
|
||||
"wsproto==1.3.2",
|
||||
"websockets==13.1",
|
||||
]
|
||||
docs = [
|
||||
"mkdocs==1.6.1",
|
||||
"mkdocs-material==9.7.1",
|
||||
"mkdocstrings-python==2.0.2",
|
||||
"mkdocs-llmstxt==0.5.0",
|
||||
]
|
||||
|
||||
[tool.uv]
|
||||
default-groups = ["dev", "docs"]
|
||||
required-version = ">=0.9.17"
|
||||
exclude-newer = "7 days"
|
||||
|
||||
[project.scripts]
|
||||
uvicorn = "uvicorn.main:main"
|
||||
|
||||
[project.urls]
|
||||
Changelog = "https://uvicorn.dev/release-notes"
|
||||
Funding = "https://github.com/sponsors/encode"
|
||||
Homepage = "https://uvicorn.dev/"
|
||||
Source = "https://github.com/Kludex/uvicorn"
|
||||
|
||||
[tool.hatch.version]
|
||||
path = "uvicorn/__init__.py"
|
||||
|
||||
[tool.hatch.build.targets.sdist]
|
||||
include = ["/uvicorn", "/tests"]
|
||||
|
||||
[tool.ruff]
|
||||
line-length = 120
|
||||
|
||||
[tool.ruff.lint]
|
||||
select = ["E", "F", "I", "FA", "UP"]
|
||||
ignore = ["B904", "B028", "UP031"]
|
||||
|
||||
[tool.ruff.lint.isort]
|
||||
combine-as-imports = true
|
||||
|
||||
[tool.mypy]
|
||||
warn_unused_ignores = true
|
||||
warn_redundant_casts = true
|
||||
show_error_codes = true
|
||||
disallow_untyped_defs = false
|
||||
ignore_missing_imports = true
|
||||
follow_imports = "silent"
|
||||
|
||||
[tool.pytest.ini_options]
|
||||
addopts = "-rxXs --strict-config --strict-markers -n 8"
|
||||
xfail_strict = true
|
||||
filterwarnings = [
|
||||
"error",
|
||||
"ignore:Uvicorn's native WSGI implementation is deprecated.*:DeprecationWarning",
|
||||
"ignore: 'cgi' is deprecated and slated for removal in Python 3.13:DeprecationWarning",
|
||||
"ignore: remove second argument of ws_handler:DeprecationWarning:websockets",
|
||||
"ignore: websockets.legacy is deprecated.*:DeprecationWarning",
|
||||
"ignore: websockets.server.WebSocketServerProtocol is deprecated.*:DeprecationWarning",
|
||||
"ignore: websockets.client.connect is deprecated.*:DeprecationWarning",
|
||||
# httptools in Python 3.14t needs the `PYTHON_GIL=0` environment variable, or raises a RuntimeWarning.
|
||||
"ignore: The global interpreter lock (GIL)*:RuntimeWarning"
|
||||
]
|
||||
|
||||
[tool.coverage.run]
|
||||
parallel = true
|
||||
source_pkgs = ["uvicorn", "tests"]
|
||||
plugins = ["coverage_conditional_plugin"]
|
||||
omit = ["uvicorn/workers.py", "uvicorn/__main__.py", "uvicorn/_compat.py", "tests/benchmarks/*"]
|
||||
|
||||
[tool.coverage.report]
|
||||
precision = 2
|
||||
fail_under = 100
|
||||
show_missing = true
|
||||
skip_covered = true
|
||||
exclude_lines = [
|
||||
"pragma: no cover",
|
||||
"pragma: nocover",
|
||||
"pragma: full coverage",
|
||||
"if TYPE_CHECKING:",
|
||||
"if typing.TYPE_CHECKING:",
|
||||
"raise NotImplementedError",
|
||||
]
|
||||
|
||||
[tool.coverage.coverage_conditional_plugin.omit]
|
||||
"sys_platform == 'win32'" = [
|
||||
"uvicorn/loops/uvloop.py",
|
||||
"uvicorn/supervisors/multiprocess.py",
|
||||
"tests/supervisors/test_multiprocess.py",
|
||||
]
|
||||
"sys_platform != 'win32'" = ["uvicorn/loops/asyncio.py"]
|
||||
|
||||
[tool.coverage.coverage_conditional_plugin.rules]
|
||||
py-win32 = "sys_platform == 'win32'"
|
||||
py-not-win32 = "sys_platform != 'win32'"
|
||||
py-linux = "sys_platform == 'linux'"
|
||||
py-not-linux = "sys_platform != 'linux'"
|
||||
py-darwin = "sys_platform == 'darwin'"
|
||||
py-gte-39 = "sys_version_info >= (3, 9)"
|
||||
py-lt-39 = "sys_version_info < (3, 9)"
|
||||
py-gte-310 = "sys_version_info >= (3, 10)"
|
||||
py-lt-310 = "sys_version_info < (3, 10)"
|
||||
py-gte-311 = "sys_version_info >= (3, 11)"
|
||||
py-lt-311 = "sys_version_info < (3, 11)"
|
||||
26
requirements.txt
Normal file
26
requirements.txt
Normal file
@ -0,0 +1,26 @@
|
||||
-e .[standard]
|
||||
|
||||
# Explicit optionals
|
||||
wsproto==0.15.*
|
||||
|
||||
# Packaging
|
||||
twine
|
||||
wheel
|
||||
|
||||
# Testing
|
||||
autoflake
|
||||
black
|
||||
flake8
|
||||
isort
|
||||
pytest
|
||||
pytest-mock
|
||||
requests
|
||||
mypy
|
||||
trustme
|
||||
cryptography
|
||||
coverage
|
||||
|
||||
# Documentation
|
||||
mkdocs
|
||||
mkdocs-material
|
||||
|
||||
@ -1,7 +1,13 @@
|
||||
#!/bin/sh -e
|
||||
|
||||
if [ -d 'venv' ] ; then
|
||||
PREFIX="venv/bin/"
|
||||
else
|
||||
PREFIX=""
|
||||
fi
|
||||
|
||||
set -x
|
||||
|
||||
uv build
|
||||
uv run twine check dist/*
|
||||
uv run mkdocs build
|
||||
${PREFIX}python setup.py sdist bdist_wheel
|
||||
${PREFIX}twine check dist/*
|
||||
${PREFIX}mkdocs build
|
||||
|
||||
@ -1,10 +1,15 @@
|
||||
#!/bin/sh -e
|
||||
|
||||
export PREFIX=""
|
||||
if [ -d 'venv' ] ; then
|
||||
export PREFIX="venv/bin/"
|
||||
fi
|
||||
export SOURCE_FILES="uvicorn tests"
|
||||
|
||||
set -x
|
||||
|
||||
./scripts/sync-version
|
||||
uv run ruff format --check --diff $SOURCE_FILES
|
||||
uv run mypy $SOURCE_FILES
|
||||
uv run ruff check $SOURCE_FILES
|
||||
${PREFIX}black --check --diff --target-version=py36 $SOURCE_FILES
|
||||
${PREFIX}flake8 $SOURCE_FILES
|
||||
${PREFIX}mypy
|
||||
${PREFIX}isort --check --diff --project=uvicorn $SOURCE_FILES
|
||||
${PREFIX}python -m tools.cli_usage --check
|
||||
|
||||
@ -1,8 +1,11 @@
|
||||
#!/bin/sh -e
|
||||
|
||||
export PREFIX=""
|
||||
if [ -d 'venv' ] ; then
|
||||
export PREFIX="venv/bin/"
|
||||
fi
|
||||
export SOURCE_FILES="uvicorn tests"
|
||||
|
||||
set -x
|
||||
|
||||
uv run coverage combine
|
||||
uv run coverage report
|
||||
${PREFIX}coverage report --show-missing --skip-covered --fail-under=80
|
||||
@ -1,5 +0,0 @@
|
||||
#!/bin/sh -e
|
||||
|
||||
set -x
|
||||
|
||||
uv run mkdocs "$@"
|
||||
@ -1,5 +1,18 @@
|
||||
#!/bin/sh -e
|
||||
|
||||
# Use the Python executable provided from the `-p` option, or a default.
|
||||
[ "$1" = "-p" ] && PYTHON=$2 || PYTHON="python3"
|
||||
|
||||
REQUIREMENTS="requirements.txt"
|
||||
VENV="venv"
|
||||
|
||||
set -x
|
||||
|
||||
uv sync --frozen
|
||||
if [ -z "$GITHUB_ACTIONS" ]; then
|
||||
"$PYTHON" -m venv "$VENV"
|
||||
PIP="$VENV/bin/pip"
|
||||
else
|
||||
PIP="pip"
|
||||
fi
|
||||
|
||||
"$PIP" install -r "$REQUIREMENTS"
|
||||
|
||||
10
scripts/lint
10
scripts/lint
@ -1,8 +1,14 @@
|
||||
#!/bin/sh -e
|
||||
|
||||
export PREFIX=""
|
||||
if [ -d 'venv' ] ; then
|
||||
export PREFIX="venv/bin/"
|
||||
fi
|
||||
export SOURCE_FILES="uvicorn tests"
|
||||
|
||||
set -x
|
||||
|
||||
uv run ruff format $SOURCE_FILES
|
||||
uv run ruff check --fix $SOURCE_FILES
|
||||
${PREFIX}autoflake --in-place --recursive $SOURCE_FILES
|
||||
${PREFIX}isort --project=uvicorn $SOURCE_FILES
|
||||
${PREFIX}black --target-version=py36 $SOURCE_FILES
|
||||
${PREFIX}python -m tools.cli_usage
|
||||
|
||||
26
scripts/publish
Executable file
26
scripts/publish
Executable file
@ -0,0 +1,26 @@
|
||||
#!/bin/sh -e
|
||||
|
||||
VERSION_FILE="uvicorn/__init__.py"
|
||||
|
||||
if [ -d 'venv' ] ; then
|
||||
PREFIX="venv/bin/"
|
||||
else
|
||||
PREFIX=""
|
||||
fi
|
||||
|
||||
if [ ! -z "$GITHUB_ACTIONS" ]; then
|
||||
git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
|
||||
git config --local user.name "GitHub Action"
|
||||
|
||||
VERSION=`grep __version__ ${VERSION_FILE} | grep -o '[0-9][^"]*'`
|
||||
|
||||
if [ "refs/tags/${VERSION}" != "${GITHUB_REF}" ] ; then
|
||||
echo "GitHub Ref '${GITHUB_REF}' did not match package version '${VERSION}'"
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
|
||||
set -x
|
||||
|
||||
${PREFIX}twine upload dist/*
|
||||
${PREFIX}mkdocs gh-deploy --force
|
||||
@ -1,9 +0,0 @@
|
||||
#!/bin/sh -e
|
||||
|
||||
SEMVER_REGEX="([0-9]+)\.([0-9]+)\.([0-9]+)(-([0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*))?(\+[0-9A-Za-z-]+)?"
|
||||
CHANGELOG_VERSION=$(grep -o -E $SEMVER_REGEX docs/release-notes.md | head -1)
|
||||
VERSION=$(grep -o -E $SEMVER_REGEX uvicorn/__init__.py | head -1)
|
||||
if [ "$CHANGELOG_VERSION" != "$VERSION" ]; then
|
||||
echo "Version in changelog does not match version in uvicorn/__init__.py!"
|
||||
exit 1
|
||||
fi
|
||||
@ -1,14 +1,17 @@
|
||||
#!/bin/sh
|
||||
|
||||
export PREFIX=""
|
||||
if [ -d 'venv' ] ; then
|
||||
export PREFIX="venv/bin/"
|
||||
fi
|
||||
|
||||
set -ex
|
||||
|
||||
if [ -z $GITHUB_ACTIONS ]; then
|
||||
scripts/check
|
||||
fi
|
||||
|
||||
export COVERAGE_PROCESS_START=$(pwd)/pyproject.toml
|
||||
|
||||
uv run coverage run --debug config -m pytest "$@"
|
||||
${PREFIX}coverage run --debug config -m pytest
|
||||
|
||||
if [ -z $GITHUB_ACTIONS ]; then
|
||||
scripts/coverage
|
||||
|
||||
26
setup.cfg
Normal file
26
setup.cfg
Normal file
@ -0,0 +1,26 @@
|
||||
[flake8]
|
||||
ignore = W503, E203, B305
|
||||
max-line-length = 88
|
||||
|
||||
[mypy]
|
||||
disallow_untyped_defs = True
|
||||
ignore_missing_imports = True
|
||||
follow_imports = silent
|
||||
files = uvicorn/lifespan,tests/test_lifespan.py
|
||||
|
||||
[mypy-tests.*]
|
||||
disallow_untyped_defs = False
|
||||
check_untyped_defs = True
|
||||
|
||||
[tool:isort]
|
||||
profile = black
|
||||
combine_as_imports = True
|
||||
known_first_party = uvicorn,tests
|
||||
known_third_party = click,does_not_exist,gunicorn,h11,httptools,pytest,requests,setuptools,urllib3,uvloop,watchgod,websockets,wsproto,yaml
|
||||
|
||||
[tool:pytest]
|
||||
addopts = -rxXs
|
||||
|
||||
[coverage:run]
|
||||
omit = venv/*
|
||||
include = uvicorn/*, tests/*
|
||||
96
setup.py
Executable file
96
setup.py
Executable file
@ -0,0 +1,96 @@
|
||||
#!/usr/bin/env python
|
||||
# -*- coding: utf-8 -*-
|
||||
|
||||
import os
|
||||
import re
|
||||
|
||||
from setuptools import setup
|
||||
|
||||
|
||||
def get_version(package):
|
||||
"""
|
||||
Return package version as listed in `__version__` in `init.py`.
|
||||
"""
|
||||
path = os.path.join(package, "__init__.py")
|
||||
init_py = open(path, "r", encoding="utf8").read()
|
||||
return re.search("__version__ = ['\"]([^'\"]+)['\"]", init_py).group(1)
|
||||
|
||||
|
||||
def get_long_description():
|
||||
"""
|
||||
Return the README.
|
||||
"""
|
||||
return open("README.md", "r", encoding="utf8").read()
|
||||
|
||||
|
||||
def get_packages(package):
|
||||
"""
|
||||
Return root package and all sub-packages.
|
||||
"""
|
||||
return [
|
||||
dirpath
|
||||
for dirpath, dirnames, filenames in os.walk(package)
|
||||
if os.path.exists(os.path.join(dirpath, "__init__.py"))
|
||||
]
|
||||
|
||||
|
||||
env_marker_cpython = (
|
||||
"sys_platform != 'win32'"
|
||||
" and sys_platform != 'cygwin'"
|
||||
" and platform_python_implementation != 'PyPy'"
|
||||
)
|
||||
|
||||
env_marker_win = "sys_platform == 'win32'"
|
||||
env_marker_below_38 = "python_version < '3.8'"
|
||||
|
||||
minimal_requirements = [
|
||||
"click==7.*",
|
||||
"h11>=0.8",
|
||||
"typing-extensions;" + env_marker_below_38,
|
||||
]
|
||||
|
||||
extra_requirements = [
|
||||
"websockets==8.*",
|
||||
"httptools==0.1.* ;" + env_marker_cpython,
|
||||
"uvloop>=0.14.0 ;" + env_marker_cpython,
|
||||
"colorama>=0.4.*;" + env_marker_win,
|
||||
"watchgod>=0.6,<0.7",
|
||||
"python-dotenv>=0.13.*",
|
||||
"PyYAML>=5.1",
|
||||
]
|
||||
|
||||
|
||||
setup(
|
||||
name="uvicorn",
|
||||
version=get_version("uvicorn"),
|
||||
url="https://github.com/encode/uvicorn",
|
||||
license="BSD",
|
||||
description="The lightning-fast ASGI server.",
|
||||
long_description=get_long_description(),
|
||||
long_description_content_type="text/markdown",
|
||||
author="Tom Christie",
|
||||
author_email="tom@tomchristie.com",
|
||||
packages=get_packages("uvicorn"),
|
||||
install_requires=minimal_requirements,
|
||||
extras_require={"standard": extra_requirements},
|
||||
include_package_data=True,
|
||||
classifiers=[
|
||||
"Development Status :: 4 - Beta",
|
||||
"Environment :: Web Environment",
|
||||
"Intended Audience :: Developers",
|
||||
"License :: OSI Approved :: BSD License",
|
||||
"Operating System :: OS Independent",
|
||||
"Topic :: Internet :: WWW/HTTP",
|
||||
"Programming Language :: Python :: 3",
|
||||
"Programming Language :: Python :: 3.6",
|
||||
"Programming Language :: Python :: 3.7",
|
||||
"Programming Language :: Python :: 3.8",
|
||||
"Programming Language :: Python :: 3.9",
|
||||
"Programming Language :: Python :: Implementation :: CPython",
|
||||
"Programming Language :: Python :: Implementation :: PyPy",
|
||||
],
|
||||
entry_points="""
|
||||
[console_scripts]
|
||||
uvicorn=uvicorn.main:main
|
||||
""",
|
||||
)
|
||||
@ -1,174 +0,0 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
from collections.abc import Callable
|
||||
from typing import TYPE_CHECKING, Any, TypeAlias
|
||||
|
||||
from uvicorn._types import ASGIApplication, Scope
|
||||
from uvicorn.config import Config
|
||||
from uvicorn.lifespan.off import LifespanOff
|
||||
from uvicorn.protocols.http.h11_impl import H11Protocol
|
||||
from uvicorn.server import ServerState
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from uvicorn.protocols.http.httptools_impl import HttpToolsProtocol
|
||||
from uvicorn.protocols.websockets.websockets_impl import WebSocketProtocol
|
||||
from uvicorn.protocols.websockets.wsproto_impl import WSProtocol as _WSProtocol
|
||||
|
||||
WSProtocol: TypeAlias = WebSocketProtocol | _WSProtocol
|
||||
HTTPProtocol: TypeAlias = H11Protocol | HttpToolsProtocol
|
||||
|
||||
|
||||
SIMPLE_GET_REQUEST = b"\r\n".join([b"GET / HTTP/1.1", b"Host: example.org", b"", b""])
|
||||
|
||||
SIMPLE_POST_REQUEST = b"\r\n".join(
|
||||
[
|
||||
b"POST / HTTP/1.1",
|
||||
b"Host: example.org",
|
||||
b"Content-Type: application/json",
|
||||
b"Content-Length: 18",
|
||||
b"",
|
||||
b'{"hello": "world"}',
|
||||
]
|
||||
)
|
||||
|
||||
LARGE_POST_REQUEST = b"\r\n".join(
|
||||
[
|
||||
b"POST / HTTP/1.1",
|
||||
b"Host: example.org",
|
||||
b"Content-Type: text/plain",
|
||||
b"Content-Length: 100000",
|
||||
b"",
|
||||
b"x" * 100000,
|
||||
]
|
||||
)
|
||||
|
||||
HTTP10_GET_REQUEST = b"\r\n".join([b"GET / HTTP/1.0", b"Host: example.org", b"", b""])
|
||||
|
||||
CONNECTION_CLOSE_REQUEST = b"\r\n".join([b"GET / HTTP/1.1", b"Host: example.org", b"Connection: close", b"", b""])
|
||||
|
||||
START_POST_REQUEST = b"\r\n".join(
|
||||
[
|
||||
b"POST / HTTP/1.1",
|
||||
b"Host: example.org",
|
||||
b"Content-Type: application/json",
|
||||
b"Content-Length: 18",
|
||||
b"",
|
||||
b"",
|
||||
]
|
||||
)
|
||||
|
||||
FINISH_POST_REQUEST = b'{"hello": "world"}'
|
||||
|
||||
BODY_CHUNK_SIZE = 256
|
||||
FRAGMENTED_BODY_SIZE = 100_000
|
||||
FRAGMENTED_POST_HEADERS = b"\r\n".join(
|
||||
[
|
||||
b"POST / HTTP/1.1",
|
||||
b"Host: example.org",
|
||||
b"Content-Type: application/octet-stream",
|
||||
b"Content-Length: " + str(FRAGMENTED_BODY_SIZE).encode(),
|
||||
b"",
|
||||
b"",
|
||||
]
|
||||
)
|
||||
FRAGMENTED_BODY_CHUNKS = [b"x" * BODY_CHUNK_SIZE] * (FRAGMENTED_BODY_SIZE // BODY_CHUNK_SIZE)
|
||||
|
||||
|
||||
class MockTransport:
|
||||
def __init__(self) -> None:
|
||||
self.buffer = b""
|
||||
self.closed = False
|
||||
self.read_paused = False
|
||||
|
||||
def get_extra_info(self, key: Any) -> Any:
|
||||
return {
|
||||
"sockname": ("127.0.0.1", 8000),
|
||||
"peername": ("127.0.0.1", 8001),
|
||||
"sslcontext": False,
|
||||
}.get(key)
|
||||
|
||||
def write(self, data: bytes) -> None:
|
||||
self.buffer += data
|
||||
|
||||
def close(self) -> None:
|
||||
self.closed = True
|
||||
|
||||
def pause_reading(self) -> None:
|
||||
self.read_paused = True
|
||||
|
||||
def resume_reading(self) -> None:
|
||||
self.read_paused = False
|
||||
|
||||
def is_closing(self) -> bool:
|
||||
return self.closed
|
||||
|
||||
def clear_buffer(self) -> None:
|
||||
self.buffer = b""
|
||||
|
||||
def set_protocol(self, protocol: asyncio.Protocol) -> None:
|
||||
pass
|
||||
|
||||
|
||||
class MockTimerHandle:
|
||||
def __init__(
|
||||
self, loop_later_list: list[MockTimerHandle], delay: float, callback: Callable[[], None], args: tuple[Any, ...]
|
||||
) -> None:
|
||||
self.loop_later_list = loop_later_list
|
||||
self.delay = delay
|
||||
self.callback = callback
|
||||
self.args = args
|
||||
self.cancelled = False
|
||||
|
||||
def cancel(self) -> None:
|
||||
if not self.cancelled:
|
||||
self.cancelled = True
|
||||
self.loop_later_list.remove(self)
|
||||
|
||||
|
||||
class MockLoop:
|
||||
def __init__(self) -> None:
|
||||
self._tasks: list[asyncio.Task[Any]] = []
|
||||
self._later: list[MockTimerHandle] = []
|
||||
|
||||
def create_task(self, coroutine: Any) -> Any:
|
||||
self._tasks.insert(0, coroutine)
|
||||
return MockTask()
|
||||
|
||||
def call_later(self, delay: float, callback: Callable[[], None], *args: Any) -> MockTimerHandle:
|
||||
handle = MockTimerHandle(self._later, delay, callback, args)
|
||||
self._later.insert(0, handle)
|
||||
return handle
|
||||
|
||||
async def run_one(self) -> Any:
|
||||
return await self._tasks.pop()
|
||||
|
||||
|
||||
class MockTask:
|
||||
def add_done_callback(self, callback: Callable[[], None]) -> None:
|
||||
pass
|
||||
|
||||
|
||||
class MockProtocol(asyncio.Protocol):
|
||||
loop: MockLoop
|
||||
transport: MockTransport
|
||||
timeout_keep_alive_task: asyncio.TimerHandle | None
|
||||
ws_protocol_class: type[WSProtocol] | None
|
||||
scope: Scope
|
||||
|
||||
|
||||
def make_config(app: ASGIApplication, **kwargs: Any) -> Config:
|
||||
return Config(app=app, **kwargs)
|
||||
|
||||
|
||||
def get_connected_protocol(
|
||||
config: Config,
|
||||
http_protocol_cls: type[HTTPProtocol],
|
||||
) -> MockProtocol:
|
||||
loop = MockLoop()
|
||||
transport = MockTransport()
|
||||
lifespan = LifespanOff(config)
|
||||
server_state = ServerState()
|
||||
protocol = http_protocol_cls(config=config, server_state=server_state, app_state=lifespan.state, _loop=loop) # type: ignore
|
||||
protocol.connection_made(transport) # type: ignore[arg-type]
|
||||
return protocol # type: ignore[return-value]
|
||||
@ -1,115 +0,0 @@
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import TYPE_CHECKING
|
||||
|
||||
import pytest
|
||||
|
||||
from tests.benchmarks.http import (
|
||||
CONNECTION_CLOSE_REQUEST,
|
||||
FINISH_POST_REQUEST,
|
||||
FRAGMENTED_BODY_CHUNKS,
|
||||
FRAGMENTED_POST_HEADERS,
|
||||
HTTP10_GET_REQUEST,
|
||||
LARGE_POST_REQUEST,
|
||||
SIMPLE_GET_REQUEST,
|
||||
SIMPLE_POST_REQUEST,
|
||||
START_POST_REQUEST,
|
||||
get_connected_protocol,
|
||||
make_config,
|
||||
)
|
||||
from tests.response import Response
|
||||
from uvicorn._types import ASGIReceiveCallable, ASGISendCallable, Scope
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from tests.benchmarks.http import HTTPProtocol
|
||||
|
||||
pytestmark = [pytest.mark.anyio, pytest.mark.benchmark]
|
||||
|
||||
_plain_text_app = Response("Hello, world", media_type="text/plain")
|
||||
_no_content_app = Response(b"", status_code=204)
|
||||
_chunked_app = Response(b"Hello, world!", status_code=200, headers={"transfer-encoding": "chunked"})
|
||||
|
||||
_plain_text_config = make_config(_plain_text_app)
|
||||
_chunked_config = make_config(_chunked_app)
|
||||
|
||||
|
||||
async def _body_echo_app(scope: Scope, receive: ASGIReceiveCallable, send: ASGISendCallable) -> None:
|
||||
body = b""
|
||||
while True:
|
||||
message = await receive()
|
||||
body += message.get("body", b"") # type: ignore[operator]
|
||||
if not message.get("more_body", False):
|
||||
break
|
||||
headers = [(b"content-length", str(len(body)).encode())]
|
||||
await send({"type": "http.response.start", "status": 200, "headers": headers})
|
||||
await send({"type": "http.response.body", "body": body})
|
||||
|
||||
|
||||
_body_echo_config = make_config(_body_echo_app)
|
||||
|
||||
|
||||
async def test_bench_simple_get(http_protocol_cls: type[HTTPProtocol]) -> None:
|
||||
protocol = get_connected_protocol(_plain_text_config, http_protocol_cls)
|
||||
protocol.data_received(SIMPLE_GET_REQUEST)
|
||||
await protocol.loop.run_one()
|
||||
|
||||
|
||||
async def test_bench_simple_post(http_protocol_cls: type[HTTPProtocol]) -> None:
|
||||
protocol = get_connected_protocol(_plain_text_config, http_protocol_cls)
|
||||
protocol.data_received(SIMPLE_POST_REQUEST)
|
||||
await protocol.loop.run_one()
|
||||
|
||||
|
||||
async def test_bench_large_post(http_protocol_cls: type[HTTPProtocol]) -> None:
|
||||
protocol = get_connected_protocol(_plain_text_config, http_protocol_cls)
|
||||
protocol.data_received(LARGE_POST_REQUEST)
|
||||
await protocol.loop.run_one()
|
||||
|
||||
|
||||
async def test_bench_pipelined_requests(http_protocol_cls: type[HTTPProtocol]) -> None:
|
||||
protocol = get_connected_protocol(_plain_text_config, http_protocol_cls)
|
||||
protocol.data_received(SIMPLE_GET_REQUEST * 3)
|
||||
await protocol.loop.run_one()
|
||||
await protocol.loop.run_one()
|
||||
await protocol.loop.run_one()
|
||||
|
||||
|
||||
async def test_bench_keepalive_reuse(http_protocol_cls: type[HTTPProtocol]) -> None:
|
||||
protocol = get_connected_protocol(_plain_text_config, http_protocol_cls)
|
||||
protocol.data_received(SIMPLE_GET_REQUEST)
|
||||
await protocol.loop.run_one()
|
||||
protocol.data_received(SIMPLE_GET_REQUEST)
|
||||
await protocol.loop.run_one()
|
||||
|
||||
|
||||
async def test_bench_chunked_response(http_protocol_cls: type[HTTPProtocol]) -> None:
|
||||
protocol = get_connected_protocol(_chunked_config, http_protocol_cls)
|
||||
protocol.data_received(SIMPLE_GET_REQUEST)
|
||||
await protocol.loop.run_one()
|
||||
|
||||
|
||||
async def test_bench_http10(http_protocol_cls: type[HTTPProtocol]) -> None:
|
||||
protocol = get_connected_protocol(_plain_text_config, http_protocol_cls)
|
||||
protocol.data_received(HTTP10_GET_REQUEST)
|
||||
await protocol.loop.run_one()
|
||||
|
||||
|
||||
async def test_bench_connection_close(http_protocol_cls: type[HTTPProtocol]) -> None:
|
||||
protocol = get_connected_protocol(_plain_text_config, http_protocol_cls)
|
||||
protocol.data_received(CONNECTION_CLOSE_REQUEST)
|
||||
await protocol.loop.run_one()
|
||||
|
||||
|
||||
async def test_bench_fragmented_body(http_protocol_cls: type[HTTPProtocol]) -> None:
|
||||
protocol = get_connected_protocol(_plain_text_config, http_protocol_cls)
|
||||
protocol.data_received(FRAGMENTED_POST_HEADERS)
|
||||
for chunk in FRAGMENTED_BODY_CHUNKS:
|
||||
protocol.data_received(chunk)
|
||||
await protocol.loop.run_one()
|
||||
|
||||
|
||||
async def test_bench_post_body_receive(http_protocol_cls: type[HTTPProtocol]) -> None:
|
||||
protocol = get_connected_protocol(_body_echo_config, http_protocol_cls)
|
||||
protocol.data_received(START_POST_REQUEST)
|
||||
protocol.data_received(FINISH_POST_REQUEST)
|
||||
await protocol.loop.run_one()
|
||||
@ -1,64 +0,0 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import importlib.util
|
||||
from typing import TYPE_CHECKING
|
||||
|
||||
import pytest
|
||||
|
||||
from tests.benchmarks.http import make_config
|
||||
from tests.benchmarks.ws import WS_UPGRADE, get_connected_ws_protocol
|
||||
from uvicorn._types import ASGIReceiveCallable, ASGISendCallable, Scope
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from tests.benchmarks.ws import WSProtocolClass
|
||||
|
||||
pytestmark = [pytest.mark.anyio, pytest.mark.benchmark]
|
||||
|
||||
|
||||
@pytest.fixture(
|
||||
params=[
|
||||
pytest.param(
|
||||
"wsproto",
|
||||
marks=pytest.mark.skipif(not importlib.util.find_spec("wsproto"), reason="wsproto not installed."),
|
||||
id="wsproto",
|
||||
),
|
||||
pytest.param("websockets-sansio", id="websockets-sansio"),
|
||||
]
|
||||
)
|
||||
def ws_cls(request: pytest.FixtureRequest) -> WSProtocolClass:
|
||||
if request.param == "wsproto":
|
||||
from uvicorn.protocols.websockets.wsproto_impl import WSProtocol
|
||||
|
||||
return WSProtocol
|
||||
from uvicorn.protocols.websockets.websockets_sansio_impl import WebSocketsSansIOProtocol
|
||||
|
||||
return WebSocketsSansIOProtocol
|
||||
|
||||
|
||||
async def _ws_accept_close_app(scope: Scope, receive: ASGIReceiveCallable, send: ASGISendCallable) -> None:
|
||||
await receive()
|
||||
await send({"type": "websocket.accept"})
|
||||
await send({"type": "websocket.close", "code": 1000})
|
||||
|
||||
|
||||
async def _ws_send_text_app(scope: Scope, receive: ASGIReceiveCallable, send: ASGISendCallable) -> None:
|
||||
await receive()
|
||||
await send({"type": "websocket.accept"})
|
||||
await send({"type": "websocket.send", "text": "Hello, world!"})
|
||||
await send({"type": "websocket.close", "code": 1000})
|
||||
|
||||
|
||||
_ws_accept_close_config = make_config(_ws_accept_close_app, access_log=False)
|
||||
_ws_send_text_config = make_config(_ws_send_text_app, access_log=False)
|
||||
|
||||
|
||||
async def test_bench_ws_handshake(ws_cls: WSProtocolClass) -> None:
|
||||
protocol = get_connected_ws_protocol(_ws_accept_close_config, ws_cls)
|
||||
protocol.data_received(WS_UPGRADE)
|
||||
await protocol.loop.run_one()
|
||||
|
||||
|
||||
async def test_bench_ws_send_text(ws_cls: WSProtocolClass) -> None:
|
||||
protocol = get_connected_ws_protocol(_ws_send_text_config, ws_cls)
|
||||
protocol.data_received(WS_UPGRADE)
|
||||
await protocol.loop.run_one()
|
||||
@ -1,40 +0,0 @@
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import TYPE_CHECKING, Any, TypeAlias
|
||||
|
||||
from tests.benchmarks.http import MockLoop, MockTransport
|
||||
from uvicorn.config import Config
|
||||
from uvicorn.lifespan.off import LifespanOff
|
||||
from uvicorn.server import ServerState
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from uvicorn.protocols.websockets.websockets_sansio_impl import WebSocketsSansIOProtocol
|
||||
from uvicorn.protocols.websockets.wsproto_impl import WSProtocol
|
||||
|
||||
WSProtocolClass: TypeAlias = type[WSProtocol] | type[WebSocketsSansIOProtocol]
|
||||
|
||||
WS_UPGRADE = (
|
||||
b"GET / HTTP/1.1\r\n"
|
||||
b"Host: example.org\r\n"
|
||||
b"Upgrade: websocket\r\n"
|
||||
b"Connection: Upgrade\r\n"
|
||||
b"Sec-WebSocket-Key: YmVuY2htYXJra2V5MTIzNA==\r\n"
|
||||
b"Sec-WebSocket-Version: 13\r\n"
|
||||
b"\r\n"
|
||||
)
|
||||
|
||||
# Masked text frame: "Hello, world!" (13 bytes) with zero mask key
|
||||
WS_TEXT_FRAME = b"\x81\x8d\x00\x00\x00\x00Hello, world!"
|
||||
|
||||
# Masked close frame: code 1000 with zero mask key
|
||||
WS_CLOSE_FRAME = b"\x88\x82\x00\x00\x00\x00\x03\xe8"
|
||||
|
||||
|
||||
def get_connected_ws_protocol(config: Config, ws_protocol_cls: WSProtocolClass) -> Any:
|
||||
loop = MockLoop()
|
||||
transport = MockTransport()
|
||||
lifespan = LifespanOff(config)
|
||||
server_state = ServerState()
|
||||
protocol = ws_protocol_cls(config=config, server_state=server_state, app_state=lifespan.state, _loop=loop) # type: ignore[arg-type]
|
||||
protocol.connection_made(transport) # type: ignore[arg-type]
|
||||
return protocol
|
||||
139
tests/client.py
Normal file
139
tests/client.py
Normal file
@ -0,0 +1,139 @@
|
||||
import asyncio
|
||||
import io
|
||||
import typing
|
||||
from urllib.parse import unquote, urljoin, urlparse
|
||||
|
||||
import requests
|
||||
|
||||
|
||||
class _HeaderDict(requests.packages.urllib3._collections.HTTPHeaderDict):
|
||||
def get_all(self, key, default):
|
||||
return self.getheaders(key)
|
||||
|
||||
|
||||
class _MockOriginalResponse(object):
|
||||
"""
|
||||
We have to jump through some hoops to present the response as if
|
||||
it was made using urllib3.
|
||||
"""
|
||||
|
||||
def __init__(self, headers):
|
||||
self.msg = _HeaderDict(headers)
|
||||
self.closed = False
|
||||
|
||||
def isclosed(self):
|
||||
return self.closed
|
||||
|
||||
|
||||
class _ASGIAdapter(requests.adapters.HTTPAdapter):
|
||||
def __init__(self, app: typing.Callable, raise_server_exceptions=True) -> None:
|
||||
self.app = app
|
||||
self.raise_server_exceptions = raise_server_exceptions
|
||||
|
||||
def send(self, request, *args, **kwargs):
|
||||
scheme, netloc, path, params, query, fragement = urlparse(request.url)
|
||||
if ":" in netloc:
|
||||
host, port = netloc.split(":", 1)
|
||||
port = int(port)
|
||||
else:
|
||||
host = netloc
|
||||
port = {"http": 80, "ws": 80, "https": 443, "wss": 443}[scheme]
|
||||
|
||||
# Include the 'host' header.
|
||||
if "host" in request.headers:
|
||||
headers = []
|
||||
elif port == 80:
|
||||
headers = [[b"host", host.encode()]]
|
||||
else:
|
||||
headers = [[b"host", ("%s:%d" % (host, port)).encode()]]
|
||||
|
||||
# Include other request headers.
|
||||
headers += [
|
||||
[key.lower().encode(), value.encode()]
|
||||
for key, value in request.headers.items()
|
||||
]
|
||||
|
||||
scope = {
|
||||
"type": "http",
|
||||
"http_version": "1.1",
|
||||
"method": request.method,
|
||||
"path": unquote(path),
|
||||
"root_path": "",
|
||||
"scheme": scheme,
|
||||
"query_string": query.encode(),
|
||||
"headers": headers,
|
||||
"client": ["testclient", 50000],
|
||||
"server": [host, port],
|
||||
}
|
||||
|
||||
async def receive():
|
||||
body = request.body
|
||||
if body is None:
|
||||
body_bytes = b""
|
||||
else:
|
||||
assert isinstance(body, bytes)
|
||||
body_bytes = body
|
||||
return {"type": "http.request", "body": body_bytes}
|
||||
|
||||
async def send(message):
|
||||
nonlocal raw_kwargs, response_started
|
||||
|
||||
if message["type"] == "http.response.start":
|
||||
raw_kwargs["version"] = 11
|
||||
raw_kwargs["status"] = message["status"]
|
||||
raw_kwargs["headers"] = [
|
||||
(key.decode(), value.decode()) for key, value in message["headers"]
|
||||
]
|
||||
raw_kwargs["preload_content"] = False
|
||||
raw_kwargs["original_response"] = _MockOriginalResponse(
|
||||
raw_kwargs["headers"]
|
||||
)
|
||||
response_started = True
|
||||
elif message["type"] == "http.response.body":
|
||||
body = message.get("body", b"")
|
||||
more_body = message.get("more_body", False)
|
||||
raw_kwargs["body"].write(body)
|
||||
if not more_body:
|
||||
raw_kwargs["body"].seek(0)
|
||||
|
||||
response_started = False
|
||||
raw_kwargs = {"body": io.BytesIO()}
|
||||
|
||||
loop = asyncio.get_event_loop()
|
||||
|
||||
try:
|
||||
loop.run_until_complete(self.app(scope, receive, send))
|
||||
except BaseException as exc:
|
||||
if self.raise_server_exceptions:
|
||||
raise exc from None
|
||||
|
||||
raw = requests.packages.urllib3.HTTPResponse(**raw_kwargs)
|
||||
return self.build_response(request, raw)
|
||||
|
||||
|
||||
class _TestClient(requests.Session):
|
||||
def __init__(
|
||||
self, app: typing.Callable, base_url: str, raise_server_exceptions=True
|
||||
) -> None:
|
||||
super(_TestClient, self).__init__()
|
||||
adapter = _ASGIAdapter(app, raise_server_exceptions=raise_server_exceptions)
|
||||
self.mount("http://", adapter)
|
||||
self.mount("https://", adapter)
|
||||
self.headers.update({"user-agent": "testclient"})
|
||||
self.base_url = base_url
|
||||
|
||||
def request(self, method: str, url: str, **kwargs) -> requests.Response:
|
||||
url = urljoin(self.base_url, url)
|
||||
return super().request(method, url, **kwargs)
|
||||
|
||||
|
||||
def TestClient(
|
||||
app: typing.Callable,
|
||||
base_url: str = "http://testserver",
|
||||
raise_server_exceptions=True,
|
||||
) -> _TestClient:
|
||||
"""
|
||||
We have to work around py.test discovery attempting to pick up
|
||||
the `TestClient` class, by declaring this as a function.
|
||||
"""
|
||||
return _TestClient(app, base_url, raise_server_exceptions=raise_server_exceptions)
|
||||
@ -1,53 +1,17 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import contextlib
|
||||
import importlib.util
|
||||
import os
|
||||
import socket
|
||||
import ssl
|
||||
from copy import deepcopy
|
||||
from hashlib import md5
|
||||
from pathlib import Path
|
||||
from tempfile import TemporaryDirectory
|
||||
from typing import Any
|
||||
from uuid import uuid4
|
||||
|
||||
import pytest
|
||||
|
||||
try:
|
||||
import trustme
|
||||
from cryptography.hazmat.backends import default_backend
|
||||
from cryptography.hazmat.primitives import serialization
|
||||
|
||||
HAVE_TRUSTME = True
|
||||
except ImportError: # pragma: no cover
|
||||
HAVE_TRUSTME = False
|
||||
|
||||
from uvicorn.config import LOGGING_CONFIG
|
||||
from uvicorn.importer import import_from_string
|
||||
|
||||
# Note: We explicitly turn the propagate on just for tests, because pytest
|
||||
# caplog not able to capture no-propagate loggers.
|
||||
#
|
||||
# And the caplog_for_logger helper also not work on test config cases, because
|
||||
# when create Config object, Config.configure_logging will remove caplog.handler.
|
||||
#
|
||||
# The simple solution is set propagate=True before execute tests.
|
||||
#
|
||||
# See also: https://github.com/pytest-dev/pytest/issues/3697
|
||||
LOGGING_CONFIG["loggers"]["uvicorn"]["propagate"] = True
|
||||
import trustme
|
||||
from cryptography.hazmat.backends import default_backend
|
||||
from cryptography.hazmat.primitives import serialization
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def tls_certificate_authority() -> trustme.CA:
|
||||
if not HAVE_TRUSTME:
|
||||
pytest.skip("trustme not installed") # pragma: no cover
|
||||
return trustme.CA()
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def tls_certificate(tls_certificate_authority: trustme.CA) -> trustme.LeafCert:
|
||||
return tls_certificate_authority.issue_cert(
|
||||
def tls_certificate(tls_certificate_authority):
|
||||
return tls_certificate_authority.issue_server_cert(
|
||||
"localhost",
|
||||
"127.0.0.1",
|
||||
"::1",
|
||||
@ -55,21 +19,21 @@ def tls_certificate(tls_certificate_authority: trustme.CA) -> trustme.LeafCert:
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def tls_ca_certificate_pem_path(tls_certificate_authority: trustme.CA):
|
||||
def tls_ca_certificate_pem_path(tls_certificate_authority):
|
||||
with tls_certificate_authority.cert_pem.tempfile() as ca_cert_pem:
|
||||
yield ca_cert_pem
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def tls_ca_certificate_private_key_path(tls_certificate_authority: trustme.CA):
|
||||
def tls_ca_certificate_private_key_path(tls_certificate_authority):
|
||||
with tls_certificate_authority.private_key_pem.tempfile() as private_key:
|
||||
yield private_key
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def tls_certificate_private_key_encrypted_path(tls_certificate):
|
||||
def tls_ca_certificate_private_key_encrypted_path(tls_certificate_authority):
|
||||
private_key = serialization.load_pem_private_key(
|
||||
tls_certificate.private_key_pem.bytes(),
|
||||
tls_certificate_authority.private_key_pem.bytes(),
|
||||
password=None,
|
||||
backend=default_backend(),
|
||||
)
|
||||
@ -83,178 +47,6 @@ def tls_certificate_private_key_encrypted_path(tls_certificate):
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def tls_certificate_private_key_path(tls_certificate: trustme.CA):
|
||||
with tls_certificate.private_key_pem.tempfile() as private_key:
|
||||
yield private_key
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def tls_certificate_key_and_chain_path(tls_certificate: trustme.LeafCert):
|
||||
def tls_certificate_pem_path(tls_certificate):
|
||||
with tls_certificate.private_key_and_cert_chain_pem.tempfile() as cert_pem:
|
||||
yield cert_pem
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def tls_certificate_server_cert_path(tls_certificate: trustme.LeafCert):
|
||||
with tls_certificate.cert_chain_pems[0].tempfile() as cert_pem:
|
||||
yield cert_pem
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def tls_ca_ssl_context(tls_certificate_authority: trustme.CA) -> ssl.SSLContext:
|
||||
ssl_ctx = ssl.create_default_context(ssl.Purpose.SERVER_AUTH)
|
||||
tls_certificate_authority.configure_trust(ssl_ctx)
|
||||
return ssl_ctx
|
||||
|
||||
|
||||
@pytest.fixture(scope="package")
|
||||
def reload_directory_structure(tmp_path_factory: pytest.TempPathFactory):
|
||||
"""
|
||||
This fixture creates a directory structure to enable reload parameter tests
|
||||
|
||||
The fixture has the following structure:
|
||||
root
|
||||
├── [app, app_first, app_second, app_third]
|
||||
│ ├── css
|
||||
│ │ └── main.css
|
||||
│ ├── js
|
||||
│ │ └── main.js
|
||||
│ ├── src
|
||||
│ │ └── main.py
|
||||
│ └── sub
|
||||
│ └── sub.py
|
||||
├── ext
|
||||
│ └── ext.jpg
|
||||
├── .dotted
|
||||
├── .dotted_dir
|
||||
│ └── file.txt
|
||||
└── main.py
|
||||
"""
|
||||
root = tmp_path_factory.mktemp("reload_directory")
|
||||
apps = ["app", "app_first", "app_second", "app_third"]
|
||||
|
||||
root_file = root / "main.py"
|
||||
root_file.touch()
|
||||
|
||||
dotted_file = root / ".dotted"
|
||||
dotted_file.touch()
|
||||
|
||||
dotted_dir = root / ".dotted_dir"
|
||||
dotted_dir.mkdir()
|
||||
dotted_dir_file = dotted_dir / "file.txt"
|
||||
dotted_dir_file.touch()
|
||||
|
||||
for app in apps:
|
||||
app_path = root / app
|
||||
app_path.mkdir()
|
||||
dir_files = [
|
||||
("src", ["main.py"]),
|
||||
("js", ["main.js"]),
|
||||
("css", ["main.css"]),
|
||||
("sub", ["sub.py"]),
|
||||
]
|
||||
for directory, files in dir_files:
|
||||
directory_path = app_path / directory
|
||||
directory_path.mkdir()
|
||||
for file in files:
|
||||
file_path = directory_path / file
|
||||
file_path.touch()
|
||||
ext_dir = root / "ext"
|
||||
ext_dir.mkdir()
|
||||
ext_file = ext_dir / "ext.jpg"
|
||||
ext_file.touch()
|
||||
|
||||
yield root
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def anyio_backend() -> str:
|
||||
return "asyncio"
|
||||
|
||||
|
||||
@pytest.fixture(scope="function")
|
||||
def logging_config() -> dict[str, Any]:
|
||||
return deepcopy(LOGGING_CONFIG)
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def short_socket_name(tmp_path, tmp_path_factory): # pragma: py-win32
|
||||
max_sock_len = 100
|
||||
socket_filename = "my.sock"
|
||||
identifier = f"{uuid4()}-"
|
||||
identifier_len = len(identifier.encode())
|
||||
tmp_dir = Path("/tmp").resolve()
|
||||
os_tmp_dir = Path(os.getenv("TMPDIR", "/tmp")).resolve()
|
||||
basetemp = Path(
|
||||
str(tmp_path_factory.getbasetemp()),
|
||||
).resolve()
|
||||
hash_basetemp = md5(
|
||||
str(basetemp).encode(),
|
||||
).hexdigest()
|
||||
|
||||
def make_tmp_dir(base_dir):
|
||||
return TemporaryDirectory(
|
||||
dir=str(base_dir),
|
||||
prefix="p-",
|
||||
suffix=f"-{hash_basetemp}",
|
||||
)
|
||||
|
||||
paths = basetemp, os_tmp_dir, tmp_dir
|
||||
for _num, tmp_dir_path in enumerate(paths, 1):
|
||||
with make_tmp_dir(tmp_dir_path) as tmpd:
|
||||
tmpd = Path(tmpd).resolve()
|
||||
sock_path = str(tmpd / socket_filename)
|
||||
sock_path_len = len(sock_path.encode())
|
||||
if sock_path_len <= max_sock_len:
|
||||
if max_sock_len - sock_path_len >= identifier_len: # pragma: no cover
|
||||
sock_path = str(tmpd / "".join((identifier, socket_filename)))
|
||||
yield sock_path
|
||||
return
|
||||
|
||||
|
||||
def _unused_port(socket_type: int) -> int:
|
||||
"""Find an unused localhost port from 1024-65535 and return it."""
|
||||
with contextlib.closing(socket.socket(type=socket_type)) as sock:
|
||||
sock.bind(("127.0.0.1", 0))
|
||||
return sock.getsockname()[1]
|
||||
|
||||
|
||||
# This was copied from pytest-asyncio.
|
||||
# Ref.: https://github.com/pytest-dev/pytest-asyncio/blob/25d9592286682bc6dbfbf291028ff7a9594cf283/pytest_asyncio/plugin.py#L525-L527 # noqa: E501
|
||||
@pytest.fixture
|
||||
def unused_tcp_port() -> int:
|
||||
return _unused_port(socket.SOCK_STREAM)
|
||||
|
||||
|
||||
@pytest.fixture(
|
||||
params=[
|
||||
pytest.param(
|
||||
"uvicorn.protocols.websockets.wsproto_impl:WSProtocol",
|
||||
marks=pytest.mark.skipif(not importlib.util.find_spec("wsproto"), reason="wsproto not installed."),
|
||||
id="wsproto",
|
||||
),
|
||||
pytest.param("uvicorn.protocols.websockets.websockets_impl:WebSocketProtocol", id="websockets"),
|
||||
pytest.param(
|
||||
"uvicorn.protocols.websockets.websockets_sansio_impl:WebSocketsSansIOProtocol", id="websockets-sansio"
|
||||
),
|
||||
]
|
||||
)
|
||||
def ws_protocol_cls(request: pytest.FixtureRequest):
|
||||
return import_from_string(request.param)
|
||||
|
||||
|
||||
@pytest.fixture(
|
||||
params=[
|
||||
pytest.param(
|
||||
"uvicorn.protocols.http.httptools_impl:HttpToolsProtocol",
|
||||
marks=pytest.mark.skipif(
|
||||
not importlib.util.find_spec("httptools"),
|
||||
reason="httptools not installed.",
|
||||
),
|
||||
id="httptools",
|
||||
),
|
||||
pytest.param("uvicorn.protocols.http.h11_impl:H11Protocol", id="h11"),
|
||||
]
|
||||
)
|
||||
def http_protocol_cls(request: pytest.FixtureRequest):
|
||||
return import_from_string(request.param)
|
||||
|
||||
@ -1,7 +0,0 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
|
||||
|
||||
class CustomLoop(asyncio.SelectorEventLoop):
|
||||
pass
|
||||
@ -1,4 +0,0 @@
|
||||
# Used by test_importer.py
|
||||
from .circular_import_b import foo # noqa
|
||||
|
||||
bar = 123 # pragma: no cover
|
||||
@ -1,4 +0,0 @@
|
||||
# Used by test_importer.py
|
||||
from .circular_import_a import bar # noqa
|
||||
|
||||
foo = 123 # pragma: no cover
|
||||
@ -3,51 +3,41 @@ import pytest
|
||||
from uvicorn.importer import ImportFromStringError, import_from_string
|
||||
|
||||
|
||||
def test_invalid_format() -> None:
|
||||
def test_invalid_format():
|
||||
with pytest.raises(ImportFromStringError) as exc_info:
|
||||
import_from_string("example:")
|
||||
expected = 'Import string "example:" must be in format "<module>:<attribute>".'
|
||||
assert expected in str(exc_info.value)
|
||||
|
||||
|
||||
def test_invalid_module() -> None:
|
||||
def test_invalid_module():
|
||||
with pytest.raises(ImportFromStringError) as exc_info:
|
||||
import_from_string("module_does_not_exist:myattr")
|
||||
expected = 'Could not import module "module_does_not_exist".'
|
||||
assert expected in str(exc_info.value)
|
||||
|
||||
|
||||
def test_invalid_attr() -> None:
|
||||
def test_invalid_attr():
|
||||
with pytest.raises(ImportFromStringError) as exc_info:
|
||||
import_from_string("tempfile:attr_does_not_exist")
|
||||
expected = 'Attribute "attr_does_not_exist" not found in module "tempfile".'
|
||||
assert expected in str(exc_info.value)
|
||||
|
||||
|
||||
def test_internal_import_error() -> None:
|
||||
def test_internal_import_error():
|
||||
with pytest.raises(ImportError):
|
||||
import_from_string("tests.importer.raise_import_error:myattr")
|
||||
|
||||
|
||||
def test_valid_import() -> None:
|
||||
def test_valid_import():
|
||||
instance = import_from_string("tempfile:TemporaryFile")
|
||||
from tempfile import TemporaryFile
|
||||
|
||||
assert instance == TemporaryFile
|
||||
|
||||
|
||||
def test_no_import_needed() -> None:
|
||||
def test_no_import_needed():
|
||||
from tempfile import TemporaryFile
|
||||
|
||||
instance = import_from_string(TemporaryFile)
|
||||
assert instance == TemporaryFile
|
||||
|
||||
|
||||
def test_circular_import_error() -> None:
|
||||
with pytest.raises(ImportError) as exc_info:
|
||||
import_from_string("tests.importer.circular_import_a:bar")
|
||||
expected = (
|
||||
"cannot import name 'bar' from partially initialized module "
|
||||
"'tests.importer.circular_import_a' (most likely due to a circular import)"
|
||||
)
|
||||
assert expected in str(exc_info.value)
|
||||
|
||||
54
tests/middleware/test_debug.py
Normal file
54
tests/middleware/test_debug.py
Normal file
@ -0,0 +1,54 @@
|
||||
import asyncio
|
||||
|
||||
import pytest
|
||||
|
||||
from tests.client import TestClient
|
||||
from uvicorn.middleware.debug import DebugMiddleware
|
||||
|
||||
|
||||
def test_debug_text():
|
||||
async def app(scope, receive, send):
|
||||
raise RuntimeError("Something went wrong")
|
||||
|
||||
app = DebugMiddleware(app)
|
||||
client = TestClient(app, raise_server_exceptions=False)
|
||||
response = client.get("/")
|
||||
assert response.status_code == 500
|
||||
assert response.headers["content-type"].startswith("text/plain")
|
||||
assert "RuntimeError" in response.text
|
||||
|
||||
|
||||
def test_debug_html():
|
||||
async def app(scope, receive, send):
|
||||
raise RuntimeError("Something went wrong")
|
||||
|
||||
app = DebugMiddleware(app)
|
||||
client = TestClient(app, raise_server_exceptions=False)
|
||||
response = client.get("/", headers={"Accept": "text/html, */*"})
|
||||
assert response.status_code == 500
|
||||
assert response.headers["content-type"].startswith("text/html")
|
||||
assert "RuntimeError" in response.text
|
||||
|
||||
|
||||
def test_debug_after_response_sent():
|
||||
async def app(scope, receive, send):
|
||||
await send({"type": "http.response.start", "status": 204, "headers": []})
|
||||
await send({"type": "http.response.body", "body": b"", "more_body": False})
|
||||
raise RuntimeError("Something went wrong")
|
||||
|
||||
app = DebugMiddleware(app)
|
||||
client = TestClient(app, raise_server_exceptions=False)
|
||||
response = client.get("/")
|
||||
assert response.status_code == 204
|
||||
assert response.content == b""
|
||||
|
||||
|
||||
def test_debug_not_http():
|
||||
async def app(scope, send, receive):
|
||||
raise RuntimeError("Something went wrong")
|
||||
|
||||
app = DebugMiddleware(app)
|
||||
|
||||
with pytest.raises(RuntimeError):
|
||||
loop = asyncio.get_event_loop()
|
||||
loop.run_until_complete(app({"type": "websocket"}, None, None))
|
||||
@ -1,64 +1,57 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import contextlib
|
||||
import logging
|
||||
import socket
|
||||
import platform
|
||||
import sys
|
||||
from collections.abc import Iterator
|
||||
from typing import TYPE_CHECKING, Any, TypeAlias
|
||||
import threading
|
||||
import time
|
||||
|
||||
import httpx
|
||||
import pytest
|
||||
import websockets.client
|
||||
from websockets.protocol import State
|
||||
import requests
|
||||
|
||||
from tests.utils import run_server
|
||||
from uvicorn import Config
|
||||
from uvicorn._types import ASGIReceiveCallable, ASGISendCallable, Scope
|
||||
|
||||
if TYPE_CHECKING:
|
||||
import sys
|
||||
|
||||
from uvicorn.protocols.websockets.websockets_impl import WebSocketProtocol
|
||||
from uvicorn.protocols.websockets.wsproto_impl import WSProtocol as _WSProtocol
|
||||
|
||||
WSProtocol: TypeAlias = "type[WebSocketProtocol | _WSProtocol]"
|
||||
|
||||
pytestmark = pytest.mark.anyio
|
||||
from uvicorn import Config, Server
|
||||
|
||||
|
||||
@contextlib.contextmanager
|
||||
def caplog_for_logger(caplog: pytest.LogCaptureFixture, logger_name: str) -> Iterator[pytest.LogCaptureFixture]:
|
||||
def caplog_for_logger(caplog, logger_name):
|
||||
logger = logging.getLogger(logger_name)
|
||||
logger.propagate, old_propagate = False, logger.propagate
|
||||
if logger.propagate:
|
||||
logger.propagate = False
|
||||
logger.addHandler(caplog.handler)
|
||||
try:
|
||||
yield caplog
|
||||
finally:
|
||||
logger.removeHandler(caplog.handler)
|
||||
logger.propagate = old_propagate
|
||||
|
||||
|
||||
async def app(scope: Scope, receive: ASGIReceiveCallable, send: ASGISendCallable):
|
||||
async def app(scope, receive, send):
|
||||
assert scope["type"] == "http"
|
||||
await send({"type": "http.response.start", "status": 204, "headers": []})
|
||||
await send({"type": "http.response.body", "body": b"", "more_body": False})
|
||||
|
||||
|
||||
async def test_trace_logging(caplog: pytest.LogCaptureFixture, logging_config: dict[str, Any], unused_tcp_port: int):
|
||||
@pytest.mark.skipif(
|
||||
sys.platform.startswith("win") or platform.python_implementation() == "PyPy",
|
||||
reason="Skipping test on Windows and PyPy",
|
||||
)
|
||||
def test_trace_logging(caplog):
|
||||
config = Config(
|
||||
app=app,
|
||||
loop="asyncio",
|
||||
limit_max_requests=1,
|
||||
log_level="trace",
|
||||
log_config=logging_config,
|
||||
lifespan="auto",
|
||||
port=unused_tcp_port,
|
||||
)
|
||||
with caplog_for_logger(caplog, "uvicorn.asgi"):
|
||||
async with run_server(config):
|
||||
async with httpx.AsyncClient() as client:
|
||||
response = await client.get(f"http://127.0.0.1:{unused_tcp_port}")
|
||||
server = Server(config=config)
|
||||
thread = threading.Thread(target=server.run)
|
||||
thread.start()
|
||||
while not server.started:
|
||||
time.sleep(0.01)
|
||||
response = requests.get("http://127.0.0.1:8000")
|
||||
assert response.status_code == 204
|
||||
messages = [record.message for record in caplog.records if record.name == "uvicorn.asgi"]
|
||||
thread.join()
|
||||
messages = [
|
||||
record.message for record in caplog.records if record.name == "uvicorn.asgi"
|
||||
]
|
||||
assert "ASGI [1] Started scope=" in messages.pop(0)
|
||||
assert "ASGI [1] Raised exception" in messages.pop(0)
|
||||
assert "ASGI [2] Started scope=" in messages.pop(0)
|
||||
@ -67,143 +60,66 @@ async def test_trace_logging(caplog: pytest.LogCaptureFixture, logging_config: d
|
||||
assert "ASGI [2] Completed" in messages.pop(0)
|
||||
|
||||
|
||||
async def test_trace_logging_on_http_protocol(http_protocol_cls, caplog, logging_config, unused_tcp_port: int):
|
||||
@pytest.mark.skipif(
|
||||
sys.platform.startswith("win") or platform.python_implementation() == "PyPy",
|
||||
reason="Skipping test on Windows and PyPy",
|
||||
)
|
||||
@pytest.mark.parametrize("http_protocol", [("h11"), ("httptools")])
|
||||
def test_access_logging(caplog, http_protocol):
|
||||
config = Config(
|
||||
app=app,
|
||||
log_level="trace",
|
||||
http=http_protocol_cls,
|
||||
log_config=logging_config,
|
||||
port=unused_tcp_port,
|
||||
loop="asyncio",
|
||||
http=http_protocol,
|
||||
limit_max_requests=1,
|
||||
)
|
||||
with caplog_for_logger(caplog, "uvicorn.error"):
|
||||
async with run_server(config):
|
||||
async with httpx.AsyncClient() as client:
|
||||
response = await client.get(f"http://127.0.0.1:{unused_tcp_port}")
|
||||
assert response.status_code == 204
|
||||
messages = [record.message for record in caplog.records if record.name == "uvicorn.error"]
|
||||
assert any(" - HTTP connection made" in message for message in messages)
|
||||
assert any(" - HTTP connection lost" in message for message in messages)
|
||||
|
||||
|
||||
async def test_trace_logging_on_ws_protocol(
|
||||
ws_protocol_cls: WSProtocol,
|
||||
caplog: pytest.LogCaptureFixture,
|
||||
logging_config: dict[str, Any],
|
||||
unused_tcp_port: int,
|
||||
):
|
||||
async def websocket_app(scope: Scope, receive: ASGIReceiveCallable, send: ASGISendCallable):
|
||||
assert scope["type"] == "websocket"
|
||||
while True:
|
||||
message = await receive()
|
||||
if message["type"] == "websocket.connect":
|
||||
await send({"type": "websocket.accept"})
|
||||
elif message["type"] == "websocket.disconnect":
|
||||
break
|
||||
|
||||
async def open_connection(url: str):
|
||||
async with websockets.client.connect(url) as websocket:
|
||||
return websocket.state is State.OPEN
|
||||
|
||||
config = Config(
|
||||
app=websocket_app,
|
||||
log_level="trace",
|
||||
log_config=logging_config,
|
||||
ws=ws_protocol_cls,
|
||||
port=unused_tcp_port,
|
||||
)
|
||||
with caplog_for_logger(caplog, "uvicorn.error"):
|
||||
async with run_server(config):
|
||||
is_open = await open_connection(f"ws://127.0.0.1:{unused_tcp_port}")
|
||||
assert is_open
|
||||
messages = [record.message for record in caplog.records if record.name == "uvicorn.error"]
|
||||
assert any(" - Upgrading to WebSocket" in message for message in messages)
|
||||
assert any(" - WebSocket connection made" in message for message in messages)
|
||||
assert any(" - WebSocket connection lost" in message for message in messages)
|
||||
|
||||
|
||||
@pytest.mark.parametrize("use_colors", [(True), (False), (None)])
|
||||
async def test_access_logging(
|
||||
use_colors: bool, caplog: pytest.LogCaptureFixture, logging_config: dict[str, Any], unused_tcp_port: int
|
||||
):
|
||||
config = Config(app=app, use_colors=use_colors, log_config=logging_config, port=unused_tcp_port)
|
||||
with caplog_for_logger(caplog, "uvicorn.access"):
|
||||
async with run_server(config):
|
||||
async with httpx.AsyncClient() as client:
|
||||
response = await client.get(f"http://127.0.0.1:{unused_tcp_port}")
|
||||
|
||||
server = Server(config=config)
|
||||
thread = threading.Thread(target=server.run)
|
||||
thread.start()
|
||||
while not server.started:
|
||||
time.sleep(0.01)
|
||||
response = requests.get("http://127.0.0.1:8000")
|
||||
assert response.status_code == 204
|
||||
messages = [record.message for record in caplog.records if record.name == "uvicorn.access"]
|
||||
thread.join()
|
||||
messages = [
|
||||
record.message
|
||||
for record in caplog.records
|
||||
if record.name == "uvicorn.access"
|
||||
]
|
||||
assert '"GET / HTTP/1.1" 204' in messages.pop()
|
||||
|
||||
|
||||
@pytest.mark.parametrize("use_colors", [(True), (False)])
|
||||
async def test_default_logging(
|
||||
use_colors: bool, caplog: pytest.LogCaptureFixture, logging_config: dict[str, Any], unused_tcp_port: int
|
||||
):
|
||||
config = Config(app=app, use_colors=use_colors, log_config=logging_config, port=unused_tcp_port)
|
||||
@pytest.mark.skipif(
|
||||
sys.platform.startswith("win") or platform.python_implementation() == "PyPy",
|
||||
reason="Skipping test on Windows and PyPy",
|
||||
)
|
||||
@pytest.mark.parametrize("http_protocol", ["h11", "httptools"])
|
||||
def test_default_logging(caplog, http_protocol):
|
||||
config = Config(
|
||||
app=app,
|
||||
loop="asyncio",
|
||||
http=http_protocol,
|
||||
limit_max_requests=1,
|
||||
)
|
||||
|
||||
with caplog_for_logger(caplog, "uvicorn.access"):
|
||||
async with run_server(config):
|
||||
async with httpx.AsyncClient() as client:
|
||||
response = await client.get(f"http://127.0.0.1:{unused_tcp_port}")
|
||||
server = Server(config=config)
|
||||
thread = threading.Thread(target=server.run)
|
||||
thread.start()
|
||||
while not server.started:
|
||||
time.sleep(0.01)
|
||||
response = requests.get("http://127.0.0.1:8000")
|
||||
assert response.status_code == 204
|
||||
messages = [record.message for record in caplog.records if "uvicorn" in record.name]
|
||||
thread.join()
|
||||
|
||||
messages = [
|
||||
record.message for record in caplog.records if "uvicorn" in record.name
|
||||
]
|
||||
assert "Started server process" in messages.pop(0)
|
||||
assert "Waiting for application startup" in messages.pop(0)
|
||||
assert "ASGI 'lifespan' protocol appears unsupported" in messages.pop(0)
|
||||
assert "Application startup complete" in messages.pop(0)
|
||||
assert "Uvicorn running on http://127.0.0.1" in messages.pop(0)
|
||||
assert "Uvicorn running on http://127.0.0.1:8000" in messages.pop(0)
|
||||
assert '"GET / HTTP/1.1" 204' in messages.pop(0)
|
||||
assert "Shutting down" in messages.pop(0)
|
||||
|
||||
|
||||
@pytest.mark.skipif(sys.platform == "win32", reason="require unix-like system")
|
||||
async def test_running_log_using_uds(
|
||||
caplog: pytest.LogCaptureFixture, short_socket_name: str, unused_tcp_port: int
|
||||
): # pragma: py-win32
|
||||
config = Config(app=app, uds=short_socket_name, port=unused_tcp_port)
|
||||
with caplog_for_logger(caplog, "uvicorn.access"):
|
||||
async with run_server(config):
|
||||
...
|
||||
|
||||
messages = [record.message for record in caplog.records if "uvicorn" in record.name]
|
||||
assert f"Uvicorn running on unix socket {short_socket_name} (Press CTRL+C to quit)" in messages
|
||||
|
||||
|
||||
@pytest.mark.skipif(sys.platform == "win32", reason="require unix-like system")
|
||||
async def test_running_log_using_fd(caplog: pytest.LogCaptureFixture, unused_tcp_port: int): # pragma: py-win32
|
||||
with contextlib.closing(socket.socket(socket.AF_INET, socket.SOCK_STREAM)) as sock:
|
||||
fd = sock.fileno()
|
||||
config = Config(app=app, fd=fd, port=unused_tcp_port)
|
||||
with caplog_for_logger(caplog, "uvicorn.access"):
|
||||
async with run_server(config):
|
||||
...
|
||||
sockname = sock.getsockname()
|
||||
messages = [record.message for record in caplog.records if "uvicorn" in record.name]
|
||||
assert f"Uvicorn running on socket {sockname} (Press CTRL+C to quit)" in messages
|
||||
|
||||
|
||||
async def test_unknown_status_code(caplog: pytest.LogCaptureFixture, unused_tcp_port: int):
|
||||
async def app(scope: Scope, receive: ASGIReceiveCallable, send: ASGISendCallable):
|
||||
assert scope["type"] == "http"
|
||||
await send({"type": "http.response.start", "status": 599, "headers": []})
|
||||
await send({"type": "http.response.body", "body": b"", "more_body": False})
|
||||
|
||||
config = Config(app=app, port=unused_tcp_port)
|
||||
with caplog_for_logger(caplog, "uvicorn.access"):
|
||||
async with run_server(config):
|
||||
async with httpx.AsyncClient() as client:
|
||||
response = await client.get(f"http://127.0.0.1:{unused_tcp_port}")
|
||||
|
||||
assert response.status_code == 599
|
||||
messages = [record.message for record in caplog.records if record.name == "uvicorn.access"]
|
||||
assert '"GET / HTTP/1.1" 599' in messages.pop()
|
||||
|
||||
|
||||
async def test_server_start_with_port_zero(caplog: pytest.LogCaptureFixture):
|
||||
config = Config(app=app, port=0)
|
||||
async with run_server(config) as _server:
|
||||
server = _server.servers[0]
|
||||
sock = server.sockets[0]
|
||||
host, port = sock.getsockname()
|
||||
messages = [record.message for record in caplog.records if "uvicorn" in record.name]
|
||||
assert f"Uvicorn running on http://{host}:{port} (Press CTRL+C to quit)" in messages
|
||||
assert "Finished server process" in messages.pop(0)
|
||||
|
||||
@ -1,50 +1,45 @@
|
||||
import httpx
|
||||
import pytest
|
||||
|
||||
from tests.middleware.test_logging import caplog_for_logger
|
||||
from uvicorn._types import ASGIReceiveCallable, ASGISendCallable, Scope
|
||||
from uvicorn.logging import TRACE_LOG_LEVEL
|
||||
from tests.client import TestClient
|
||||
from uvicorn.middleware.message_logger import MessageLoggerMiddleware
|
||||
|
||||
TRACE_LOG_LEVEL = 5
|
||||
|
||||
@pytest.mark.anyio
|
||||
async def test_message_logger(caplog: pytest.LogCaptureFixture) -> None:
|
||||
async def app(scope: Scope, receive: ASGIReceiveCallable, send: ASGISendCallable) -> None:
|
||||
|
||||
def test_message_logger(caplog):
|
||||
async def app(scope, receive, send):
|
||||
await receive()
|
||||
await send({"type": "http.response.start", "status": 200, "headers": []})
|
||||
await send({"type": "http.response.body", "body": b"", "more_body": False})
|
||||
|
||||
with caplog_for_logger(caplog, "uvicorn.asgi"):
|
||||
caplog.set_level(TRACE_LOG_LEVEL, logger="uvicorn.asgi")
|
||||
caplog.set_level(TRACE_LOG_LEVEL)
|
||||
caplog.set_level(TRACE_LOG_LEVEL, logger="uvicorn.asgi")
|
||||
caplog.set_level(TRACE_LOG_LEVEL)
|
||||
|
||||
transport = httpx.ASGITransport(MessageLoggerMiddleware(app)) # type: ignore
|
||||
async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as client:
|
||||
response = await client.get("/")
|
||||
assert response.status_code == 200
|
||||
messages = [record.msg % record.args for record in caplog.records]
|
||||
assert sum(["ASGI [1] Started" in message for message in messages]) == 1
|
||||
assert sum(["ASGI [1] Send" in message for message in messages]) == 2
|
||||
assert sum(["ASGI [1] Receive" in message for message in messages]) == 1
|
||||
assert sum(["ASGI [1] Completed" in message for message in messages]) == 1
|
||||
assert sum(["ASGI [1] Raised exception" in message for message in messages]) == 0
|
||||
app = MessageLoggerMiddleware(app)
|
||||
client = TestClient(app)
|
||||
response = client.get("/")
|
||||
assert response.status_code == 200
|
||||
messages = [record.msg % record.args for record in caplog.records]
|
||||
assert sum(["ASGI [1] Started" in message for message in messages]) == 1
|
||||
assert sum(["ASGI [1] Send" in message for message in messages]) == 2
|
||||
assert sum(["ASGI [1] Receive" in message for message in messages]) == 1
|
||||
assert sum(["ASGI [1] Completed" in message for message in messages]) == 1
|
||||
assert sum(["ASGI [1] Raised exception" in message for message in messages]) == 0
|
||||
|
||||
|
||||
@pytest.mark.anyio
|
||||
async def test_message_logger_exc(caplog: pytest.LogCaptureFixture) -> None:
|
||||
async def app(scope: Scope, receive: ASGIReceiveCallable, send: ASGISendCallable) -> None:
|
||||
def test_message_logger_exc(caplog):
|
||||
async def app(scope, receive, send):
|
||||
raise RuntimeError()
|
||||
|
||||
with caplog_for_logger(caplog, "uvicorn.asgi"):
|
||||
caplog.set_level(TRACE_LOG_LEVEL, logger="uvicorn.asgi")
|
||||
caplog.set_level(TRACE_LOG_LEVEL)
|
||||
transport = httpx.ASGITransport(MessageLoggerMiddleware(app)) # type: ignore
|
||||
async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as client:
|
||||
with pytest.raises(RuntimeError):
|
||||
await client.get("/")
|
||||
messages = [record.msg % record.args for record in caplog.records]
|
||||
assert sum(["ASGI [1] Started" in message for message in messages]) == 1
|
||||
assert sum(["ASGI [1] Send" in message for message in messages]) == 0
|
||||
assert sum(["ASGI [1] Receive" in message for message in messages]) == 0
|
||||
assert sum(["ASGI [1] Completed" in message for message in messages]) == 0
|
||||
assert sum(["ASGI [1] Raised exception" in message for message in messages]) == 1
|
||||
caplog.set_level(TRACE_LOG_LEVEL, logger="uvicorn.asgi")
|
||||
caplog.set_level(TRACE_LOG_LEVEL)
|
||||
app = MessageLoggerMiddleware(app)
|
||||
client = TestClient(app)
|
||||
with pytest.raises(RuntimeError):
|
||||
client.get("/")
|
||||
messages = [record.msg % record.args for record in caplog.records]
|
||||
assert sum(["ASGI [1] Started" in message for message in messages]) == 1
|
||||
assert sum(["ASGI [1] Send" in message for message in messages]) == 0
|
||||
assert sum(["ASGI [1] Receive" in message for message in messages]) == 0
|
||||
assert sum(["ASGI [1] Completed" in message for message in messages]) == 0
|
||||
assert sum(["ASGI [1] Raised exception" in message for message in messages]) == 1
|
||||
|
||||
@ -1,556 +1,41 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import contextlib
|
||||
import ipaddress
|
||||
from typing import TYPE_CHECKING
|
||||
|
||||
import httpx
|
||||
import pytest
|
||||
import websockets.client
|
||||
|
||||
from tests.client import TestClient
|
||||
from tests.response import Response
|
||||
from tests.utils import run_server
|
||||
from uvicorn._types import ASGIReceiveCallable, ASGISendCallable, Scope
|
||||
from uvicorn.config import Config
|
||||
from uvicorn.middleware.proxy_headers import ProxyHeadersMiddleware, _TrustedHosts
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from uvicorn.protocols.http.h11_impl import H11Protocol
|
||||
from uvicorn.protocols.http.httptools_impl import HttpToolsProtocol
|
||||
from uvicorn.protocols.websockets.websockets_impl import WebSocketProtocol
|
||||
from uvicorn.protocols.websockets.wsproto_impl import WSProtocol
|
||||
from uvicorn.middleware.proxy_headers import ProxyHeadersMiddleware
|
||||
|
||||
|
||||
X_FORWARDED_FOR = "X-Forwarded-For"
|
||||
X_FORWARDED_PROTO = "X-Forwarded-Proto"
|
||||
|
||||
|
||||
async def default_app(scope: Scope, receive: ASGIReceiveCallable, send: ASGISendCallable) -> None:
|
||||
scheme = scope["scheme"] # type: ignore
|
||||
if (client := scope["client"]) is None: # type: ignore
|
||||
client_addr = "NONE" # pragma: no cover
|
||||
else:
|
||||
host, port = client
|
||||
with contextlib.suppress(ValueError):
|
||||
if ipaddress.ip_address(host).version == 6:
|
||||
host = f"[{host}]"
|
||||
client_addr = f"{host}:{port}"
|
||||
|
||||
response = Response(f"{scheme}://{client_addr}", media_type="text/plain")
|
||||
async def app(scope, receive, send):
|
||||
scheme = scope["scheme"]
|
||||
host, port = scope["client"]
|
||||
addr = "%s://%s:%d" % (scheme, host, port)
|
||||
response = Response("Remote: " + addr, media_type="text/plain")
|
||||
await response(scope, receive, send)
|
||||
|
||||
|
||||
def make_httpx_client(
|
||||
trusted_hosts: str | list[str],
|
||||
client: tuple[str, int] = ("127.0.0.1", 123),
|
||||
) -> httpx.AsyncClient:
|
||||
"""Create async client for use in test cases.
|
||||
|
||||
Args:
|
||||
trusted_hosts: trusted_hosts for proxy middleware
|
||||
client: transport client to use
|
||||
"""
|
||||
|
||||
app = ProxyHeadersMiddleware(default_app, trusted_hosts)
|
||||
transport = httpx.ASGITransport(app=app, client=client) # type: ignore
|
||||
return httpx.AsyncClient(transport=transport, base_url="http://testserver")
|
||||
app = ProxyHeadersMiddleware(app, trusted_hosts="*")
|
||||
|
||||
|
||||
# Note: we vary the format here to also test some of the functionality
|
||||
# of the _TrustedHosts.__init__ method.
|
||||
_TRUSTED_NOTHING: list[str] = []
|
||||
_TRUSTED_EVERYTHING = "*"
|
||||
_TRUSTED_EVERYTHING_LIST = ["*"]
|
||||
_TRUSTED_IPv4_ADDRESSES = "127.0.0.1, 10.0.0.1"
|
||||
_TRUSTED_IPv4_NETWORKS = ["127.0.0.0/8", "10.0.0.0/8"]
|
||||
_TRUSTED_IPv6_ADDRESSES = [
|
||||
"2001:db8::",
|
||||
"2001:0db8:0001:0000:0000:0ab9:C0A8:0102",
|
||||
"2001:db8:3333:4444:5555:6666:1.2.3.4", # This is a dual address
|
||||
"::11.22.33.44", # This is a dual address
|
||||
]
|
||||
_TRUSTED_IPv6_NETWORKS = "2001:db8:abcd:0012::0/64"
|
||||
_TRUSTED_LITERALS = "some-literal , unix:///foo/bar , /foo/bar, garba*gewith*"
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
("init_hosts", "test_host", "expected"),
|
||||
[
|
||||
## Never Trust trust
|
||||
## -----------------------------
|
||||
# Test IPv4 Addresses
|
||||
(_TRUSTED_NOTHING, "127.0.0.0", False),
|
||||
(_TRUSTED_NOTHING, "127.0.0.1", False),
|
||||
(_TRUSTED_NOTHING, "127.1.1.1", False),
|
||||
(_TRUSTED_NOTHING, "127.255.255.255", False),
|
||||
(_TRUSTED_NOTHING, "10.0.0.0", False),
|
||||
(_TRUSTED_NOTHING, "10.0.0.1", False),
|
||||
(_TRUSTED_NOTHING, "10.1.1.1", False),
|
||||
(_TRUSTED_NOTHING, "10.255.255.255", False),
|
||||
(_TRUSTED_NOTHING, "192.168.0.0", False),
|
||||
(_TRUSTED_NOTHING, "192.168.0.1", False),
|
||||
(_TRUSTED_NOTHING, "1.1.1.1", False),
|
||||
# Test IPv6 Addresses
|
||||
(_TRUSTED_NOTHING, "2001:db8::", False),
|
||||
(_TRUSTED_NOTHING, "2001:db8:abcd:0012::0", False),
|
||||
(_TRUSTED_NOTHING, "2001:db8:abcd:0012::1:1", False),
|
||||
(_TRUSTED_NOTHING, "::", False),
|
||||
(_TRUSTED_NOTHING, "::1", False),
|
||||
(
|
||||
_TRUSTED_NOTHING,
|
||||
"2001:db8:3333:4444:5555:6666:102:304",
|
||||
False,
|
||||
), # aka 2001:db8:3333:4444:5555:6666:1.2.3.4
|
||||
(_TRUSTED_NOTHING, "::b16:212c", False), # aka ::11.22.33.44
|
||||
(_TRUSTED_NOTHING, "a:b:c:d::", False),
|
||||
(_TRUSTED_NOTHING, "::a:b:c:d", False),
|
||||
# Test Literals
|
||||
(_TRUSTED_NOTHING, "some-literal", False),
|
||||
(_TRUSTED_NOTHING, "unix:///foo/bar", False),
|
||||
(_TRUSTED_NOTHING, "/foo/bar", False),
|
||||
(_TRUSTED_NOTHING, "*", False),
|
||||
(_TRUSTED_NOTHING, "another-literal", False),
|
||||
(_TRUSTED_NOTHING, "unix:///another/path", False),
|
||||
(_TRUSTED_NOTHING, "/another/path", False),
|
||||
(_TRUSTED_NOTHING, "", False),
|
||||
## Always trust
|
||||
## -----------------------------
|
||||
# Test IPv4 Addresses
|
||||
(_TRUSTED_EVERYTHING, "127.0.0.0", True),
|
||||
(_TRUSTED_EVERYTHING, "127.0.0.1", True),
|
||||
(_TRUSTED_EVERYTHING, "127.1.1.1", True),
|
||||
(_TRUSTED_EVERYTHING, "127.255.255.255", True),
|
||||
(_TRUSTED_EVERYTHING, "10.0.0.0", True),
|
||||
(_TRUSTED_EVERYTHING, "10.0.0.1", True),
|
||||
(_TRUSTED_EVERYTHING, "10.1.1.1", True),
|
||||
(_TRUSTED_EVERYTHING, "10.255.255.255", True),
|
||||
(_TRUSTED_EVERYTHING, "192.168.0.0", True),
|
||||
(_TRUSTED_EVERYTHING, "192.168.0.1", True),
|
||||
(_TRUSTED_EVERYTHING, "1.1.1.1", True),
|
||||
(_TRUSTED_EVERYTHING_LIST, "1.1.1.1", True),
|
||||
# Test IPv6 Addresses
|
||||
(_TRUSTED_EVERYTHING, "2001:db8::", True),
|
||||
(_TRUSTED_EVERYTHING, "2001:db8:abcd:0012::0", True),
|
||||
(_TRUSTED_EVERYTHING, "2001:db8:abcd:0012::1:1", True),
|
||||
(_TRUSTED_EVERYTHING, "::", True),
|
||||
(_TRUSTED_EVERYTHING, "::1", True),
|
||||
(
|
||||
_TRUSTED_EVERYTHING,
|
||||
"2001:db8:3333:4444:5555:6666:102:304",
|
||||
True,
|
||||
), # aka 2001:db8:3333:4444:5555:6666:1.2.3.4
|
||||
(_TRUSTED_EVERYTHING, "::b16:212c", True), # aka ::11.22.33.44
|
||||
(_TRUSTED_EVERYTHING, "a:b:c:d::", True),
|
||||
(_TRUSTED_EVERYTHING, "::a:b:c:d", True),
|
||||
(_TRUSTED_EVERYTHING_LIST, "::a:b:c:d", True),
|
||||
# Test Literals
|
||||
(_TRUSTED_EVERYTHING, "some-literal", True),
|
||||
(_TRUSTED_EVERYTHING, "unix:///foo/bar", True),
|
||||
(_TRUSTED_EVERYTHING, "/foo/bar", True),
|
||||
(_TRUSTED_EVERYTHING, "*", True),
|
||||
(_TRUSTED_EVERYTHING, "another-literal", True),
|
||||
(_TRUSTED_EVERYTHING, "unix:///another/path", True),
|
||||
(_TRUSTED_EVERYTHING, "/another/path", True),
|
||||
(_TRUSTED_EVERYTHING, "", True),
|
||||
(_TRUSTED_EVERYTHING_LIST, "", True),
|
||||
## Trust IPv4 Addresses
|
||||
## -----------------------------
|
||||
# Test IPv4 Addresses
|
||||
(_TRUSTED_IPv4_ADDRESSES, "127.0.0.0", False),
|
||||
(_TRUSTED_IPv4_ADDRESSES, "127.0.0.1", True),
|
||||
(_TRUSTED_IPv4_ADDRESSES, "127.1.1.1", False),
|
||||
(_TRUSTED_IPv4_ADDRESSES, "127.255.255.255", False),
|
||||
(_TRUSTED_IPv4_ADDRESSES, "10.0.0.0", False),
|
||||
(_TRUSTED_IPv4_ADDRESSES, "10.0.0.1", True),
|
||||
(_TRUSTED_IPv4_ADDRESSES, "10.1.1.1", False),
|
||||
(_TRUSTED_IPv4_ADDRESSES, "10.255.255.255", False),
|
||||
(_TRUSTED_IPv4_ADDRESSES, "192.168.0.0", False),
|
||||
(_TRUSTED_IPv4_ADDRESSES, "192.168.0.1", False),
|
||||
(_TRUSTED_IPv4_ADDRESSES, "1.1.1.1", False),
|
||||
# Test IPv6 Addresses
|
||||
(_TRUSTED_IPv4_ADDRESSES, "2001:db8::", False),
|
||||
(_TRUSTED_IPv4_ADDRESSES, "2001:db8:abcd:0012::0", False),
|
||||
(_TRUSTED_IPv4_ADDRESSES, "2001:db8:abcd:0012::1:1", False),
|
||||
(_TRUSTED_IPv4_ADDRESSES, "::", False),
|
||||
(_TRUSTED_IPv4_ADDRESSES, "::1", False),
|
||||
(
|
||||
_TRUSTED_IPv4_ADDRESSES,
|
||||
"2001:db8:3333:4444:5555:6666:102:304",
|
||||
False,
|
||||
), # aka 2001:db8:3333:4444:5555:6666:1.2.3.4
|
||||
(_TRUSTED_IPv4_ADDRESSES, "::b16:212c", False), # aka ::11.22.33.44
|
||||
(_TRUSTED_IPv4_ADDRESSES, "a:b:c:d::", False),
|
||||
(_TRUSTED_IPv4_ADDRESSES, "::a:b:c:d", False),
|
||||
# Test Literals
|
||||
(_TRUSTED_IPv4_ADDRESSES, "some-literal", False),
|
||||
(_TRUSTED_IPv4_ADDRESSES, "unix:///foo/bar", False),
|
||||
(_TRUSTED_IPv4_ADDRESSES, "*", False),
|
||||
(_TRUSTED_IPv4_ADDRESSES, "/foo/bar", False),
|
||||
(_TRUSTED_IPv4_ADDRESSES, "another-literal", False),
|
||||
(_TRUSTED_IPv4_ADDRESSES, "unix:///another/path", False),
|
||||
(_TRUSTED_IPv4_ADDRESSES, "/another/path", False),
|
||||
(_TRUSTED_IPv4_ADDRESSES, "", False),
|
||||
## Trust IPv6 Addresses
|
||||
## -----------------------------
|
||||
# Test IPv4 Addresses
|
||||
(_TRUSTED_IPv6_ADDRESSES, "127.0.0.0", False),
|
||||
(_TRUSTED_IPv6_ADDRESSES, "127.0.0.1", False),
|
||||
(_TRUSTED_IPv6_ADDRESSES, "127.1.1.1", False),
|
||||
(_TRUSTED_IPv6_ADDRESSES, "127.255.255.255", False),
|
||||
(_TRUSTED_IPv6_ADDRESSES, "10.0.0.0", False),
|
||||
(_TRUSTED_IPv6_ADDRESSES, "10.0.0.1", False),
|
||||
(_TRUSTED_IPv6_ADDRESSES, "10.1.1.1", False),
|
||||
(_TRUSTED_IPv6_ADDRESSES, "10.255.255.255", False),
|
||||
(_TRUSTED_IPv6_ADDRESSES, "192.168.0.0", False),
|
||||
(_TRUSTED_IPv6_ADDRESSES, "192.168.0.1", False),
|
||||
(_TRUSTED_IPv6_ADDRESSES, "1.1.1.1", False),
|
||||
# Test IPv6 Addresses
|
||||
(_TRUSTED_IPv6_ADDRESSES, "2001:db8::", True),
|
||||
(_TRUSTED_IPv6_ADDRESSES, "2001:db8:abcd:0012::0", False),
|
||||
(_TRUSTED_IPv6_ADDRESSES, "2001:db8:abcd:0012::1:1", False),
|
||||
(_TRUSTED_IPv6_ADDRESSES, "::", False),
|
||||
(_TRUSTED_IPv6_ADDRESSES, "::1", False),
|
||||
(
|
||||
_TRUSTED_IPv6_ADDRESSES,
|
||||
"2001:db8:3333:4444:5555:6666:102:304",
|
||||
True,
|
||||
), # aka 2001:db8:3333:4444:5555:6666:1.2.3.4
|
||||
(_TRUSTED_IPv6_ADDRESSES, "::b16:212c", True), # aka ::11.22.33.44
|
||||
(_TRUSTED_IPv6_ADDRESSES, "a:b:c:d::", False),
|
||||
(_TRUSTED_IPv6_ADDRESSES, "::a:b:c:d", False),
|
||||
# Test Literals
|
||||
(_TRUSTED_IPv6_ADDRESSES, "some-literal", False),
|
||||
(_TRUSTED_IPv6_ADDRESSES, "unix:///foo/bar", False),
|
||||
(_TRUSTED_IPv6_ADDRESSES, "*", False),
|
||||
(_TRUSTED_IPv6_ADDRESSES, "/foo/bar", False),
|
||||
(_TRUSTED_IPv6_ADDRESSES, "another-literal", False),
|
||||
(_TRUSTED_IPv6_ADDRESSES, "unix:///another/path", False),
|
||||
(_TRUSTED_IPv6_ADDRESSES, "/another/path", False),
|
||||
(_TRUSTED_IPv6_ADDRESSES, "", False),
|
||||
## Trust IPv4 Networks
|
||||
## -----------------------------
|
||||
# Test IPv4 Addresses
|
||||
(_TRUSTED_IPv4_NETWORKS, "127.0.0.0", True),
|
||||
(_TRUSTED_IPv4_NETWORKS, "127.0.0.1", True),
|
||||
(_TRUSTED_IPv4_NETWORKS, "127.1.1.1", True),
|
||||
(_TRUSTED_IPv4_NETWORKS, "127.255.255.255", True),
|
||||
(_TRUSTED_IPv4_NETWORKS, "10.0.0.0", True),
|
||||
(_TRUSTED_IPv4_NETWORKS, "10.0.0.1", True),
|
||||
(_TRUSTED_IPv4_NETWORKS, "10.1.1.1", True),
|
||||
(_TRUSTED_IPv4_NETWORKS, "10.255.255.255", True),
|
||||
(_TRUSTED_IPv4_NETWORKS, "192.168.0.0", False),
|
||||
(_TRUSTED_IPv4_NETWORKS, "192.168.0.1", False),
|
||||
(_TRUSTED_IPv4_NETWORKS, "1.1.1.1", False),
|
||||
# Test IPv6 Addresses
|
||||
(_TRUSTED_IPv4_NETWORKS, "2001:db8::", False),
|
||||
(_TRUSTED_IPv4_NETWORKS, "2001:db8:abcd:0012::0", False),
|
||||
(_TRUSTED_IPv4_NETWORKS, "2001:db8:abcd:0012::1:1", False),
|
||||
(_TRUSTED_IPv4_NETWORKS, "::", False),
|
||||
(_TRUSTED_IPv4_NETWORKS, "::1", False),
|
||||
(
|
||||
_TRUSTED_IPv4_NETWORKS,
|
||||
"2001:db8:3333:4444:5555:6666:102:304",
|
||||
False,
|
||||
), # aka 2001:db8:3333:4444:5555:6666:1.2.3.4
|
||||
(_TRUSTED_IPv4_NETWORKS, "::b16:212c", False), # aka ::11.22.33.44
|
||||
(_TRUSTED_IPv4_NETWORKS, "a:b:c:d::", False),
|
||||
(_TRUSTED_IPv4_NETWORKS, "::a:b:c:d", False),
|
||||
# Test Literals
|
||||
(_TRUSTED_IPv4_NETWORKS, "some-literal", False),
|
||||
(_TRUSTED_IPv4_NETWORKS, "unix:///foo/bar", False),
|
||||
(_TRUSTED_IPv4_NETWORKS, "*", False),
|
||||
(_TRUSTED_IPv4_NETWORKS, "/foo/bar", False),
|
||||
(_TRUSTED_IPv4_NETWORKS, "another-literal", False),
|
||||
(_TRUSTED_IPv4_NETWORKS, "unix:///another/path", False),
|
||||
(_TRUSTED_IPv4_NETWORKS, "/another/path", False),
|
||||
(_TRUSTED_IPv4_NETWORKS, "", False),
|
||||
## Trust IPv6 Networks
|
||||
## -----------------------------
|
||||
# Test IPv4 Addresses
|
||||
(_TRUSTED_IPv6_NETWORKS, "127.0.0.0", False),
|
||||
(_TRUSTED_IPv6_NETWORKS, "127.0.0.1", False),
|
||||
(_TRUSTED_IPv6_NETWORKS, "127.1.1.1", False),
|
||||
(_TRUSTED_IPv6_NETWORKS, "127.255.255.255", False),
|
||||
(_TRUSTED_IPv6_NETWORKS, "10.0.0.0", False),
|
||||
(_TRUSTED_IPv6_NETWORKS, "10.0.0.1", False),
|
||||
(_TRUSTED_IPv6_NETWORKS, "10.1.1.1", False),
|
||||
(_TRUSTED_IPv6_NETWORKS, "10.255.255.255", False),
|
||||
(_TRUSTED_IPv6_NETWORKS, "192.168.0.0", False),
|
||||
(_TRUSTED_IPv6_NETWORKS, "192.168.0.1", False),
|
||||
(_TRUSTED_IPv6_NETWORKS, "1.1.1.1", False),
|
||||
# Test IPv6 Addresses
|
||||
(_TRUSTED_IPv6_NETWORKS, "2001:db8::", False),
|
||||
(_TRUSTED_IPv6_NETWORKS, "2001:db8:abcd:0012::0", True),
|
||||
(_TRUSTED_IPv6_NETWORKS, "2001:db8:abcd:0012::1:1", True),
|
||||
(_TRUSTED_IPv6_NETWORKS, "::", False),
|
||||
(_TRUSTED_IPv6_NETWORKS, "::1", False),
|
||||
(
|
||||
_TRUSTED_IPv6_NETWORKS,
|
||||
"2001:db8:3333:4444:5555:6666:102:304",
|
||||
False,
|
||||
), # aka 2001:db8:3333:4444:5555:6666:1.2.3.4
|
||||
(_TRUSTED_IPv6_NETWORKS, "::b16:212c", False), # aka ::11.22.33.44
|
||||
(_TRUSTED_IPv6_NETWORKS, "a:b:c:d::", False),
|
||||
(_TRUSTED_IPv6_NETWORKS, "::a:b:c:d", False),
|
||||
# Test Literals
|
||||
(_TRUSTED_IPv6_NETWORKS, "some-literal", False),
|
||||
(_TRUSTED_IPv6_NETWORKS, "unix:///foo/bar", False),
|
||||
(_TRUSTED_IPv6_NETWORKS, "*", False),
|
||||
(_TRUSTED_IPv6_NETWORKS, "/foo/bar", False),
|
||||
(_TRUSTED_IPv6_NETWORKS, "another-literal", False),
|
||||
(_TRUSTED_IPv6_NETWORKS, "unix:///another/path", False),
|
||||
(_TRUSTED_IPv6_NETWORKS, "/another/path", False),
|
||||
(_TRUSTED_IPv6_NETWORKS, "", False),
|
||||
## Trust Literals
|
||||
## -----------------------------
|
||||
# Test IPv4 Addresses
|
||||
(_TRUSTED_LITERALS, "127.0.0.0", False),
|
||||
(_TRUSTED_LITERALS, "127.0.0.1", False),
|
||||
(_TRUSTED_LITERALS, "127.1.1.1", False),
|
||||
(_TRUSTED_LITERALS, "127.255.255.255", False),
|
||||
(_TRUSTED_LITERALS, "10.0.0.0", False),
|
||||
(_TRUSTED_LITERALS, "10.0.0.1", False),
|
||||
(_TRUSTED_LITERALS, "10.1.1.1", False),
|
||||
(_TRUSTED_LITERALS, "10.255.255.255", False),
|
||||
(_TRUSTED_LITERALS, "192.168.0.0", False),
|
||||
(_TRUSTED_LITERALS, "192.168.0.1", False),
|
||||
(_TRUSTED_LITERALS, "1.1.1.1", False),
|
||||
# Test IPv6 Addresses
|
||||
(_TRUSTED_LITERALS, "2001:db8::", False),
|
||||
(_TRUSTED_LITERALS, "2001:db8:abcd:0012::0", False),
|
||||
(_TRUSTED_LITERALS, "2001:db8:abcd:0012::1:1", False),
|
||||
(_TRUSTED_LITERALS, "::", False),
|
||||
(_TRUSTED_LITERALS, "::1", False),
|
||||
(
|
||||
_TRUSTED_LITERALS,
|
||||
"2001:db8:3333:4444:5555:6666:102:304",
|
||||
False,
|
||||
), # aka 2001:db8:3333:4444:5555:6666:1.2.3.4
|
||||
(_TRUSTED_LITERALS, "::b16:212c", False), # aka ::11.22.33.44
|
||||
(_TRUSTED_LITERALS, "a:b:c:d::", False),
|
||||
(_TRUSTED_LITERALS, "::a:b:c:d", False),
|
||||
# Test Literals
|
||||
(_TRUSTED_LITERALS, "some-literal", True),
|
||||
(_TRUSTED_LITERALS, "unix:///foo/bar", True),
|
||||
(_TRUSTED_LITERALS, "*", False),
|
||||
(_TRUSTED_LITERALS, "/foo/bar", True),
|
||||
(_TRUSTED_LITERALS, "another-literal", False),
|
||||
(_TRUSTED_LITERALS, "unix:///another/path", False),
|
||||
(_TRUSTED_LITERALS, "/another/path", False),
|
||||
(_TRUSTED_LITERALS, "", False),
|
||||
],
|
||||
)
|
||||
def test_forwarded_hosts(init_hosts: str | list[str], test_host: str, expected: bool) -> None:
|
||||
trusted_hosts = _TrustedHosts(init_hosts)
|
||||
assert (test_host in trusted_hosts) is expected
|
||||
|
||||
|
||||
@pytest.mark.anyio
|
||||
@pytest.mark.parametrize(
|
||||
("trusted_hosts", "expected"),
|
||||
[
|
||||
# always trust
|
||||
("*", "https://1.2.3.4:0"),
|
||||
# trusted proxy
|
||||
("127.0.0.1", "https://1.2.3.4:0"),
|
||||
(["127.0.0.1"], "https://1.2.3.4:0"),
|
||||
# trusted proxy list
|
||||
(["127.0.0.1", "10.0.0.1"], "https://1.2.3.4:0"),
|
||||
("127.0.0.1, 10.0.0.1", "https://1.2.3.4:0"),
|
||||
# trusted proxy network
|
||||
# https://github.com/Kludex/uvicorn/issues/1068#issuecomment-1004813267
|
||||
("127.0.0.0/24, 10.0.0.1", "https://1.2.3.4:0"),
|
||||
# request from untrusted proxy
|
||||
("192.168.0.1", "http://127.0.0.1:123"),
|
||||
# request from untrusted proxy network
|
||||
("192.168.0.0/16", "http://127.0.0.1:123"),
|
||||
# request from client running on proxy server itself
|
||||
# https://github.com/Kludex/uvicorn/issues/1068#issuecomment-855371576
|
||||
(["127.0.0.1", "1.2.3.4"], "https://1.2.3.4:0"),
|
||||
],
|
||||
)
|
||||
async def test_proxy_headers_trusted_hosts(trusted_hosts: str | list[str], expected: str) -> None:
|
||||
async with make_httpx_client(trusted_hosts) as client:
|
||||
headers = {X_FORWARDED_FOR: "1.2.3.4", X_FORWARDED_PROTO: "https"}
|
||||
response = await client.get("/", headers=headers)
|
||||
def test_proxy_headers():
|
||||
client = TestClient(app)
|
||||
headers = {"X-Forwarded-Proto": "https", "X-Forwarded-For": "1.2.3.4"}
|
||||
response = client.get("/", headers=headers)
|
||||
assert response.status_code == 200
|
||||
assert response.text == expected
|
||||
assert response.text == "Remote: https://1.2.3.4:0"
|
||||
|
||||
|
||||
@pytest.mark.anyio
|
||||
@pytest.mark.parametrize(
|
||||
("forwarded_for", "forwarded_proto", "expected"),
|
||||
[
|
||||
("", "", "http://127.0.0.1:123"),
|
||||
("", None, "http://127.0.0.1:123"),
|
||||
("", "asdf", "http://127.0.0.1:123"),
|
||||
(" , ", "https", "https://127.0.0.1:123"),
|
||||
(", , ", "https", "https://127.0.0.1:123"),
|
||||
(" , 10.0.0.1", "https", "https://127.0.0.1:123"),
|
||||
("9.9.9.9 , , , 10.0.0.1", "https", "https://127.0.0.1:123"),
|
||||
(", , 9.9.9.9", "https", "https://9.9.9.9:0"),
|
||||
(", , 9.9.9.9, , ", "https", "https://127.0.0.1:123"),
|
||||
],
|
||||
)
|
||||
async def test_proxy_headers_trusted_hosts_malformed(
|
||||
forwarded_for: str,
|
||||
forwarded_proto: str | None,
|
||||
expected: str,
|
||||
) -> None:
|
||||
async with make_httpx_client("127.0.0.1, 10.0.0.0/8") as client:
|
||||
headers = {X_FORWARDED_FOR: forwarded_for}
|
||||
if forwarded_proto is not None:
|
||||
headers[X_FORWARDED_PROTO] = forwarded_proto
|
||||
response = await client.get("/", headers=headers)
|
||||
def test_proxy_headers_no_port():
|
||||
client = TestClient(app)
|
||||
headers = {"X-Forwarded-Proto": "https", "X-Forwarded-For": "1.2.3.4"}
|
||||
response = client.get("/", headers=headers)
|
||||
assert response.status_code == 200
|
||||
assert response.text == expected
|
||||
assert response.text == "Remote: https://1.2.3.4:0"
|
||||
|
||||
|
||||
@pytest.mark.anyio
|
||||
@pytest.mark.parametrize(
|
||||
("trusted_hosts", "expected"),
|
||||
[
|
||||
# always trust
|
||||
("*", "https://1.2.3.4:0"),
|
||||
# all proxies are trusted
|
||||
(["127.0.0.1", "10.0.2.1", "192.168.0.2"], "https://1.2.3.4:0"),
|
||||
# order doesn't matter
|
||||
(["10.0.2.1", "192.168.0.2", "127.0.0.1"], "https://1.2.3.4:0"),
|
||||
# should set first untrusted as remote address
|
||||
(["192.168.0.2", "127.0.0.1"], "https://10.0.2.1:0"),
|
||||
# Mixed literals and networks
|
||||
(["127.0.0.1", "10.0.0.0/8", "192.168.0.2"], "https://1.2.3.4:0"),
|
||||
],
|
||||
)
|
||||
async def test_proxy_headers_multiple_proxies(trusted_hosts: str | list[str], expected: str) -> None:
|
||||
async with make_httpx_client(trusted_hosts) as client:
|
||||
headers = {X_FORWARDED_FOR: "1.2.3.4, 10.0.2.1, 192.168.0.2", X_FORWARDED_PROTO: "https"}
|
||||
response = await client.get("/", headers=headers)
|
||||
def test_proxy_headers_invalid_x_forwarded_for():
|
||||
client = TestClient(app)
|
||||
headers = {
|
||||
"X-Forwarded-Proto": "https",
|
||||
"X-Forwarded-For": "\xf0\xfd\xfd\xfd, 1.2.3.4",
|
||||
}
|
||||
response = client.get("/", headers=headers)
|
||||
assert response.status_code == 200
|
||||
assert response.text == expected
|
||||
|
||||
|
||||
@pytest.mark.anyio
|
||||
@pytest.mark.parametrize(
|
||||
("trusted_hosts", "expected"),
|
||||
[
|
||||
# always trust
|
||||
("*", "https://1.2.3.4:1234"),
|
||||
# all proxies are trusted
|
||||
(["127.0.0.1", "2001:db8::1", "192.168.0.2"], "https://1.2.3.4:1234"),
|
||||
# should set first untrusted as remote address
|
||||
(["192.168.0.2", "127.0.0.1"], "https://[2001:db8::1]:8080"),
|
||||
# Mixed literals and networks
|
||||
(["127.0.0.1", "2001:db8::/32", "192.168.0.2"], "https://1.2.3.4:1234"),
|
||||
],
|
||||
)
|
||||
async def test_proxy_headers_multiple_proxies_with_ports(trusted_hosts: str | list[str], expected: str) -> None:
|
||||
async with make_httpx_client(trusted_hosts) as client:
|
||||
headers = {
|
||||
X_FORWARDED_FOR: "1.2.3.4:1234, [2001:db8::1]:8080, 192.168.0.2:9000",
|
||||
X_FORWARDED_PROTO: "https",
|
||||
}
|
||||
response = await client.get("/", headers=headers)
|
||||
assert response.status_code == 200
|
||||
assert response.text == expected
|
||||
|
||||
|
||||
@pytest.mark.anyio
|
||||
async def test_proxy_headers_invalid_x_forwarded_for() -> None:
|
||||
async with make_httpx_client("*") as client:
|
||||
headers = httpx.Headers(
|
||||
{
|
||||
X_FORWARDED_FOR: "1.2.3.4, \xf0\xfd\xfd\xfd, unix:, ::1",
|
||||
X_FORWARDED_PROTO: "https",
|
||||
},
|
||||
encoding="latin-1",
|
||||
)
|
||||
response = await client.get("/", headers=headers)
|
||||
assert response.status_code == 200
|
||||
assert response.text == "https://1.2.3.4:0"
|
||||
|
||||
|
||||
@pytest.mark.anyio
|
||||
@pytest.mark.parametrize(
|
||||
("forwarded_for", "expected"),
|
||||
[
|
||||
# IPv4 without port
|
||||
("1.2.3.4", "https://1.2.3.4:0"),
|
||||
# IPv4 with port
|
||||
("1.2.3.4:1234", "https://1.2.3.4:1234"),
|
||||
# Bracketed IPv6 with port
|
||||
("[2001:db8::1]:443", "https://[2001:db8::1]:443"),
|
||||
# Bracketed IPv6 without port
|
||||
("[2001:db8::1]", "https://[2001:db8::1]:0"),
|
||||
# Bare IPv6 without port
|
||||
("2001:db8::1", "https://[2001:db8::1]:0"),
|
||||
# Invalid IPv4 port falls back to the original host value
|
||||
("1.2.3.4:notaport", "https://1.2.3.4:notaport:0"),
|
||||
# Invalid bracketed IPv6 port keeps the host and drops the port
|
||||
("[2001:db8::1]:notaport", "https://[2001:db8::1]:0"),
|
||||
# Trailing data after a bracketed IPv6 host is left untouched
|
||||
("[2001:db8::1]extra", "https://[2001:db8::1]extra:0"),
|
||||
# Malformed bracket is left untouched
|
||||
("[2001:db8::1", "https://[2001:db8::1:0"),
|
||||
],
|
||||
)
|
||||
async def test_proxy_headers_x_forwarded_for_port_shapes(forwarded_for: str, expected: str) -> None:
|
||||
async with make_httpx_client("*") as client:
|
||||
headers = {X_FORWARDED_FOR: forwarded_for, X_FORWARDED_PROTO: "https"}
|
||||
response = await client.get("/", headers=headers)
|
||||
assert response.status_code == 200
|
||||
assert response.text == expected
|
||||
|
||||
|
||||
@pytest.mark.anyio
|
||||
@pytest.mark.parametrize(
|
||||
"forwarded_proto,expected",
|
||||
[
|
||||
("http", "ws://1.2.3.4:0"),
|
||||
("https", "wss://1.2.3.4:0"),
|
||||
("ws", "ws://1.2.3.4:0"),
|
||||
("wss", "wss://1.2.3.4:0"),
|
||||
],
|
||||
)
|
||||
async def test_proxy_headers_websocket_x_forwarded_proto(
|
||||
forwarded_proto: str,
|
||||
expected: str,
|
||||
ws_protocol_cls: type[WSProtocol | WebSocketProtocol],
|
||||
http_protocol_cls: type[H11Protocol | HttpToolsProtocol],
|
||||
unused_tcp_port: int,
|
||||
) -> None:
|
||||
async def websocket_app(scope: Scope, receive: ASGIReceiveCallable, send: ASGISendCallable) -> None:
|
||||
assert scope["type"] == "websocket"
|
||||
scheme = scope["scheme"]
|
||||
assert scope["client"] is not None
|
||||
host, port = scope["client"]
|
||||
await send({"type": "websocket.accept"})
|
||||
await send({"type": "websocket.send", "text": f"{scheme}://{host}:{port}"})
|
||||
await send({"type": "websocket.close"})
|
||||
|
||||
app_with_middleware = ProxyHeadersMiddleware(websocket_app, trusted_hosts="*")
|
||||
config = Config(
|
||||
app=app_with_middleware,
|
||||
ws=ws_protocol_cls,
|
||||
http=http_protocol_cls,
|
||||
lifespan="off",
|
||||
port=unused_tcp_port,
|
||||
)
|
||||
|
||||
async with run_server(config):
|
||||
url = f"ws://127.0.0.1:{unused_tcp_port}"
|
||||
headers = {X_FORWARDED_FOR: "1.2.3.4", X_FORWARDED_PROTO: forwarded_proto}
|
||||
async with websockets.client.connect(url, extra_headers=headers) as websocket:
|
||||
data = await websocket.recv()
|
||||
assert data == expected
|
||||
|
||||
|
||||
@pytest.mark.anyio
|
||||
async def test_proxy_headers_empty_x_forwarded_for() -> None:
|
||||
# fallback to the default behavior if x-forwarded-for is an empty list
|
||||
# https://github.com/Kludex/uvicorn/issues/1068#issuecomment-855371576
|
||||
async with make_httpx_client("*") as client:
|
||||
headers = {X_FORWARDED_FOR: "", X_FORWARDED_PROTO: "https"}
|
||||
response = await client.get("/", headers=headers)
|
||||
assert response.status_code == 200
|
||||
assert response.text == "https://127.0.0.1:123"
|
||||
assert response.text == "Remote: https://1.2.3.4:0"
|
||||
|
||||
@ -1,44 +1,38 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import io
|
||||
import sys
|
||||
from collections.abc import AsyncGenerator, Callable
|
||||
|
||||
import a2wsgi
|
||||
import httpx
|
||||
import pytest
|
||||
|
||||
from uvicorn._types import Environ, HTTPRequestEvent, HTTPScope, StartResponse
|
||||
from uvicorn.middleware import wsgi
|
||||
from tests.client import TestClient
|
||||
from uvicorn.middleware.wsgi import WSGIMiddleware
|
||||
|
||||
|
||||
def hello_world(environ: Environ, start_response: StartResponse) -> list[bytes]:
|
||||
def hello_world(environ, start_response):
|
||||
status = "200 OK"
|
||||
output = b"Hello World!\n"
|
||||
headers = [
|
||||
("Content-Type", "text/plain; charset=utf-8"),
|
||||
("Content-Length", str(len(output))),
|
||||
]
|
||||
start_response(status, headers, None)
|
||||
start_response(status, headers)
|
||||
return [output]
|
||||
|
||||
|
||||
def echo_body(environ: Environ, start_response: StartResponse) -> list[bytes]:
|
||||
def echo_body(environ, start_response):
|
||||
status = "200 OK"
|
||||
output = environ["wsgi.input"].read()
|
||||
headers = [
|
||||
("Content-Type", "text/plain; charset=utf-8"),
|
||||
("Content-Length", str(len(output))),
|
||||
]
|
||||
start_response(status, headers, None)
|
||||
start_response(status, headers)
|
||||
return [output]
|
||||
|
||||
|
||||
def raise_exception(environ: Environ, start_response: StartResponse) -> list[bytes]:
|
||||
def raise_exception(environ, start_response):
|
||||
raise RuntimeError("Something went wrong")
|
||||
|
||||
|
||||
def return_exc_info(environ: Environ, start_response: StartResponse) -> list[bytes]:
|
||||
def return_exc_info(environ, start_response):
|
||||
try:
|
||||
raise RuntimeError("Something went wrong")
|
||||
except RuntimeError:
|
||||
@ -48,91 +42,45 @@ def return_exc_info(environ: Environ, start_response: StartResponse) -> list[byt
|
||||
("Content-Type", "text/plain; charset=utf-8"),
|
||||
("Content-Length", str(len(output))),
|
||||
]
|
||||
start_response(status, headers, sys.exc_info()) # type: ignore[arg-type]
|
||||
start_response(status, headers, exc_info=sys.exc_info())
|
||||
return [output]
|
||||
|
||||
|
||||
@pytest.fixture(params=[wsgi._WSGIMiddleware, a2wsgi.WSGIMiddleware])
|
||||
def wsgi_middleware(request: pytest.FixtureRequest) -> Callable:
|
||||
return request.param
|
||||
|
||||
|
||||
@pytest.mark.anyio
|
||||
async def test_wsgi_get(wsgi_middleware: Callable) -> None:
|
||||
transport = httpx.ASGITransport(wsgi_middleware(hello_world))
|
||||
async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as client:
|
||||
response = await client.get("/")
|
||||
def test_wsgi_get():
|
||||
app = WSGIMiddleware(hello_world)
|
||||
client = TestClient(app)
|
||||
response = client.get("/")
|
||||
assert response.status_code == 200
|
||||
assert response.text == "Hello World!\n"
|
||||
|
||||
|
||||
@pytest.mark.anyio
|
||||
async def test_wsgi_post(wsgi_middleware: Callable) -> None:
|
||||
transport = httpx.ASGITransport(wsgi_middleware(echo_body))
|
||||
async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as client:
|
||||
response = await client.post("/", json={"example": 123})
|
||||
def test_wsgi_post():
|
||||
app = WSGIMiddleware(echo_body)
|
||||
client = TestClient(app)
|
||||
response = client.post("/", json={"example": 123})
|
||||
assert response.status_code == 200
|
||||
assert response.text == '{"example":123}'
|
||||
assert response.text == '{"example": 123}'
|
||||
|
||||
|
||||
@pytest.mark.anyio
|
||||
async def test_wsgi_put_more_body(wsgi_middleware: Callable) -> None:
|
||||
async def generate_body() -> AsyncGenerator[bytes, None]:
|
||||
for _ in range(1024):
|
||||
yield b"123456789abcdef\n" * 64
|
||||
|
||||
transport = httpx.ASGITransport(wsgi_middleware(echo_body))
|
||||
async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as client:
|
||||
response = await client.put("/", content=generate_body())
|
||||
assert response.status_code == 200
|
||||
assert response.text == "123456789abcdef\n" * 64 * 1024
|
||||
|
||||
|
||||
@pytest.mark.anyio
|
||||
async def test_wsgi_exception(wsgi_middleware: Callable) -> None:
|
||||
def test_wsgi_exception():
|
||||
# Note that we're testing the WSGI app directly here.
|
||||
# The HTTP protocol implementations would catch this error and return 500.
|
||||
transport = httpx.ASGITransport(wsgi_middleware(raise_exception))
|
||||
async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as client:
|
||||
with pytest.raises(RuntimeError):
|
||||
await client.get("/")
|
||||
app = WSGIMiddleware(raise_exception)
|
||||
client = TestClient(app)
|
||||
with pytest.raises(RuntimeError):
|
||||
client.get("/")
|
||||
|
||||
|
||||
@pytest.mark.anyio
|
||||
async def test_wsgi_exc_info(wsgi_middleware: Callable) -> None:
|
||||
app = wsgi_middleware(return_exc_info)
|
||||
transport = httpx.ASGITransport(
|
||||
app=app,
|
||||
raise_app_exceptions=False,
|
||||
)
|
||||
async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as client:
|
||||
response = await client.get("/")
|
||||
def test_wsgi_exc_info():
|
||||
# Note that we're testing the WSGI app directly here.
|
||||
# The HTTP protocol implementations would catch this error and return 500.
|
||||
app = WSGIMiddleware(return_exc_info)
|
||||
client = TestClient(app)
|
||||
with pytest.raises(RuntimeError):
|
||||
response = client.get("/")
|
||||
|
||||
app = WSGIMiddleware(return_exc_info)
|
||||
client = TestClient(app, raise_server_exceptions=False)
|
||||
response = client.get("/")
|
||||
assert response.status_code == 500
|
||||
assert response.text == "Internal Server Error"
|
||||
|
||||
|
||||
def test_build_environ_encoding() -> None:
|
||||
scope: HTTPScope = {
|
||||
"asgi": {"version": "3.0", "spec_version": "2.0"},
|
||||
"scheme": "http",
|
||||
"raw_path": b"/\xe6\x96\x87%2Fall",
|
||||
"type": "http",
|
||||
"http_version": "1.1",
|
||||
"method": "GET",
|
||||
"path": "/文/all",
|
||||
"root_path": "/文",
|
||||
"client": None,
|
||||
"server": None,
|
||||
"query_string": b"a=123&b=456",
|
||||
"headers": [(b"key", b"value1"), (b"key", b"value2")],
|
||||
"extensions": {},
|
||||
}
|
||||
message: HTTPRequestEvent = {
|
||||
"type": "http.request",
|
||||
"body": b"",
|
||||
"more_body": False,
|
||||
}
|
||||
environ = wsgi.build_environ(scope, message, io.BytesIO(b""))
|
||||
assert environ["SCRIPT_NAME"] == "/文".encode().decode("latin-1")
|
||||
assert environ["PATH_INFO"] == b"/all".decode("latin-1")
|
||||
assert environ["HTTP_KEY"] == "value1,value2"
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,21 +1,10 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import socket
|
||||
from asyncio import Transport
|
||||
from typing import Any
|
||||
|
||||
import pytest
|
||||
|
||||
from uvicorn.protocols.utils import get_client_addr, get_local_addr, get_remote_addr
|
||||
from uvicorn.protocols.utils import get_local_addr, get_remote_addr
|
||||
|
||||
|
||||
class MockSocket:
|
||||
def __init__(
|
||||
self,
|
||||
family: socket.AddressFamily,
|
||||
peername: tuple[str, int] | None = None,
|
||||
sockname: tuple[str, int] | str | None = None,
|
||||
):
|
||||
def __init__(self, family, peername=None, sockname=None):
|
||||
self.peername = peername
|
||||
self.sockname = sockname
|
||||
self.family = family
|
||||
@ -27,53 +16,63 @@ class MockSocket:
|
||||
return self.sockname
|
||||
|
||||
|
||||
class MockTransport(Transport):
|
||||
def __init__(self, info: dict[str, Any]) -> None:
|
||||
class MockTransport:
|
||||
def __init__(self, info):
|
||||
self.info = info
|
||||
|
||||
def get_extra_info(self, name: str, default: Any = None) -> Any:
|
||||
return self.info.get(name)
|
||||
def get_extra_info(self, info_type):
|
||||
return self.info.get(info_type)
|
||||
|
||||
|
||||
def test_get_local_addr_with_socket():
|
||||
transport = MockTransport({"socket": MockSocket(family=socket.AF_IPX)})
|
||||
assert get_local_addr(transport) is None
|
||||
|
||||
transport = MockTransport({"socket": MockSocket(family=socket.AF_INET6, sockname=("::1", 123))})
|
||||
transport = MockTransport(
|
||||
{"socket": MockSocket(family=socket.AF_INET6, sockname=("::1", 123))}
|
||||
)
|
||||
assert get_local_addr(transport) == ("::1", 123)
|
||||
|
||||
transport = MockTransport({"socket": MockSocket(family=socket.AF_INET, sockname=("123.45.6.7", 123))})
|
||||
transport = MockTransport(
|
||||
{"socket": MockSocket(family=socket.AF_INET, sockname=("123.45.6.7", 123))}
|
||||
)
|
||||
assert get_local_addr(transport) == ("123.45.6.7", 123)
|
||||
|
||||
transport = MockTransport({"socket": MockSocket(family=socket.AF_INET, sockname="/tmp/test.sock")})
|
||||
assert get_local_addr(transport) == ("/tmp/test.sock", None)
|
||||
if hasattr(socket, "AF_UNIX"):
|
||||
transport = MockTransport(
|
||||
{"socket": MockSocket(family=socket.AF_UNIX, sockname=("127.0.0.1", 8000))}
|
||||
)
|
||||
assert get_local_addr(transport) == ("127.0.0.1", 8000)
|
||||
|
||||
|
||||
def test_get_remote_addr_with_socket():
|
||||
transport = MockTransport({"socket": MockSocket(family=socket.AF_IPX)})
|
||||
assert get_remote_addr(transport) is None
|
||||
|
||||
transport = MockTransport({"socket": MockSocket(family=socket.AF_INET6, peername=("::1", 123))})
|
||||
transport = MockTransport(
|
||||
{"socket": MockSocket(family=socket.AF_INET6, peername=("::1", 123))}
|
||||
)
|
||||
assert get_remote_addr(transport) == ("::1", 123)
|
||||
|
||||
transport = MockTransport({"socket": MockSocket(family=socket.AF_INET, peername=("123.45.6.7", 123))})
|
||||
transport = MockTransport(
|
||||
{"socket": MockSocket(family=socket.AF_INET, peername=("123.45.6.7", 123))}
|
||||
)
|
||||
assert get_remote_addr(transport) == ("123.45.6.7", 123)
|
||||
|
||||
if hasattr(socket, "AF_UNIX"): # pragma: no cover
|
||||
transport = MockTransport({"socket": MockSocket(family=socket.AF_UNIX, peername=("127.0.0.1", 8000))})
|
||||
if hasattr(socket, "AF_UNIX"):
|
||||
transport = MockTransport(
|
||||
{"socket": MockSocket(family=socket.AF_UNIX, peername=("127.0.0.1", 8000))}
|
||||
)
|
||||
assert get_remote_addr(transport) == ("127.0.0.1", 8000)
|
||||
|
||||
|
||||
def test_get_local_addr():
|
||||
transport = MockTransport({"sockname": "path/to/unix-domain-socket"})
|
||||
assert get_local_addr(transport) == ("path/to/unix-domain-socket", None)
|
||||
assert get_local_addr(transport) is None
|
||||
|
||||
transport = MockTransport({"sockname": ("123.45.6.7", 123)})
|
||||
assert get_local_addr(transport) == ("123.45.6.7", 123)
|
||||
|
||||
transport = MockTransport({})
|
||||
assert get_local_addr(transport) is None
|
||||
|
||||
|
||||
def test_get_remote_addr():
|
||||
transport = MockTransport({"peername": None})
|
||||
@ -81,12 +80,3 @@ def test_get_remote_addr():
|
||||
|
||||
transport = MockTransport({"peername": ("123.45.6.7", 123)})
|
||||
assert get_remote_addr(transport) == ("123.45.6.7", 123)
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"scope, expected_client",
|
||||
[({"client": ("127.0.0.1", 36000)}, "127.0.0.1:36000"), ({"client": None}, "")],
|
||||
ids=["ip:port client", "None client"],
|
||||
)
|
||||
def test_get_client_addr(scope: Any, expected_client: str):
|
||||
assert get_client_addr(scope) == expected_client
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -10,15 +10,17 @@ class Response:
|
||||
self.set_content_length()
|
||||
|
||||
async def __call__(self, scope, receive, send) -> None:
|
||||
prefix = "websocket." if scope["type"] == "websocket" else ""
|
||||
await send(
|
||||
{
|
||||
"type": prefix + "http.response.start",
|
||||
"type": "http.response.start",
|
||||
"status": self.status_code,
|
||||
"headers": [[key.encode(), value.encode()] for key, value in self.headers.items()],
|
||||
"headers": [
|
||||
[key.encode(), value.encode()]
|
||||
for key, value in self.headers.items()
|
||||
],
|
||||
}
|
||||
)
|
||||
await send({"type": prefix + "http.response.body", "body": self.body})
|
||||
await send({"type": "http.response.body", "body": self.body})
|
||||
|
||||
def render(self, content) -> bytes:
|
||||
if isinstance(content, bytes):
|
||||
|
||||
@ -1,175 +1,21 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import functools
|
||||
import os
|
||||
import signal
|
||||
import socket
|
||||
import threading
|
||||
import time
|
||||
from collections.abc import Callable
|
||||
from typing import Any
|
||||
|
||||
import pytest
|
||||
|
||||
from uvicorn import Config
|
||||
from uvicorn._types import ASGIReceiveCallable, ASGISendCallable, Scope
|
||||
from uvicorn.supervisors import Multiprocess
|
||||
from uvicorn.supervisors.multiprocess import Process
|
||||
|
||||
|
||||
def new_console_in_windows(test_function: Callable[[], Any]) -> Callable[[], Any]: # pragma: no cover
|
||||
if os.name != "nt":
|
||||
return test_function
|
||||
|
||||
@functools.wraps(test_function)
|
||||
def new_function():
|
||||
import subprocess
|
||||
import sys
|
||||
|
||||
module = test_function.__module__
|
||||
name = test_function.__name__
|
||||
|
||||
subprocess.check_call(
|
||||
[sys.executable, "-c", f"from {module} import {name}; {name}.__wrapped__()"],
|
||||
creationflags=subprocess.CREATE_NO_WINDOW,
|
||||
)
|
||||
|
||||
return new_function
|
||||
def run(sockets):
|
||||
pass
|
||||
|
||||
|
||||
async def app(scope: Scope, receive: ASGIReceiveCallable, send: ASGISendCallable) -> None:
|
||||
pass # pragma: no cover
|
||||
|
||||
|
||||
def run(sockets: list[socket.socket] | None) -> None:
|
||||
while True: # pragma: no cover
|
||||
time.sleep(1)
|
||||
|
||||
|
||||
def test_process_ping_pong() -> None:
|
||||
process = Process(Config(app=app), target=lambda x: None, sockets=[])
|
||||
threading.Thread(target=process.always_pong, daemon=True).start()
|
||||
assert process.ping()
|
||||
|
||||
|
||||
def test_process_ping_pong_timeout() -> None:
|
||||
process = Process(Config(app=app), target=lambda x: None, sockets=[])
|
||||
assert not process.ping(0.1)
|
||||
|
||||
|
||||
@new_console_in_windows
|
||||
def test_multiprocess_run() -> None:
|
||||
def test_multiprocess_run():
|
||||
"""
|
||||
A basic sanity check.
|
||||
|
||||
Simply run the supervisor against a no-op server, and signal for it to
|
||||
quit immediately.
|
||||
"""
|
||||
config = Config(app=app, workers=2)
|
||||
config = Config(app=None, workers=2)
|
||||
supervisor = Multiprocess(config, target=run, sockets=[])
|
||||
threading.Thread(target=supervisor.run, daemon=True).start()
|
||||
supervisor.signal_queue.append(signal.SIGINT)
|
||||
supervisor.join_all()
|
||||
|
||||
|
||||
@new_console_in_windows
|
||||
def test_multiprocess_health_check() -> None:
|
||||
"""
|
||||
Ensure that the health check works as expected.
|
||||
"""
|
||||
config = Config(app=app, workers=2)
|
||||
supervisor = Multiprocess(config, target=run, sockets=[])
|
||||
threading.Thread(target=supervisor.run, daemon=True).start()
|
||||
time.sleep(1)
|
||||
process = supervisor.processes[0]
|
||||
process.kill()
|
||||
assert not process.is_alive()
|
||||
deadline = time.monotonic() + 10
|
||||
while not all(p.is_alive() for p in supervisor.processes): # pragma: no cover
|
||||
assert time.monotonic() < deadline, "Timed out waiting for processes to be alive"
|
||||
time.sleep(0.1)
|
||||
supervisor.signal_queue.append(signal.SIGINT)
|
||||
supervisor.join_all()
|
||||
|
||||
|
||||
@new_console_in_windows
|
||||
def test_multiprocess_sigterm() -> None:
|
||||
"""
|
||||
Ensure that the SIGTERM signal is handled as expected.
|
||||
"""
|
||||
config = Config(app=app, workers=2)
|
||||
supervisor = Multiprocess(config, target=run, sockets=[])
|
||||
threading.Thread(target=supervisor.run, daemon=True).start()
|
||||
time.sleep(1)
|
||||
supervisor.signal_queue.append(signal.SIGTERM)
|
||||
supervisor.join_all()
|
||||
|
||||
|
||||
@pytest.mark.skipif(not hasattr(signal, "SIGBREAK"), reason="platform unsupports SIGBREAK")
|
||||
@new_console_in_windows
|
||||
def test_multiprocess_sigbreak() -> None: # pragma: py-not-win32
|
||||
"""
|
||||
Ensure that the SIGBREAK signal is handled as expected.
|
||||
"""
|
||||
config = Config(app=app, workers=2)
|
||||
supervisor = Multiprocess(config, target=run, sockets=[])
|
||||
threading.Thread(target=supervisor.run, daemon=True).start()
|
||||
time.sleep(1)
|
||||
supervisor.signal_queue.append(getattr(signal, "SIGBREAK"))
|
||||
supervisor.join_all()
|
||||
|
||||
|
||||
@pytest.mark.skipif(not hasattr(signal, "SIGHUP"), reason="platform unsupports SIGHUP")
|
||||
def test_multiprocess_sighup() -> None:
|
||||
"""
|
||||
Ensure that the SIGHUP signal is handled as expected.
|
||||
"""
|
||||
config = Config(app=app, workers=2)
|
||||
supervisor = Multiprocess(config, target=run, sockets=[])
|
||||
threading.Thread(target=supervisor.run, daemon=True).start()
|
||||
time.sleep(1)
|
||||
pids = [p.pid for p in supervisor.processes]
|
||||
supervisor.signal_queue.append(signal.SIGHUP)
|
||||
# Poll instead of a fixed sleep — the supervisor loop runs on a 0.5s interval and `restart_all()` terminates/joins
|
||||
# each worker sequentially, so the total time is non-deterministic.
|
||||
deadline = time.monotonic() + 10
|
||||
while time.monotonic() < deadline:
|
||||
if [p.pid for p in supervisor.processes] != pids:
|
||||
break
|
||||
time.sleep(0.1)
|
||||
assert pids != [p.pid for p in supervisor.processes]
|
||||
supervisor.signal_queue.append(signal.SIGINT)
|
||||
supervisor.join_all()
|
||||
|
||||
|
||||
@pytest.mark.skipif(not hasattr(signal, "SIGTTIN"), reason="platform unsupports SIGTTIN")
|
||||
def test_multiprocess_sigttin() -> None:
|
||||
"""
|
||||
Ensure that the SIGTTIN signal is handled as expected.
|
||||
"""
|
||||
config = Config(app=app, workers=2)
|
||||
supervisor = Multiprocess(config, target=run, sockets=[])
|
||||
threading.Thread(target=supervisor.run, daemon=True).start()
|
||||
supervisor.signal_queue.append(signal.SIGTTIN)
|
||||
time.sleep(1)
|
||||
assert len(supervisor.processes) == 3
|
||||
supervisor.signal_queue.append(signal.SIGINT)
|
||||
supervisor.join_all()
|
||||
|
||||
|
||||
@pytest.mark.skipif(not hasattr(signal, "SIGTTOU"), reason="platform unsupports SIGTTOU")
|
||||
def test_multiprocess_sigttou() -> None:
|
||||
"""
|
||||
Ensure that the SIGTTOU signal is handled as expected.
|
||||
"""
|
||||
config = Config(app=app, workers=2)
|
||||
supervisor = Multiprocess(config, target=run, sockets=[])
|
||||
threading.Thread(target=supervisor.run, daemon=True).start()
|
||||
supervisor.signal_queue.append(signal.SIGTTOU)
|
||||
time.sleep(1)
|
||||
assert len(supervisor.processes) == 1
|
||||
supervisor.signal_queue.append(signal.SIGTTOU)
|
||||
time.sleep(1)
|
||||
assert len(supervisor.processes) == 1
|
||||
supervisor.signal_queue.append(signal.SIGINT)
|
||||
supervisor.join_all()
|
||||
supervisor.signal_handler(sig=signal.SIGINT, frame=None)
|
||||
supervisor.run()
|
||||
|
||||
@ -1,401 +1,98 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import signal
|
||||
import socket
|
||||
import sys
|
||||
from collections.abc import Callable, Generator
|
||||
from pathlib import Path
|
||||
from threading import Thread
|
||||
from time import sleep
|
||||
|
||||
import pytest
|
||||
from pytest_mock import MockerFixture
|
||||
|
||||
from tests.utils import as_cwd
|
||||
from uvicorn.config import Config
|
||||
from uvicorn.supervisors.basereload import BaseReload, _display_path
|
||||
from uvicorn.supervisors.basereload import BaseReload
|
||||
from uvicorn.supervisors.statreload import StatReload
|
||||
|
||||
try:
|
||||
from uvicorn.supervisors.watchfilesreload import WatchFilesReload
|
||||
except ImportError: # pragma: no cover
|
||||
WatchFilesReload = None # type: ignore[misc,assignment]
|
||||
|
||||
|
||||
# TODO: Investigate why this is flaky on MacOS, and Windows.
|
||||
skip_non_linux = pytest.mark.skipif(sys.platform in ("darwin", "win32"), reason="Flaky on Windows and MacOS")
|
||||
|
||||
|
||||
def run(sockets: list[socket.socket] | None) -> None:
|
||||
pass # pragma: no cover
|
||||
|
||||
|
||||
def sleep_touch(*paths: Path):
|
||||
sleep(0.1)
|
||||
for p in paths:
|
||||
p.touch()
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def touch_soon() -> Generator[Callable[[Path], None]]:
|
||||
threads: list[Thread] = []
|
||||
|
||||
def start(*paths: Path) -> None:
|
||||
thread = Thread(target=sleep_touch, args=paths)
|
||||
thread.start()
|
||||
threads.append(thread)
|
||||
|
||||
yield start
|
||||
|
||||
for t in threads:
|
||||
t.join()
|
||||
from uvicorn.supervisors.watchgodreload import WatchGodReload
|
||||
|
||||
|
||||
@pytest.mark.parametrize("reloader_class", [StatReload, WatchGodReload])
|
||||
class TestBaseReload:
|
||||
tmp_path: Path
|
||||
|
||||
@pytest.fixture(autouse=True)
|
||||
def setup(self, reload_directory_structure: Path, reloader_class: type[BaseReload] | None):
|
||||
if reloader_class is None: # pragma: no cover
|
||||
pytest.skip("Needed dependency not installed")
|
||||
self.reload_path = reload_directory_structure
|
||||
def setup(self, tmpdir, reloader_class):
|
||||
self.tmpdir = tmpdir
|
||||
self.tmp_path = Path(tmpdir)
|
||||
self.reloader_class = reloader_class
|
||||
|
||||
def run(self, sockets):
|
||||
pass
|
||||
|
||||
def _setup_reloader(self, config: Config) -> BaseReload:
|
||||
config.reload_delay = 0 # save time
|
||||
|
||||
reloader = self.reloader_class(config, target=run, sockets=[])
|
||||
|
||||
assert config.should_reload
|
||||
reloader = self.reloader_class(config, target=self.run, sockets=[])
|
||||
reloader.signal_handler(sig=signal.SIGINT, frame=None)
|
||||
reloader.startup()
|
||||
return reloader
|
||||
|
||||
def _reload_tester(
|
||||
self, touch_soon: Callable[[Path], None], reloader: BaseReload, *files: Path
|
||||
) -> list[Path] | None:
|
||||
def _reload_tester(self, reloader: BaseReload, file: Path) -> bool:
|
||||
reloader.restart()
|
||||
if WatchFilesReload is not None and isinstance(reloader, WatchFilesReload):
|
||||
touch_soon(*files)
|
||||
else:
|
||||
assert not next(reloader)
|
||||
sleep(0.1)
|
||||
for file in files:
|
||||
file.touch()
|
||||
return next(reloader)
|
||||
assert not reloader.should_restart()
|
||||
sleep(0.1)
|
||||
file.touch()
|
||||
return reloader.should_restart()
|
||||
|
||||
@pytest.mark.parametrize("reloader_class", [StatReload, WatchFilesReload])
|
||||
def test_reloader_should_initialize(self) -> None:
|
||||
def test_reloader_should_initialize(self):
|
||||
"""
|
||||
A basic sanity check.
|
||||
|
||||
Simply run the reloader against a no-op server, and signal for it to
|
||||
quit immediately.
|
||||
"""
|
||||
with as_cwd(self.reload_path):
|
||||
config = Config(app="tests.test_config:asgi_app", reload=True)
|
||||
reloader = self._setup_reloader(config)
|
||||
reloader.shutdown()
|
||||
|
||||
@pytest.mark.parametrize("reloader_class", [StatReload, pytest.param(WatchFilesReload, marks=skip_non_linux)])
|
||||
def test_reload_when_python_file_is_changed(self, touch_soon: Callable[[Path], None]):
|
||||
file = self.reload_path / "main.py"
|
||||
|
||||
with as_cwd(self.reload_path):
|
||||
config = Config(app="tests.test_config:asgi_app", reload=True)
|
||||
reloader = self._setup_reloader(config)
|
||||
|
||||
changes = self._reload_tester(touch_soon, reloader, file)
|
||||
assert changes == [file]
|
||||
|
||||
reloader.shutdown()
|
||||
|
||||
@pytest.mark.parametrize("reloader_class", [StatReload, WatchFilesReload])
|
||||
def test_should_reload_when_python_file_in_subdir_is_changed(self, touch_soon: Callable[[Path], None]):
|
||||
file = self.reload_path / "app" / "sub" / "sub.py"
|
||||
|
||||
with as_cwd(self.reload_path):
|
||||
config = Config(app="tests.test_config:asgi_app", reload=True)
|
||||
reloader = self._setup_reloader(config)
|
||||
|
||||
assert self._reload_tester(touch_soon, reloader, file)
|
||||
|
||||
reloader.shutdown()
|
||||
|
||||
@pytest.mark.parametrize("reloader_class", [WatchFilesReload])
|
||||
def test_should_not_reload_when_python_file_in_excluded_subdir_is_changed(self, touch_soon: Callable[[Path], None]):
|
||||
sub_dir = self.reload_path / "app" / "sub"
|
||||
sub_file = sub_dir / "sub.py"
|
||||
|
||||
with as_cwd(self.reload_path):
|
||||
config = Config(
|
||||
app="tests.test_config:asgi_app",
|
||||
reload=True,
|
||||
reload_excludes=[str(sub_dir)],
|
||||
)
|
||||
reloader = self._setup_reloader(config)
|
||||
|
||||
assert not self._reload_tester(touch_soon, reloader, sub_file)
|
||||
|
||||
reloader.shutdown()
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"reloader_class, result", [(StatReload, False), pytest.param(WatchFilesReload, True, marks=skip_non_linux)]
|
||||
)
|
||||
def test_reload_when_pattern_matched_file_is_changed(
|
||||
self, result: bool, touch_soon: Callable[[Path], None]
|
||||
): # pragma: py-not-linux
|
||||
file = self.reload_path / "app" / "js" / "main.js"
|
||||
|
||||
with as_cwd(self.reload_path):
|
||||
config = Config(app="tests.test_config:asgi_app", reload=True, reload_includes=["*.js"])
|
||||
reloader = self._setup_reloader(config)
|
||||
|
||||
assert bool(self._reload_tester(touch_soon, reloader, file)) == result
|
||||
|
||||
reloader.shutdown()
|
||||
|
||||
@pytest.mark.parametrize("reloader_class", [pytest.param(WatchFilesReload, marks=skip_non_linux)])
|
||||
def test_should_not_reload_when_exclude_pattern_match_file_is_changed(
|
||||
self, touch_soon: Callable[[Path], None]
|
||||
): # pragma: py-not-linux
|
||||
python_file = self.reload_path / "app" / "src" / "main.py"
|
||||
css_file = self.reload_path / "app" / "css" / "main.css"
|
||||
js_file = self.reload_path / "app" / "js" / "main.js"
|
||||
|
||||
with as_cwd(self.reload_path):
|
||||
config = Config(
|
||||
app="tests.test_config:asgi_app",
|
||||
reload=True,
|
||||
reload_includes=["*"],
|
||||
reload_excludes=["*.js"],
|
||||
)
|
||||
reloader = self._setup_reloader(config)
|
||||
|
||||
assert self._reload_tester(touch_soon, reloader, python_file)
|
||||
assert self._reload_tester(touch_soon, reloader, css_file)
|
||||
assert not self._reload_tester(touch_soon, reloader, js_file)
|
||||
|
||||
reloader.shutdown()
|
||||
|
||||
@pytest.mark.parametrize("reloader_class", [StatReload, WatchFilesReload])
|
||||
def test_should_not_reload_when_dot_file_is_changed(self, touch_soon: Callable[[Path], None]):
|
||||
file = self.reload_path / ".dotted"
|
||||
|
||||
with as_cwd(self.reload_path):
|
||||
config = Config(app="tests.test_config:asgi_app", reload=True)
|
||||
reloader = self._setup_reloader(config)
|
||||
|
||||
assert not self._reload_tester(touch_soon, reloader, file)
|
||||
|
||||
reloader.shutdown()
|
||||
|
||||
@pytest.mark.parametrize("reloader_class", [StatReload, pytest.param(WatchFilesReload, marks=skip_non_linux)])
|
||||
def test_should_reload_when_directories_have_same_prefix(
|
||||
self, touch_soon: Callable[[Path], None]
|
||||
): # pragma: py-not-linux
|
||||
app_dir = self.reload_path / "app"
|
||||
app_file = app_dir / "src" / "main.py"
|
||||
app_first_dir = self.reload_path / "app_first"
|
||||
app_first_file = app_first_dir / "src" / "main.py"
|
||||
|
||||
with as_cwd(self.reload_path):
|
||||
config = Config(
|
||||
app="tests.test_config:asgi_app",
|
||||
reload=True,
|
||||
reload_dirs=[str(app_dir), str(app_first_dir)],
|
||||
)
|
||||
reloader = self._setup_reloader(config)
|
||||
|
||||
assert self._reload_tester(touch_soon, reloader, app_file)
|
||||
assert self._reload_tester(touch_soon, reloader, app_first_file)
|
||||
|
||||
reloader.shutdown()
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"reloader_class",
|
||||
[StatReload, pytest.param(WatchFilesReload, marks=skip_non_linux)],
|
||||
)
|
||||
def test_should_not_reload_when_only_subdirectory_is_watched(
|
||||
self, touch_soon: Callable[[Path], None]
|
||||
): # pragma: py-not-linux
|
||||
app_dir = self.reload_path / "app"
|
||||
app_dir_file = self.reload_path / "app" / "src" / "main.py"
|
||||
root_file = self.reload_path / "main.py"
|
||||
|
||||
config = Config(
|
||||
app="tests.test_config:asgi_app",
|
||||
reload=True,
|
||||
reload_dirs=[str(app_dir)],
|
||||
)
|
||||
config = Config(app=None, reload=True)
|
||||
reloader = self._setup_reloader(config)
|
||||
|
||||
assert self._reload_tester(touch_soon, reloader, app_dir_file)
|
||||
assert not self._reload_tester(touch_soon, reloader, root_file, app_dir / "~ignored")
|
||||
|
||||
reloader.shutdown()
|
||||
|
||||
@pytest.mark.parametrize("reloader_class", [pytest.param(WatchFilesReload, marks=skip_non_linux)])
|
||||
def test_override_defaults(self, touch_soon: Callable[[Path], None]) -> None: # pragma: py-not-linux
|
||||
dotted_file = self.reload_path / ".dotted"
|
||||
dotted_dir_file = self.reload_path / ".dotted_dir" / "file.txt"
|
||||
python_file = self.reload_path / "main.py"
|
||||
def test_should_reload_when_python_file_is_changed(self):
|
||||
file = "example.py"
|
||||
update_file = self.tmp_path.joinpath(file)
|
||||
update_file.touch()
|
||||
|
||||
with as_cwd(self.reload_path):
|
||||
config = Config(
|
||||
app="tests.test_config:asgi_app",
|
||||
reload=True,
|
||||
# We need to add *.txt otherwise no regular files will match
|
||||
reload_includes=[".*", "*.txt"],
|
||||
reload_excludes=["*.py"],
|
||||
)
|
||||
with self.tmpdir.as_cwd():
|
||||
config = Config(app=None, reload=True)
|
||||
reloader = self._setup_reloader(config)
|
||||
|
||||
assert self._reload_tester(touch_soon, reloader, dotted_file)
|
||||
assert self._reload_tester(touch_soon, reloader, dotted_dir_file)
|
||||
assert not self._reload_tester(touch_soon, reloader, python_file)
|
||||
assert self._reload_tester(reloader, update_file)
|
||||
|
||||
reloader.shutdown()
|
||||
|
||||
@pytest.mark.parametrize("reloader_class", [pytest.param(WatchFilesReload, marks=skip_non_linux)])
|
||||
def test_explicit_paths(self, touch_soon: Callable[[Path], None]) -> None: # pragma: py-not-linux
|
||||
dotted_file = self.reload_path / ".dotted"
|
||||
non_dotted_file = self.reload_path / "ext" / "ext.jpg"
|
||||
python_file = self.reload_path / "main.py"
|
||||
def test_should_not_reload_when_dot_file_is_changed(self):
|
||||
file = ".dotted"
|
||||
|
||||
with as_cwd(self.reload_path):
|
||||
config = Config(
|
||||
app="tests.test_config:asgi_app",
|
||||
reload=True,
|
||||
reload_includes=[".dotted", "ext/ext.jpg"],
|
||||
)
|
||||
update_file = self.tmp_path.joinpath(file)
|
||||
update_file.touch()
|
||||
|
||||
with self.tmpdir.as_cwd():
|
||||
config = Config(app=None, reload=True)
|
||||
reloader = self._setup_reloader(config)
|
||||
|
||||
assert self._reload_tester(touch_soon, reloader, dotted_file)
|
||||
assert self._reload_tester(touch_soon, reloader, non_dotted_file)
|
||||
assert self._reload_tester(touch_soon, reloader, python_file)
|
||||
assert not self._reload_tester(reloader, update_file)
|
||||
|
||||
reloader.shutdown()
|
||||
|
||||
@pytest.mark.skipif(WatchFilesReload is None, reason="watchfiles not available")
|
||||
@pytest.mark.parametrize("reloader_class", [WatchFilesReload])
|
||||
def test_watchfiles_no_changes(self) -> None:
|
||||
sub_dir = self.reload_path / "app" / "sub"
|
||||
def test_should_reload_when_directories_have_same_prefix(self):
|
||||
file = "example.py"
|
||||
|
||||
with as_cwd(self.reload_path):
|
||||
app_dir = self.tmp_path.joinpath("app")
|
||||
app_ext_dir = self.tmp_path.joinpath("app_extension")
|
||||
app_file = app_dir.joinpath(file)
|
||||
app_ext_file = app_ext_dir.joinpath(file)
|
||||
app_dir.mkdir()
|
||||
app_ext_dir.mkdir()
|
||||
app_file.touch()
|
||||
app_ext_file.touch()
|
||||
|
||||
with self.tmpdir.as_cwd():
|
||||
config = Config(
|
||||
app="tests.test_config:asgi_app",
|
||||
reload=True,
|
||||
reload_excludes=[str(sub_dir)],
|
||||
app=None, reload=True, reload_dirs=[str(app_dir), str(app_ext_dir)]
|
||||
)
|
||||
reloader = self._setup_reloader(config)
|
||||
|
||||
from watchfiles import watch
|
||||
|
||||
assert isinstance(reloader, WatchFilesReload)
|
||||
# just so we can make rust_timeout 100ms
|
||||
reloader.watcher = watch(
|
||||
sub_dir,
|
||||
watch_filter=None,
|
||||
stop_event=reloader.should_exit,
|
||||
yield_on_timeout=True,
|
||||
rust_timeout=100,
|
||||
)
|
||||
|
||||
assert reloader.should_restart() is None
|
||||
assert self._reload_tester(reloader, app_file)
|
||||
assert self._reload_tester(reloader, app_ext_file)
|
||||
|
||||
reloader.shutdown()
|
||||
|
||||
|
||||
@pytest.mark.skipif(WatchFilesReload is None, reason="watchfiles not available")
|
||||
def test_should_watch_cwd(mocker: MockerFixture, reload_directory_structure: Path):
|
||||
mock_watch = mocker.patch("uvicorn.supervisors.watchfilesreload.watch")
|
||||
|
||||
config = Config(app="tests.test_config:asgi_app", reload=True, reload_dirs=[])
|
||||
WatchFilesReload(config, target=run, sockets=[])
|
||||
mock_watch.assert_called_once()
|
||||
assert mock_watch.call_args[0] == (Path.cwd(),)
|
||||
|
||||
|
||||
@pytest.mark.skipif(WatchFilesReload is None, reason="watchfiles not available")
|
||||
def test_should_watch_multiple_dirs(mocker: MockerFixture, reload_directory_structure: Path):
|
||||
mock_watch = mocker.patch("uvicorn.supervisors.watchfilesreload.watch")
|
||||
app_dir = reload_directory_structure / "app"
|
||||
app_first_dir = reload_directory_structure / "app_first"
|
||||
config = Config(
|
||||
app="tests.test_config:asgi_app",
|
||||
reload=True,
|
||||
reload_dirs=[str(app_dir), str(app_first_dir)],
|
||||
)
|
||||
WatchFilesReload(config, target=run, sockets=[])
|
||||
mock_watch.assert_called_once()
|
||||
assert set(mock_watch.call_args[0]) == {
|
||||
app_dir,
|
||||
app_first_dir,
|
||||
}
|
||||
|
||||
|
||||
def test_display_path_relative(tmp_path: Path):
|
||||
with as_cwd(tmp_path):
|
||||
p = tmp_path / "app" / "foobar.py"
|
||||
# accept windows paths as wells as posix
|
||||
assert _display_path(p) in ("'app/foobar.py'", "'app\\foobar.py'")
|
||||
|
||||
|
||||
def test_display_path_non_relative():
|
||||
p = Path("/foo/bar.py")
|
||||
assert _display_path(p) in ("'/foo/bar.py'", "'\\foo\\bar.py'")
|
||||
|
||||
|
||||
def test_base_reloader_run(tmp_path: Path):
|
||||
calls: list[str] = []
|
||||
step = 0
|
||||
|
||||
class CustomReload(BaseReload):
|
||||
def startup(self):
|
||||
calls.append("startup")
|
||||
|
||||
def restart(self):
|
||||
calls.append("restart")
|
||||
|
||||
def shutdown(self):
|
||||
calls.append("shutdown")
|
||||
|
||||
def should_restart(self):
|
||||
nonlocal step
|
||||
step += 1
|
||||
if step == 1:
|
||||
return None
|
||||
elif step == 2:
|
||||
return [tmp_path / "foobar.py"]
|
||||
else:
|
||||
raise StopIteration()
|
||||
|
||||
config = Config(app="tests.test_config:asgi_app", reload=True)
|
||||
reloader = CustomReload(config, target=run, sockets=[])
|
||||
reloader.run()
|
||||
|
||||
assert calls == ["startup", "restart", "shutdown"]
|
||||
|
||||
|
||||
def test_base_reloader_should_exit(tmp_path: Path):
|
||||
config = Config(app="tests.test_config:asgi_app", reload=True)
|
||||
reloader = BaseReload(config, target=run, sockets=[])
|
||||
assert not reloader.should_exit.is_set()
|
||||
reloader.pause()
|
||||
|
||||
if sys.platform == "win32":
|
||||
reloader.signal_handler(signal.CTRL_C_EVENT, None) # pragma: py-not-win32
|
||||
else:
|
||||
reloader.signal_handler(signal.SIGINT, None) # pragma: py-win32
|
||||
|
||||
assert reloader.should_exit.is_set()
|
||||
with pytest.raises(StopIteration):
|
||||
reloader.pause()
|
||||
|
||||
|
||||
def test_base_reloader_closes_sockets_on_shutdown():
|
||||
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
|
||||
config = Config(app="tests.test_config:asgi_app", reload=True)
|
||||
reloader = BaseReload(config, target=run, sockets=[sock])
|
||||
reloader.startup()
|
||||
assert sock.fileno() != -1
|
||||
reloader.shutdown()
|
||||
assert sock.fileno() == -1
|
||||
|
||||
@ -1,104 +0,0 @@
|
||||
import asyncio
|
||||
import signal
|
||||
from asyncio import Event
|
||||
|
||||
import httpx
|
||||
import pytest
|
||||
|
||||
from tests.utils import assert_signal, run_server
|
||||
from uvicorn import Server
|
||||
from uvicorn.config import Config
|
||||
|
||||
|
||||
@pytest.mark.anyio
|
||||
async def test_sigint_finish_req(unused_tcp_port: int):
|
||||
"""
|
||||
1. Request is sent
|
||||
2. Sigint is sent to uvicorn
|
||||
3. Shutdown sequence start
|
||||
4. Request is finished before timeout_graceful_shutdown=1
|
||||
|
||||
Result: Request should go through, even though the server was cancelled.
|
||||
"""
|
||||
|
||||
server_event = Event()
|
||||
|
||||
async def wait_app(scope, receive, send):
|
||||
await send({"type": "http.response.start", "status": 200, "headers": []})
|
||||
await send({"type": "http.response.body", "body": b"start", "more_body": True})
|
||||
await server_event.wait()
|
||||
await send({"type": "http.response.body", "body": b"end", "more_body": False})
|
||||
|
||||
config = Config(app=wait_app, reload=False, port=unused_tcp_port, timeout_graceful_shutdown=1)
|
||||
server: Server
|
||||
with assert_signal(signal.SIGINT):
|
||||
async with run_server(config) as server, httpx.AsyncClient() as client:
|
||||
req = asyncio.create_task(client.get(f"http://127.0.0.1:{unused_tcp_port}"))
|
||||
await asyncio.sleep(0.1) # ensure next tick
|
||||
server.handle_exit(sig=signal.SIGINT, frame=None) # exit
|
||||
server_event.set() # continue request
|
||||
# ensure httpx has processed the response and result is complete
|
||||
await req
|
||||
assert req.result().status_code == 200
|
||||
await asyncio.sleep(0.1) # ensure shutdown is complete
|
||||
|
||||
|
||||
@pytest.mark.anyio
|
||||
async def test_sigint_abort_req(unused_tcp_port: int, caplog):
|
||||
"""
|
||||
1. Request is sent
|
||||
2. Sigint is sent to uvicorn
|
||||
3. Shutdown sequence start
|
||||
4. Request is _NOT_ finished before timeout_graceful_shutdown=1
|
||||
|
||||
Result: Request is cancelled mid-execution, and httpx will raise a
|
||||
`RemoteProtocolError`.
|
||||
"""
|
||||
|
||||
async def forever_app(scope, receive, send):
|
||||
server_event = Event()
|
||||
await send({"type": "http.response.start", "status": 200, "headers": []})
|
||||
await send({"type": "http.response.body", "body": b"start", "more_body": True})
|
||||
# we never continue this one, so this request will time out
|
||||
await server_event.wait()
|
||||
await send({"type": "http.response.body", "body": b"end", "more_body": False}) # pragma: full coverage
|
||||
|
||||
config = Config(app=forever_app, reload=False, port=unused_tcp_port, timeout_graceful_shutdown=1)
|
||||
server: Server
|
||||
with assert_signal(signal.SIGINT):
|
||||
async with run_server(config) as server, httpx.AsyncClient() as client:
|
||||
req = asyncio.create_task(client.get(f"http://127.0.0.1:{unused_tcp_port}"))
|
||||
await asyncio.sleep(0.1) # next tick
|
||||
# trigger exit, this request should time out in ~1 sec
|
||||
server.handle_exit(sig=signal.SIGINT, frame=None)
|
||||
with pytest.raises(httpx.RemoteProtocolError):
|
||||
await req
|
||||
|
||||
# req.result()
|
||||
assert "Cancel 1 running task(s), timeout graceful shutdown exceeded" in caplog.messages
|
||||
|
||||
|
||||
@pytest.mark.anyio
|
||||
async def test_sigint_deny_request_after_triggered(unused_tcp_port: int, caplog):
|
||||
"""
|
||||
1. Server is started
|
||||
2. Shutdown sequence start
|
||||
3. Request is sent, but not accepted
|
||||
|
||||
Result: Request should fail, and not be able to be sent, since server is no longer
|
||||
accepting connections.
|
||||
"""
|
||||
|
||||
async def app(scope, receive, send):
|
||||
await send({"type": "http.response.start", "status": 200, "headers": []})
|
||||
await asyncio.sleep(1) # pragma: full coverage
|
||||
|
||||
config = Config(app=app, reload=False, port=unused_tcp_port, timeout_graceful_shutdown=1)
|
||||
server: Server
|
||||
with assert_signal(signal.SIGINT):
|
||||
async with run_server(config) as server, httpx.AsyncClient() as client:
|
||||
# exit and ensure we do not accept more requests
|
||||
server.handle_exit(sig=signal.SIGINT, frame=None)
|
||||
await asyncio.sleep(0.1) # next tick
|
||||
with pytest.raises(httpx.ConnectError):
|
||||
await client.get(f"http://127.0.0.1:{unused_tcp_port}")
|
||||
@ -1,58 +1,55 @@
|
||||
import asyncio
|
||||
import contextlib
|
||||
import importlib
|
||||
|
||||
import pytest
|
||||
|
||||
from uvicorn.config import Config
|
||||
from uvicorn.loops.auto import auto_loop_factory
|
||||
from uvicorn.loops.auto import auto_loop_setup
|
||||
from uvicorn.main import ServerState
|
||||
from uvicorn.protocols.http.auto import AutoHTTPProtocol
|
||||
from uvicorn.protocols.websockets.auto import AutoWebSocketsProtocol
|
||||
from uvicorn.server import ServerState
|
||||
|
||||
try:
|
||||
importlib.import_module("uvloop")
|
||||
expected_loop = "uvloop" # pragma: py-win32
|
||||
except ImportError: # pragma: py-not-win32
|
||||
expected_loop = "asyncio"
|
||||
|
||||
try:
|
||||
importlib.import_module("httptools")
|
||||
expected_http = "HttpToolsProtocol"
|
||||
import uvloop
|
||||
except ImportError: # pragma: no cover
|
||||
expected_http = "H11Protocol"
|
||||
uvloop = None
|
||||
|
||||
try:
|
||||
importlib.import_module("websockets")
|
||||
expected_websockets = "WebSocketProtocol"
|
||||
import httptools
|
||||
except ImportError: # pragma: no cover
|
||||
expected_websockets = "WSProtocol"
|
||||
httptools = None
|
||||
|
||||
try:
|
||||
import websockets
|
||||
except ImportError: # pragma: no cover
|
||||
# Note that we skip the websocket tests completely in this case.
|
||||
websockets = None
|
||||
|
||||
|
||||
async def app(scope, receive, send):
|
||||
pass # pragma: no cover
|
||||
|
||||
|
||||
# TODO: Add pypy to our testing matrix, and assert we get the correct classes
|
||||
# dependent on the platform we're running the tests under.
|
||||
|
||||
|
||||
def test_loop_auto():
|
||||
loop_factory = auto_loop_factory(use_subprocess=True)
|
||||
with contextlib.closing(loop_factory()) as loop:
|
||||
assert isinstance(loop, asyncio.AbstractEventLoop)
|
||||
assert type(loop).__module__.startswith(expected_loop)
|
||||
auto_loop_setup()
|
||||
policy = asyncio.get_event_loop_policy()
|
||||
assert isinstance(policy, asyncio.events.BaseDefaultEventLoopPolicy)
|
||||
expected_loop = "asyncio" if uvloop is None else "uvloop"
|
||||
assert type(policy).__module__.startswith(expected_loop)
|
||||
|
||||
|
||||
@pytest.mark.anyio
|
||||
async def test_http_auto():
|
||||
def test_http_auto():
|
||||
config = Config(app=app)
|
||||
server_state = ServerState()
|
||||
protocol = AutoHTTPProtocol(config=config, server_state=server_state, app_state={})
|
||||
protocol = AutoHTTPProtocol(config=config, server_state=server_state)
|
||||
expected_http = "H11Protocol" if httptools is None else "HttpToolsProtocol"
|
||||
assert type(protocol).__name__ == expected_http
|
||||
|
||||
|
||||
@pytest.mark.anyio
|
||||
async def test_websocket_auto():
|
||||
def test_websocket_auto():
|
||||
config = Config(app=app)
|
||||
server_state = ServerState()
|
||||
|
||||
assert AutoWebSocketsProtocol is not None
|
||||
protocol = AutoWebSocketsProtocol(config=config, server_state=server_state, app_state={})
|
||||
protocol = AutoWebSocketsProtocol(config=config, server_state=server_state)
|
||||
expected_websockets = "WSProtocol" if websockets is None else "WebSocketProtocol"
|
||||
assert type(protocol).__name__ == expected_websockets
|
||||
|
||||
@ -1,56 +1,15 @@
|
||||
import contextlib
|
||||
import importlib
|
||||
import os
|
||||
import platform
|
||||
import sys
|
||||
from collections.abc import Iterator
|
||||
from pathlib import Path
|
||||
from textwrap import dedent
|
||||
from unittest import mock
|
||||
|
||||
import pytest
|
||||
from click.testing import CliRunner
|
||||
|
||||
import uvicorn
|
||||
from uvicorn.config import Config
|
||||
from uvicorn.main import main as cli
|
||||
from uvicorn.server import Server
|
||||
from uvicorn.supervisors import ChangeReload, Multiprocess
|
||||
|
||||
HEADERS = "Content-Security-Policy:default-src 'self'; script-src https://example.com"
|
||||
main = importlib.import_module("uvicorn.main")
|
||||
|
||||
|
||||
@contextlib.contextmanager
|
||||
def load_env_var(key: str, value: str) -> Iterator[None]:
|
||||
old_environ = dict(os.environ)
|
||||
os.environ[key] = value
|
||||
yield
|
||||
os.environ.clear()
|
||||
os.environ.update(old_environ)
|
||||
|
||||
|
||||
class App:
|
||||
pass
|
||||
|
||||
|
||||
def test_cli_print_version() -> None:
|
||||
runner = CliRunner()
|
||||
|
||||
result = runner.invoke(cli, ["--version"])
|
||||
|
||||
assert result.exit_code == 0
|
||||
assert (
|
||||
"Running uvicorn {version} with {py_implementation} {py_version} on {system}".format( # noqa: UP032
|
||||
version=uvicorn.__version__,
|
||||
py_implementation=platform.python_implementation(),
|
||||
py_version=platform.python_version(),
|
||||
system=platform.system(),
|
||||
)
|
||||
) in result.output
|
||||
|
||||
|
||||
def test_cli_headers() -> None:
|
||||
def test_cli_headers():
|
||||
runner = CliRunner()
|
||||
|
||||
with mock.patch.object(main, "run") as mock_run:
|
||||
@ -67,137 +26,5 @@ def test_cli_headers() -> None:
|
||||
]
|
||||
|
||||
|
||||
def test_cli_call_server_run() -> None:
|
||||
runner = CliRunner()
|
||||
|
||||
with mock.patch.object(Server, "run") as mock_run:
|
||||
result = runner.invoke(cli, ["tests.test_cli:App"])
|
||||
|
||||
assert result.exit_code == 3
|
||||
mock_run.assert_called_once()
|
||||
|
||||
|
||||
def test_cli_call_change_reload_run() -> None:
|
||||
runner = CliRunner()
|
||||
|
||||
with mock.patch.object(Config, "bind_socket") as mock_bind_socket:
|
||||
with mock.patch.object(ChangeReload, "run") as mock_run:
|
||||
result = runner.invoke(cli, ["tests.test_cli:App", "--reload"])
|
||||
|
||||
assert result.exit_code == 0
|
||||
mock_bind_socket.assert_called_once()
|
||||
mock_run.assert_called_once()
|
||||
|
||||
|
||||
def test_cli_call_multiprocess_run() -> None:
|
||||
runner = CliRunner()
|
||||
|
||||
with mock.patch.object(Config, "bind_socket") as mock_bind_socket:
|
||||
with mock.patch.object(Multiprocess, "run") as mock_run:
|
||||
result = runner.invoke(cli, ["tests.test_cli:App", "--workers=2"])
|
||||
|
||||
assert result.exit_code == 0
|
||||
mock_bind_socket.assert_called_once()
|
||||
mock_run.assert_called_once()
|
||||
|
||||
|
||||
@pytest.fixture(params=(True, False))
|
||||
def uds_file(tmp_path: Path, request: pytest.FixtureRequest) -> Path: # pragma: py-win32
|
||||
file = tmp_path / "uvicorn.sock"
|
||||
should_create_file = request.param
|
||||
if should_create_file:
|
||||
file.touch(exist_ok=True)
|
||||
return file
|
||||
|
||||
|
||||
@pytest.mark.skipif(sys.platform == "win32", reason="require unix-like system")
|
||||
def test_cli_uds(uds_file: Path) -> None: # pragma: py-win32
|
||||
runner = CliRunner()
|
||||
|
||||
with mock.patch.object(Config, "bind_socket") as mock_bind_socket:
|
||||
with mock.patch.object(Multiprocess, "run") as mock_run:
|
||||
result = runner.invoke(cli, ["tests.test_cli:App", "--workers=2", "--uds", str(uds_file)])
|
||||
|
||||
assert result.exit_code == 0
|
||||
assert result.output == ""
|
||||
mock_bind_socket.assert_called_once()
|
||||
mock_run.assert_called_once()
|
||||
assert not uds_file.exists()
|
||||
|
||||
|
||||
def test_cli_incomplete_app_parameter() -> None:
|
||||
runner = CliRunner()
|
||||
|
||||
result = runner.invoke(cli, ["tests.test_cli"])
|
||||
|
||||
assert (
|
||||
'Error loading ASGI app. Import string "tests.test_cli" must be in format "<module>:<attribute>".'
|
||||
) in result.output
|
||||
assert result.exit_code == 1
|
||||
|
||||
|
||||
def test_cli_event_size() -> None:
|
||||
runner = CliRunner()
|
||||
|
||||
with mock.patch.object(main, "run") as mock_run:
|
||||
result = runner.invoke(
|
||||
cli,
|
||||
["tests.test_cli:App", "--h11-max-incomplete-event-size", str(32 * 1024)],
|
||||
)
|
||||
|
||||
assert result.output == ""
|
||||
assert result.exit_code == 0
|
||||
mock_run.assert_called_once()
|
||||
assert mock_run.call_args[1]["h11_max_incomplete_event_size"] == 32768
|
||||
|
||||
|
||||
@pytest.mark.parametrize("http_protocol", ["h11", "httptools"])
|
||||
def test_env_variables(http_protocol: str):
|
||||
with load_env_var("UVICORN_HTTP", http_protocol):
|
||||
runner = CliRunner(env=os.environ)
|
||||
with mock.patch.object(main, "run") as mock_run:
|
||||
runner.invoke(cli, ["tests.test_cli:App"])
|
||||
_, kwargs = mock_run.call_args
|
||||
assert kwargs["http"] == http_protocol
|
||||
|
||||
|
||||
def test_ignore_environment_variable_when_set_on_cli():
|
||||
with load_env_var("UVICORN_HTTP", "h11"):
|
||||
runner = CliRunner(env=os.environ)
|
||||
with mock.patch.object(main, "run") as mock_run:
|
||||
runner.invoke(cli, ["tests.test_cli:App", "--http=httptools"])
|
||||
_, kwargs = mock_run.call_args
|
||||
assert kwargs["http"] == "httptools"
|
||||
|
||||
|
||||
def test_app_dir(tmp_path: Path, caplog: pytest.LogCaptureFixture) -> None:
|
||||
app_dir = tmp_path / "dir" / "app_dir"
|
||||
app_file = app_dir / "main.py"
|
||||
app_dir.mkdir(parents=True)
|
||||
app_file.touch()
|
||||
app_file.write_text(
|
||||
dedent(
|
||||
"""
|
||||
async def app(scope, receive, send):
|
||||
...
|
||||
"""
|
||||
)
|
||||
)
|
||||
runner = CliRunner()
|
||||
with mock.patch.object(Server, "run") as mock_run:
|
||||
result = runner.invoke(cli, ["main:app", "--app-dir", f"{str(app_dir)}"])
|
||||
|
||||
assert result.exit_code == 3
|
||||
mock_run.assert_called_once()
|
||||
assert sys.path[0] == str(app_dir)
|
||||
|
||||
|
||||
def test_set_app_via_environment_variable():
|
||||
app_path = "tests.test_cli:App"
|
||||
with load_env_var("UVICORN_APP", app_path):
|
||||
runner = CliRunner(env=os.environ)
|
||||
with mock.patch.object(main, "run") as mock_run:
|
||||
result = runner.invoke(cli)
|
||||
args, _ = mock_run.call_args
|
||||
assert result.exit_code == 0
|
||||
assert args == (app_path,)
|
||||
class App:
|
||||
pass
|
||||
|
||||
28
tests/test_client.py
Normal file
28
tests/test_client.py
Normal file
@ -0,0 +1,28 @@
|
||||
from tests.client import TestClient
|
||||
|
||||
|
||||
async def hello_world(scope, receive, send):
|
||||
await send(
|
||||
{
|
||||
"type": "http.response.start",
|
||||
"status": 200,
|
||||
"headers": [(b"content-type", b"text/plain")],
|
||||
}
|
||||
)
|
||||
await send(
|
||||
{"type": "http.response.body", "body": b"hello, world", "more_body": False}
|
||||
)
|
||||
|
||||
|
||||
def test_explicit_base_url():
|
||||
client = TestClient(hello_world, base_url="http://testserver:321")
|
||||
response = client.get("/")
|
||||
assert response.status_code == 200
|
||||
assert response.text == "hello, world"
|
||||
|
||||
|
||||
def test_explicit_host():
|
||||
client = TestClient(hello_world)
|
||||
response = client.get("/", headers={"host": "example.org"})
|
||||
assert response.status_code == 200
|
||||
assert response.text == "hello, world"
|
||||
@ -1,28 +0,0 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
from asyncio import AbstractEventLoop
|
||||
|
||||
import pytest
|
||||
|
||||
from tests.custom_loop_utils import CustomLoop
|
||||
from tests.utils import get_asyncio_default_loop_per_os
|
||||
from uvicorn._compat import asyncio_run
|
||||
|
||||
|
||||
async def assert_event_loop(expected_loop_class: type[AbstractEventLoop]):
|
||||
assert isinstance(asyncio.get_running_loop(), expected_loop_class)
|
||||
|
||||
|
||||
def test_asyncio_run__default_loop_factory() -> None:
|
||||
asyncio_run(assert_event_loop(get_asyncio_default_loop_per_os()), loop_factory=None)
|
||||
|
||||
|
||||
def test_asyncio_run__custom_loop_factory() -> None:
|
||||
asyncio_run(assert_event_loop(CustomLoop), loop_factory=CustomLoop)
|
||||
|
||||
|
||||
def test_asyncio_run__passing_a_non_awaitable_callback_should_throw_error() -> None:
|
||||
# TypeError on Python >= 3.14
|
||||
with pytest.raises((ValueError, TypeError)):
|
||||
asyncio_run(lambda: None, loop_factory=CustomLoop) # type: ignore
|
||||
@ -1,194 +1,54 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import configparser
|
||||
import io
|
||||
import json
|
||||
import logging
|
||||
import os
|
||||
import socket
|
||||
import sys
|
||||
from collections.abc import Callable, Iterator
|
||||
from contextlib import closing
|
||||
from pathlib import Path
|
||||
from typing import IO, Any, Literal
|
||||
from unittest.mock import MagicMock
|
||||
from copy import deepcopy
|
||||
|
||||
import pytest
|
||||
import yaml
|
||||
from pytest_mock import MockerFixture
|
||||
|
||||
from tests.custom_loop_utils import CustomLoop
|
||||
from tests.utils import as_cwd, get_asyncio_default_loop_per_os
|
||||
from uvicorn._types import ASGIApplication, ASGIReceiveCallable, ASGISendCallable, Environ, Scope, StartResponse
|
||||
from uvicorn.config import Config, LoopFactoryType
|
||||
from uvicorn.config import LOGGING_CONFIG, Config
|
||||
from uvicorn.middleware.debug import DebugMiddleware
|
||||
from uvicorn.middleware.proxy_headers import ProxyHeadersMiddleware
|
||||
from uvicorn.middleware.wsgi import WSGIMiddleware
|
||||
from uvicorn.protocols.http.h11_impl import H11Protocol
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def mocked_logging_config_module(mocker: MockerFixture) -> MagicMock:
|
||||
def mocked_logging_config_module(mocker):
|
||||
return mocker.patch("logging.config")
|
||||
|
||||
|
||||
@pytest.fixture(scope="function")
|
||||
def logging_config():
|
||||
return deepcopy(LOGGING_CONFIG)
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def json_logging_config(logging_config: dict) -> str:
|
||||
def json_logging_config(logging_config):
|
||||
return json.dumps(logging_config)
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def yaml_logging_config(logging_config: dict) -> str:
|
||||
def yaml_logging_config(logging_config):
|
||||
return yaml.dump(logging_config)
|
||||
|
||||
|
||||
async def asgi_app(scope: Scope, receive: ASGIReceiveCallable, send: ASGISendCallable) -> None:
|
||||
async def asgi_app(scope, receive, send):
|
||||
pass # pragma: nocover
|
||||
|
||||
|
||||
def wsgi_app(environ: Environ, start_response: StartResponse) -> None:
|
||||
def wsgi_app(environ, start_response):
|
||||
pass # pragma: nocover
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"app, expected_should_reload",
|
||||
[(asgi_app, False), ("tests.test_config:asgi_app", True)],
|
||||
)
|
||||
def test_config_should_reload_is_set(app: ASGIApplication, expected_should_reload: bool) -> None:
|
||||
config = Config(app=app, reload=True)
|
||||
assert config.reload is True
|
||||
assert config.should_reload is expected_should_reload
|
||||
def test_debug_app():
|
||||
config = Config(app=asgi_app, debug=True, proxy_headers=False)
|
||||
config.load()
|
||||
|
||||
assert config.debug is True
|
||||
assert isinstance(config.loaded_app, DebugMiddleware)
|
||||
|
||||
|
||||
def test_should_warn_on_invalid_reload_configuration(tmp_path: Path, caplog: pytest.LogCaptureFixture) -> None:
|
||||
config_class = Config(app=asgi_app, reload_dirs=[str(tmp_path)])
|
||||
assert not config_class.should_reload
|
||||
assert len(caplog.records) == 1
|
||||
assert (
|
||||
caplog.records[-1].message == "Current configuration will not reload as not all conditions are met, "
|
||||
"please refer to documentation."
|
||||
)
|
||||
|
||||
config_no_reload = Config(app="tests.test_config:asgi_app", reload_dirs=[str(tmp_path)])
|
||||
assert not config_no_reload.should_reload
|
||||
assert len(caplog.records) == 2
|
||||
assert (
|
||||
caplog.records[-1].message == "Current configuration will not reload as not all conditions are met, "
|
||||
"please refer to documentation."
|
||||
)
|
||||
|
||||
|
||||
def test_reload_dir_is_set(reload_directory_structure: Path, caplog: pytest.LogCaptureFixture) -> None:
|
||||
app_dir = reload_directory_structure / "app"
|
||||
with caplog.at_level(logging.INFO):
|
||||
config = Config(app="tests.test_config:asgi_app", reload=True, reload_dirs=[str(app_dir)])
|
||||
assert len(caplog.records) == 1
|
||||
assert caplog.records[-1].message == f"Will watch for changes in these directories: {[str(app_dir)]}"
|
||||
assert config.reload_dirs == [app_dir]
|
||||
config = Config(app="tests.test_config:asgi_app", reload=True, reload_dirs=str(app_dir))
|
||||
assert config.reload_dirs == [app_dir]
|
||||
|
||||
|
||||
def test_non_existant_reload_dir_is_not_set(reload_directory_structure: Path, caplog: pytest.LogCaptureFixture) -> None:
|
||||
with as_cwd(reload_directory_structure), caplog.at_level(logging.WARNING):
|
||||
config = Config(app="tests.test_config:asgi_app", reload=True, reload_dirs=["reload"])
|
||||
assert config.reload_dirs == [reload_directory_structure]
|
||||
assert (
|
||||
caplog.records[-1].message
|
||||
== "Provided reload directories ['reload'] did not contain valid "
|
||||
+ "directories, watching current working directory."
|
||||
)
|
||||
|
||||
|
||||
def test_reload_subdir_removal(reload_directory_structure: Path) -> None:
|
||||
app_dir = reload_directory_structure / "app"
|
||||
|
||||
reload_dirs = [str(reload_directory_structure), "app", str(app_dir)]
|
||||
|
||||
with as_cwd(reload_directory_structure):
|
||||
config = Config(app="tests.test_config:asgi_app", reload=True, reload_dirs=reload_dirs)
|
||||
assert config.reload_dirs == [reload_directory_structure]
|
||||
|
||||
|
||||
def test_reload_included_dir_is_added_to_reload_dirs(
|
||||
reload_directory_structure: Path,
|
||||
) -> None:
|
||||
app_dir = reload_directory_structure / "app"
|
||||
ext_dir = reload_directory_structure / "ext"
|
||||
|
||||
with as_cwd(reload_directory_structure):
|
||||
config = Config(
|
||||
app="tests.test_config:asgi_app",
|
||||
reload=True,
|
||||
reload_dirs=[str(app_dir)],
|
||||
reload_includes=["*.js", str(ext_dir)],
|
||||
)
|
||||
assert frozenset(config.reload_dirs), frozenset([app_dir, ext_dir])
|
||||
assert frozenset(config.reload_includes) == frozenset(["*.js", str(ext_dir)])
|
||||
|
||||
|
||||
def test_reload_dir_subdirectories_are_removed(
|
||||
reload_directory_structure: Path,
|
||||
) -> None:
|
||||
app_dir = reload_directory_structure / "app"
|
||||
app_sub_dir = app_dir / "sub"
|
||||
ext_dir = reload_directory_structure / "ext"
|
||||
ext_sub_dir = ext_dir / "sub"
|
||||
|
||||
with as_cwd(reload_directory_structure):
|
||||
config = Config(
|
||||
app="tests.test_config:asgi_app",
|
||||
reload=True,
|
||||
reload_dirs=[
|
||||
str(app_dir),
|
||||
str(app_sub_dir),
|
||||
str(ext_sub_dir),
|
||||
str(ext_dir),
|
||||
],
|
||||
)
|
||||
assert frozenset(config.reload_dirs) == frozenset([app_dir, ext_dir])
|
||||
|
||||
|
||||
def test_reload_excluded_subdirectories_are_removed(
|
||||
reload_directory_structure: Path,
|
||||
) -> None:
|
||||
app_dir = reload_directory_structure / "app"
|
||||
app_sub_dir = app_dir / "sub"
|
||||
|
||||
with as_cwd(reload_directory_structure):
|
||||
config = Config(
|
||||
app="tests.test_config:asgi_app",
|
||||
reload=True,
|
||||
reload_excludes=[str(app_dir), str(app_sub_dir)],
|
||||
)
|
||||
assert frozenset(config.reload_dirs) == frozenset([reload_directory_structure])
|
||||
assert frozenset(config.reload_dirs_excludes) == frozenset([app_dir])
|
||||
assert frozenset(config.reload_excludes) == frozenset([str(app_dir), str(app_sub_dir)])
|
||||
|
||||
|
||||
def test_reload_includes_exclude_dir_patterns_are_matched(
|
||||
reload_directory_structure: Path, caplog: pytest.LogCaptureFixture
|
||||
) -> None:
|
||||
with caplog.at_level(logging.INFO):
|
||||
first_app_dir = reload_directory_structure / "app_first" / "src"
|
||||
second_app_dir = reload_directory_structure / "app_second" / "src"
|
||||
|
||||
with as_cwd(reload_directory_structure):
|
||||
config = Config(
|
||||
app="tests.test_config:asgi_app",
|
||||
reload=True,
|
||||
reload_includes=["*/src"],
|
||||
reload_excludes=["app", "*third*"],
|
||||
)
|
||||
assert len(caplog.records) == 1
|
||||
assert (
|
||||
caplog.records[-1].message == "Will watch for changes in these directories: "
|
||||
f"{sorted([str(first_app_dir), str(second_app_dir)])}"
|
||||
)
|
||||
assert frozenset(config.reload_dirs) == frozenset([first_app_dir, second_app_dir])
|
||||
assert config.reload_includes == ["*/src"]
|
||||
|
||||
|
||||
def test_wsgi_app() -> None:
|
||||
def test_wsgi_app():
|
||||
config = Config(app=wsgi_app, interface="wsgi", proxy_headers=False)
|
||||
config.load()
|
||||
|
||||
@ -197,7 +57,7 @@ def test_wsgi_app() -> None:
|
||||
assert config.asgi_version == "3.0"
|
||||
|
||||
|
||||
def test_proxy_headers() -> None:
|
||||
def test_proxy_headers():
|
||||
config = Config(app=asgi_app)
|
||||
config.load()
|
||||
|
||||
@ -205,42 +65,24 @@ def test_proxy_headers() -> None:
|
||||
assert isinstance(config.loaded_app, ProxyHeadersMiddleware)
|
||||
|
||||
|
||||
def test_app_unimportable_module() -> None:
|
||||
def test_app_unimportable():
|
||||
config = Config(app="no.such:app")
|
||||
with pytest.raises(ImportError):
|
||||
config.load()
|
||||
|
||||
|
||||
def test_app_unimportable_other(caplog: pytest.LogCaptureFixture) -> None:
|
||||
config = Config(app="tests.test_config:app")
|
||||
with pytest.raises(SystemExit):
|
||||
config.load()
|
||||
error_messages = [
|
||||
record.message for record in caplog.records if record.name == "uvicorn.error" and record.levelname == "ERROR"
|
||||
]
|
||||
assert (
|
||||
'Error loading ASGI app. Attribute "app" not found in module "tests.test_config".' # noqa: E501
|
||||
== error_messages.pop(0)
|
||||
)
|
||||
|
||||
|
||||
def test_app_factory(caplog: pytest.LogCaptureFixture) -> None:
|
||||
def create_app() -> ASGIApplication:
|
||||
def test_app_factory():
|
||||
def create_app():
|
||||
return asgi_app
|
||||
|
||||
config = Config(app=create_app, factory=True, proxy_headers=False)
|
||||
config.load()
|
||||
assert config.loaded_app is asgi_app
|
||||
|
||||
# Flag not passed. In this case, successfully load the app, but issue a warning
|
||||
# to indicate that an explicit flag is preferred.
|
||||
caplog.clear()
|
||||
config = Config(app=create_app, proxy_headers=False)
|
||||
with caplog.at_level(logging.WARNING):
|
||||
# Flag missing.
|
||||
config = Config(app=create_app)
|
||||
with pytest.raises(SystemExit):
|
||||
config.load()
|
||||
assert config.loaded_app is asgi_app
|
||||
assert len(caplog.records) == 1
|
||||
assert "--factory" in caplog.records[0].message
|
||||
|
||||
# App not a no-arguments callable.
|
||||
config = Config(app=asgi_app, factory=True)
|
||||
@ -248,24 +90,20 @@ def test_app_factory(caplog: pytest.LogCaptureFixture) -> None:
|
||||
config.load()
|
||||
|
||||
|
||||
def test_concrete_http_class() -> None:
|
||||
def test_concrete_http_class():
|
||||
config = Config(app=asgi_app, http=H11Protocol)
|
||||
config.load()
|
||||
assert config.http_protocol_class is H11Protocol
|
||||
|
||||
|
||||
def test_socket_bind() -> None:
|
||||
def test_socket_bind():
|
||||
config = Config(app=asgi_app)
|
||||
config.load()
|
||||
sock = config.bind_socket()
|
||||
assert isinstance(sock, socket.socket)
|
||||
sock.close()
|
||||
|
||||
assert isinstance(config.bind_socket(), socket.socket)
|
||||
|
||||
|
||||
def test_ssl_config(
|
||||
tls_ca_certificate_pem_path: str,
|
||||
tls_ca_certificate_private_key_path: str,
|
||||
) -> None:
|
||||
def test_ssl_config(tls_ca_certificate_pem_path, tls_ca_certificate_private_key_path):
|
||||
config = Config(
|
||||
app=asgi_app,
|
||||
ssl_certfile=tls_ca_certificate_pem_path,
|
||||
@ -276,25 +114,27 @@ def test_ssl_config(
|
||||
assert config.is_ssl is True
|
||||
|
||||
|
||||
def test_ssl_config_combined(tls_certificate_key_and_chain_path: str) -> None:
|
||||
def test_ssl_config_combined(tls_certificate_pem_path):
|
||||
config = Config(
|
||||
app=asgi_app,
|
||||
ssl_certfile=tls_certificate_key_and_chain_path,
|
||||
ssl_certfile=tls_certificate_pem_path,
|
||||
)
|
||||
config.load()
|
||||
|
||||
assert config.is_ssl is True
|
||||
|
||||
|
||||
def asgi2_app(scope: Scope) -> Callable:
|
||||
async def asgi(receive: ASGIReceiveCallable, send: ASGISendCallable) -> None: # pragma: nocover
|
||||
def asgi2_app(scope):
|
||||
async def asgi(receive, send):
|
||||
pass
|
||||
|
||||
return asgi # pragma: nocover
|
||||
return asgi
|
||||
|
||||
|
||||
@pytest.mark.parametrize("app, expected_interface", [(asgi_app, "3.0"), (asgi2_app, "2.0")])
|
||||
def test_asgi_version(app: ASGIApplication, expected_interface: Literal["2.0", "3.0"]) -> None:
|
||||
@pytest.mark.parametrize(
|
||||
"app, expected_interface", [(asgi_app, "3.0"), (asgi2_app, "2.0")]
|
||||
)
|
||||
def test_asgi_version(app, expected_interface):
|
||||
config = Config(app=app)
|
||||
config.load()
|
||||
assert config.asgi_version == expected_interface
|
||||
@ -309,35 +149,29 @@ def test_asgi_version(app: ASGIApplication, expected_interface: Literal["2.0", "
|
||||
pytest.param(False, False, id="use_colors_disabled"),
|
||||
],
|
||||
)
|
||||
def test_log_config_default(
|
||||
mocked_logging_config_module: MagicMock,
|
||||
use_colors: bool | None,
|
||||
expected: bool | None,
|
||||
logging_config: dict[str, Any],
|
||||
) -> None:
|
||||
def test_log_config_default(mocked_logging_config_module, use_colors, expected):
|
||||
"""
|
||||
Test that one can specify the use_colors option when using the default logging
|
||||
config.
|
||||
"""
|
||||
config = Config(app=asgi_app, use_colors=use_colors, log_config=logging_config)
|
||||
config = Config(app=asgi_app, use_colors=use_colors)
|
||||
config.load()
|
||||
|
||||
mocked_logging_config_module.dictConfig.assert_called_once_with(logging_config)
|
||||
mocked_logging_config_module.dictConfig.assert_called_once_with(LOGGING_CONFIG)
|
||||
|
||||
(provided_dict_config,), _ = mocked_logging_config_module.dictConfig.call_args
|
||||
assert provided_dict_config["formatters"]["default"]["use_colors"] == expected
|
||||
|
||||
|
||||
def test_log_config_json(
|
||||
mocked_logging_config_module: MagicMock,
|
||||
logging_config: dict[str, Any],
|
||||
json_logging_config: str,
|
||||
mocker: MockerFixture,
|
||||
) -> None:
|
||||
mocked_logging_config_module, logging_config, json_logging_config, mocker
|
||||
):
|
||||
"""
|
||||
Test that one can load a json config from disk.
|
||||
"""
|
||||
mocked_open = mocker.patch("uvicorn.config.open", mocker.mock_open(read_data=json_logging_config))
|
||||
mocked_open = mocker.patch(
|
||||
"uvicorn.config.open", mocker.mock_open(read_data=json_logging_config)
|
||||
)
|
||||
|
||||
config = Config(app=asgi_app, log_config="log_config.json")
|
||||
config.load()
|
||||
@ -348,16 +182,18 @@ def test_log_config_json(
|
||||
|
||||
@pytest.mark.parametrize("config_filename", ["log_config.yml", "log_config.yaml"])
|
||||
def test_log_config_yaml(
|
||||
mocked_logging_config_module: MagicMock,
|
||||
logging_config: dict[str, Any],
|
||||
yaml_logging_config: str,
|
||||
mocker: MockerFixture,
|
||||
config_filename: str,
|
||||
) -> None:
|
||||
mocked_logging_config_module,
|
||||
logging_config,
|
||||
yaml_logging_config,
|
||||
mocker,
|
||||
config_filename,
|
||||
):
|
||||
"""
|
||||
Test that one can load a yaml config from disk.
|
||||
"""
|
||||
mocked_open = mocker.patch("uvicorn.config.open", mocker.mock_open(read_data=yaml_logging_config))
|
||||
mocked_open = mocker.patch(
|
||||
"uvicorn.config.open", mocker.mock_open(read_data=yaml_logging_config)
|
||||
)
|
||||
|
||||
config = Config(app=asgi_app, log_config=config_filename)
|
||||
config.load()
|
||||
@ -366,297 +202,13 @@ def test_log_config_yaml(
|
||||
mocked_logging_config_module.dictConfig.assert_called_once_with(logging_config)
|
||||
|
||||
|
||||
def test_log_config_yaml_missing_pyyaml(mocked_logging_config_module: MagicMock, mocker: MockerFixture) -> None:
|
||||
"""
|
||||
Test that a helpful error is raised when PyYAML is not installed.
|
||||
"""
|
||||
mocker.patch.dict(sys.modules, {"yaml": None})
|
||||
with pytest.raises(ImportError, match=r"Install the PyYAML package or uvicorn\[standard\]"):
|
||||
Config(app=asgi_app, log_config="log_config.yaml")
|
||||
|
||||
|
||||
def test_log_config_pathlike(
|
||||
mocked_logging_config_module: MagicMock,
|
||||
logging_config: dict[str, Any],
|
||||
json_logging_config: str,
|
||||
mocker: MockerFixture,
|
||||
tmp_path: Path,
|
||||
) -> None:
|
||||
"""
|
||||
Test that one can pass a `os.PathLike` (e.g. `pathlib.Path`) as the log config path.
|
||||
"""
|
||||
path = tmp_path / "log_config.json"
|
||||
mocked_open = mocker.patch("uvicorn.config.open", mocker.mock_open(read_data=json_logging_config))
|
||||
|
||||
config = Config(app=asgi_app, log_config=path)
|
||||
config.load()
|
||||
|
||||
mocked_open.assert_called_once_with(os.fspath(path))
|
||||
mocked_logging_config_module.dictConfig.assert_called_once_with(logging_config)
|
||||
|
||||
|
||||
@pytest.mark.parametrize("config_file", ["log_config.ini", configparser.ConfigParser(), io.StringIO()])
|
||||
def test_log_config_file(
|
||||
mocked_logging_config_module: MagicMock,
|
||||
config_file: str | configparser.RawConfigParser | IO[Any],
|
||||
) -> None:
|
||||
def test_log_config_file(mocked_logging_config_module):
|
||||
"""
|
||||
Test that one can load a configparser config from disk.
|
||||
"""
|
||||
config = Config(app=asgi_app, log_config=config_file)
|
||||
config = Config(app=asgi_app, log_config="log_config")
|
||||
config.load()
|
||||
|
||||
mocked_logging_config_module.fileConfig.assert_called_once_with(config_file, disable_existing_loggers=False)
|
||||
|
||||
|
||||
@pytest.fixture(params=[0, 1])
|
||||
def web_concurrency(request: pytest.FixtureRequest) -> Iterator[int]:
|
||||
yield request.param
|
||||
if os.getenv("WEB_CONCURRENCY"):
|
||||
del os.environ["WEB_CONCURRENCY"]
|
||||
|
||||
|
||||
@pytest.fixture(params=["127.0.0.1", "127.0.0.2"])
|
||||
def forwarded_allow_ips(request: pytest.FixtureRequest) -> Iterator[str]:
|
||||
yield request.param
|
||||
if os.getenv("FORWARDED_ALLOW_IPS"):
|
||||
del os.environ["FORWARDED_ALLOW_IPS"]
|
||||
|
||||
|
||||
def test_env_file(
|
||||
web_concurrency: int,
|
||||
forwarded_allow_ips: str,
|
||||
caplog: pytest.LogCaptureFixture,
|
||||
tmp_path: Path,
|
||||
) -> None:
|
||||
"""
|
||||
Test that one can load environment variables using an env file.
|
||||
"""
|
||||
fp = tmp_path / ".env"
|
||||
content = f"WEB_CONCURRENCY={web_concurrency}\nFORWARDED_ALLOW_IPS={forwarded_allow_ips}\n"
|
||||
fp.write_text(content)
|
||||
with caplog.at_level(logging.INFO):
|
||||
config = Config(app=asgi_app, env_file=fp)
|
||||
config.load()
|
||||
|
||||
assert config.workers == int(str(os.getenv("WEB_CONCURRENCY")))
|
||||
assert config.forwarded_allow_ips == os.getenv("FORWARDED_ALLOW_IPS")
|
||||
assert len(caplog.records) == 1
|
||||
assert f"Loading environment from '{fp}'" in caplog.records[0].message
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"access_log, handlers",
|
||||
[
|
||||
pytest.param(True, 1, id="access log enabled should have single handler"),
|
||||
pytest.param(False, 0, id="access log disabled shouldn't have handlers"),
|
||||
],
|
||||
)
|
||||
def test_config_access_log(access_log: bool, handlers: int) -> None:
|
||||
config = Config(app=asgi_app, access_log=access_log)
|
||||
config.load()
|
||||
|
||||
assert len(logging.getLogger("uvicorn.access").handlers) == handlers
|
||||
assert config.access_log == access_log
|
||||
|
||||
|
||||
@pytest.mark.parametrize("log_level", [5, 10, 20, 30, 40, 50])
|
||||
def test_config_log_level(log_level: int) -> None:
|
||||
config = Config(app=asgi_app, log_level=log_level)
|
||||
config.load()
|
||||
|
||||
assert logging.getLogger("uvicorn.error").level == log_level
|
||||
assert logging.getLogger("uvicorn.access").level == log_level
|
||||
assert logging.getLogger("uvicorn.asgi").level == log_level
|
||||
assert config.log_level == log_level
|
||||
|
||||
|
||||
@pytest.mark.parametrize("log_level", [None, 0, 5, 10, 20, 30, 40, 50])
|
||||
@pytest.mark.parametrize("uvicorn_logger_level", [0, 5, 10, 20, 30, 40, 50])
|
||||
def test_config_log_effective_level(log_level: int, uvicorn_logger_level: int) -> None:
|
||||
default_level = 30
|
||||
log_config = {
|
||||
"version": 1,
|
||||
"disable_existing_loggers": False,
|
||||
"loggers": {
|
||||
"uvicorn": {"level": uvicorn_logger_level},
|
||||
},
|
||||
}
|
||||
config = Config(app=asgi_app, log_level=log_level, log_config=log_config)
|
||||
config.load()
|
||||
|
||||
effective_level = log_level or uvicorn_logger_level or default_level
|
||||
assert logging.getLogger("uvicorn.error").getEffectiveLevel() == effective_level
|
||||
assert logging.getLogger("uvicorn.access").getEffectiveLevel() == effective_level
|
||||
assert logging.getLogger("uvicorn.asgi").getEffectiveLevel() == effective_level
|
||||
|
||||
|
||||
@pytest.mark.parametrize("log_level", ["INFO", "Info", "info"])
|
||||
def test_config_log_level_case_insensitive(log_level: str) -> None:
|
||||
config = Config(app=asgi_app, log_level=log_level)
|
||||
config.load()
|
||||
assert logging.getLogger("uvicorn.error").level == logging.INFO
|
||||
|
||||
|
||||
def test_ws_max_size() -> None:
|
||||
config = Config(app=asgi_app, ws_max_size=1000)
|
||||
config.load()
|
||||
assert config.ws_max_size == 1000
|
||||
|
||||
|
||||
def test_ws_max_queue() -> None:
|
||||
config = Config(app=asgi_app, ws_max_queue=64)
|
||||
config.load()
|
||||
assert config.ws_max_queue == 64
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"reload, workers",
|
||||
[
|
||||
(True, 1),
|
||||
(False, 2),
|
||||
],
|
||||
ids=["--reload=True --workers=1", "--reload=False --workers=2"],
|
||||
)
|
||||
@pytest.mark.skipif(sys.platform == "win32", reason="require unix-like system")
|
||||
def test_bind_unix_socket_works_with_reload_or_workers(
|
||||
tmp_path: Path, reload: bool, workers: int, short_socket_name: str
|
||||
): # pragma: py-win32
|
||||
config = Config(app=asgi_app, uds=short_socket_name, reload=reload, workers=workers)
|
||||
config.load()
|
||||
sock = config.bind_socket()
|
||||
assert isinstance(sock, socket.socket)
|
||||
assert sock.family == socket.AF_UNIX
|
||||
assert sock.getsockname() == short_socket_name
|
||||
sock.close()
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"reload, workers",
|
||||
[
|
||||
(True, 1),
|
||||
(False, 2),
|
||||
],
|
||||
ids=["--reload=True --workers=1", "--reload=False --workers=2"],
|
||||
)
|
||||
@pytest.mark.skipif(sys.platform == "win32", reason="require unix-like system")
|
||||
def test_bind_fd_works_with_reload_or_workers(reload: bool, workers: int): # pragma: py-win32
|
||||
fdsock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
|
||||
fd = fdsock.fileno()
|
||||
config = Config(app=asgi_app, fd=fd, reload=reload, workers=workers)
|
||||
config.load()
|
||||
sock = config.bind_socket()
|
||||
assert isinstance(sock, socket.socket)
|
||||
assert sock.family == socket.AF_UNIX
|
||||
assert sock.getsockname() == ""
|
||||
sock.close()
|
||||
fdsock.close()
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def stdin_socket() -> Iterator[socket.socket]: # pragma: py-win32
|
||||
with closing(socket.socket(socket.AF_INET)) as sock:
|
||||
sock.bind(("127.0.0.1", 0))
|
||||
saved_stdin = os.dup(0)
|
||||
os.dup2(sock.fileno(), 0)
|
||||
try:
|
||||
yield sock
|
||||
finally:
|
||||
os.dup2(saved_stdin, 0)
|
||||
os.close(saved_stdin)
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"reload, workers",
|
||||
[
|
||||
(True, 1),
|
||||
(False, 2),
|
||||
],
|
||||
ids=["--reload=True --workers=1", "--reload=False --workers=2"],
|
||||
)
|
||||
@pytest.mark.skipif(sys.platform == "win32", reason="require unix-like system")
|
||||
def test_bind_stdin_works_with_reload_or_workers(
|
||||
reload: bool, workers: int, stdin_socket: socket.socket
|
||||
): # pragma: py-win32
|
||||
config = Config(app=asgi_app, fd=0, reload=reload, workers=workers)
|
||||
config.load()
|
||||
with closing(config.bind_socket()) as sock:
|
||||
assert sock.getsockname() == stdin_socket.getsockname()
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"reload, workers, expected",
|
||||
[
|
||||
(True, 1, True),
|
||||
(False, 2, True),
|
||||
(False, 1, False),
|
||||
],
|
||||
ids=[
|
||||
"--reload=True --workers=1",
|
||||
"--reload=False --workers=2",
|
||||
"--reload=False --workers=1",
|
||||
],
|
||||
)
|
||||
def test_config_use_subprocess(reload: bool, workers: int, expected: bool):
|
||||
config = Config(app=asgi_app, reload=reload, workers=workers)
|
||||
config.load()
|
||||
assert config.use_subprocess == expected
|
||||
|
||||
|
||||
def test_warn_when_using_reload_and_workers(caplog: pytest.LogCaptureFixture) -> None:
|
||||
Config(app=asgi_app, reload=True, workers=2)
|
||||
assert len(caplog.records) == 1
|
||||
assert '"workers" flag is ignored when reloading is enabled.' in caplog.records[0].message
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
("loop_type", "expected_loop_factory"),
|
||||
[
|
||||
("none", None),
|
||||
("asyncio", get_asyncio_default_loop_per_os()),
|
||||
],
|
||||
)
|
||||
def test_get_loop_factory(loop_type: LoopFactoryType, expected_loop_factory: Any):
|
||||
config = Config(app=asgi_app, loop=loop_type)
|
||||
loop_factory = config.get_loop_factory()
|
||||
if loop_factory is None:
|
||||
assert expected_loop_factory is loop_factory
|
||||
else:
|
||||
loop = loop_factory()
|
||||
with closing(loop):
|
||||
assert loop is not None
|
||||
assert isinstance(loop, expected_loop_factory)
|
||||
|
||||
|
||||
def test_custom_loop__importable_custom_loop_setup_function() -> None:
|
||||
config = Config(app=asgi_app, loop="tests.custom_loop_utils:CustomLoop")
|
||||
config.load()
|
||||
loop_factory = config.get_loop_factory()
|
||||
assert loop_factory, "Loop factory should be set"
|
||||
event_loop = loop_factory()
|
||||
with closing(event_loop):
|
||||
assert event_loop is not None
|
||||
assert isinstance(event_loop, CustomLoop)
|
||||
|
||||
|
||||
@pytest.mark.filterwarnings("ignore::pytest.PytestUnraisableExceptionWarning")
|
||||
def test_custom_loop__not_importable_custom_loop_setup_function(caplog: pytest.LogCaptureFixture) -> None:
|
||||
config = Config(app=asgi_app, loop="tests.test_config:non_existing_setup_function")
|
||||
config.load()
|
||||
with pytest.raises(SystemExit):
|
||||
config.get_loop_factory()
|
||||
error_messages = [
|
||||
record.message for record in caplog.records if record.name == "uvicorn.error" and record.levelname == "ERROR"
|
||||
]
|
||||
assert (
|
||||
'Error loading custom loop setup function. Attribute "non_existing_setup_function" not found in module "tests.test_config".' # noqa: E501
|
||||
== error_messages.pop(0)
|
||||
mocked_logging_config_module.fileConfig.assert_called_once_with(
|
||||
"log_config", disable_existing_loggers=False
|
||||
)
|
||||
|
||||
|
||||
def test_setup_event_loop_is_removed(caplog: pytest.LogCaptureFixture) -> None:
|
||||
config = Config(app=asgi_app)
|
||||
with pytest.raises(
|
||||
AttributeError, match="The `setup_event_loop` method was replaced by `get_loop_factory` in uvicorn 0.36.0."
|
||||
):
|
||||
config.setup_event_loop()
|
||||
|
||||
@ -1,69 +1,90 @@
|
||||
from __future__ import annotations
|
||||
import threading
|
||||
import time
|
||||
|
||||
import httpx
|
||||
import pytest
|
||||
import requests
|
||||
|
||||
from tests.utils import run_server
|
||||
from uvicorn import Config
|
||||
from uvicorn._types import ASGIReceiveCallable, ASGISendCallable, Scope
|
||||
|
||||
pytestmark = pytest.mark.anyio
|
||||
from uvicorn import Config, Server
|
||||
|
||||
|
||||
async def app(scope: Scope, receive: ASGIReceiveCallable, send: ASGISendCallable) -> None:
|
||||
async def app(scope, receive, send):
|
||||
assert scope["type"] == "http"
|
||||
await send({"type": "http.response.start", "status": 200, "headers": []})
|
||||
await send({"type": "http.response.body", "body": b"", "more_body": False})
|
||||
|
||||
|
||||
async def test_default_default_headers(unused_tcp_port: int):
|
||||
config = Config(app=app, loop="asyncio", limit_max_requests=1, port=unused_tcp_port)
|
||||
async with run_server(config):
|
||||
async with httpx.AsyncClient() as client:
|
||||
response = await client.get(f"http://127.0.0.1:{unused_tcp_port}")
|
||||
assert response.headers["server"] == "uvicorn" and response.headers["date"]
|
||||
def test_default_default_headers():
|
||||
config = Config(app=app, loop="asyncio", limit_max_requests=1)
|
||||
server = Server(config=config)
|
||||
thread = threading.Thread(target=server.run)
|
||||
thread.start()
|
||||
while not server.started:
|
||||
time.sleep(0.01)
|
||||
response = requests.get("http://127.0.0.1:8000")
|
||||
|
||||
assert response.headers["server"] == "uvicorn" and response.headers["date"]
|
||||
|
||||
thread.join()
|
||||
|
||||
|
||||
async def test_override_server_header(unused_tcp_port: int):
|
||||
headers: list[tuple[str, str]] = [("Server", "over-ridden")]
|
||||
config = Config(app=app, loop="asyncio", limit_max_requests=1, headers=headers, port=unused_tcp_port)
|
||||
async with run_server(config):
|
||||
async with httpx.AsyncClient() as client:
|
||||
response = await client.get(f"http://127.0.0.1:{unused_tcp_port}")
|
||||
assert response.headers["server"] == "over-ridden" and response.headers["date"]
|
||||
def test_override_server_header():
|
||||
config = Config(
|
||||
app=app,
|
||||
loop="asyncio",
|
||||
limit_max_requests=1,
|
||||
headers=[("Server", "over-ridden")],
|
||||
)
|
||||
server = Server(config=config)
|
||||
thread = threading.Thread(target=server.run)
|
||||
thread.start()
|
||||
while not server.started:
|
||||
time.sleep(0.01)
|
||||
response = requests.get("http://127.0.0.1:8000")
|
||||
|
||||
assert response.headers["server"] == "over-ridden" and response.headers["date"]
|
||||
|
||||
thread.join()
|
||||
|
||||
|
||||
async def test_disable_default_server_header(unused_tcp_port: int):
|
||||
config = Config(app=app, loop="asyncio", limit_max_requests=1, server_header=False, port=unused_tcp_port)
|
||||
async with run_server(config):
|
||||
async with httpx.AsyncClient() as client:
|
||||
response = await client.get(f"http://127.0.0.1:{unused_tcp_port}")
|
||||
assert "server" not in response.headers
|
||||
def test_override_server_header_multiple_times():
|
||||
config = Config(
|
||||
app=app,
|
||||
loop="asyncio",
|
||||
limit_max_requests=1,
|
||||
headers=[("Server", "over-ridden"), ("Server", "another-value")],
|
||||
)
|
||||
server = Server(config=config)
|
||||
thread = threading.Thread(target=server.run)
|
||||
thread.start()
|
||||
while not server.started:
|
||||
time.sleep(0.01)
|
||||
response = requests.get("http://127.0.0.1:8000")
|
||||
|
||||
assert (
|
||||
response.headers["server"] == "over-ridden, another-value"
|
||||
and response.headers["date"]
|
||||
)
|
||||
|
||||
thread.join()
|
||||
|
||||
|
||||
async def test_override_server_header_multiple_times(unused_tcp_port: int):
|
||||
headers: list[tuple[str, str]] = [("Server", "over-ridden"), ("Server", "another-value")]
|
||||
config = Config(app=app, loop="asyncio", limit_max_requests=1, headers=headers, port=unused_tcp_port)
|
||||
async with run_server(config):
|
||||
async with httpx.AsyncClient() as client:
|
||||
response = await client.get(f"http://127.0.0.1:{unused_tcp_port}")
|
||||
assert response.headers["server"] == "over-ridden, another-value" and response.headers["date"]
|
||||
def test_add_additional_header():
|
||||
config = Config(
|
||||
app=app,
|
||||
loop="asyncio",
|
||||
limit_max_requests=1,
|
||||
headers=[("X-Additional", "new-value")],
|
||||
)
|
||||
server = Server(config=config)
|
||||
thread = threading.Thread(target=server.run)
|
||||
thread.start()
|
||||
while not server.started:
|
||||
time.sleep(0.01)
|
||||
response = requests.get("http://127.0.0.1:8000")
|
||||
|
||||
assert (
|
||||
response.headers["x-additional"] == "new-value"
|
||||
and response.headers["server"] == "uvicorn"
|
||||
and response.headers["date"]
|
||||
)
|
||||
|
||||
async def test_add_additional_header(unused_tcp_port: int):
|
||||
headers: list[tuple[str, str]] = [("X-Additional", "new-value")]
|
||||
config = Config(app=app, loop="asyncio", limit_max_requests=1, headers=headers, port=unused_tcp_port)
|
||||
async with run_server(config):
|
||||
async with httpx.AsyncClient() as client:
|
||||
response = await client.get(f"http://127.0.0.1:{unused_tcp_port}")
|
||||
assert response.headers["x-additional"] == "new-value"
|
||||
assert response.headers["server"] == "uvicorn"
|
||||
assert response.headers["date"]
|
||||
|
||||
|
||||
async def test_disable_default_date_header(unused_tcp_port: int):
|
||||
config = Config(app=app, loop="asyncio", limit_max_requests=1, date_header=False, port=unused_tcp_port)
|
||||
async with run_server(config):
|
||||
async with httpx.AsyncClient() as client:
|
||||
response = await client.get(f"http://127.0.0.1:{unused_tcp_port}")
|
||||
assert "date" not in response.headers
|
||||
thread.join()
|
||||
|
||||
@ -37,7 +37,6 @@ def test_lifespan_on():
|
||||
|
||||
loop = asyncio.new_event_loop()
|
||||
loop.run_until_complete(test())
|
||||
loop.close()
|
||||
|
||||
|
||||
def test_lifespan_off():
|
||||
@ -53,7 +52,6 @@ def test_lifespan_off():
|
||||
|
||||
loop = asyncio.new_event_loop()
|
||||
loop.run_until_complete(test())
|
||||
loop.close()
|
||||
|
||||
|
||||
def test_lifespan_auto():
|
||||
@ -86,7 +84,6 @@ def test_lifespan_auto():
|
||||
|
||||
loop = asyncio.new_event_loop()
|
||||
loop.run_until_complete(test())
|
||||
loop.close()
|
||||
|
||||
|
||||
def test_lifespan_auto_with_error():
|
||||
@ -98,13 +95,12 @@ def test_lifespan_auto_with_error():
|
||||
lifespan = LifespanOn(config)
|
||||
|
||||
await lifespan.startup()
|
||||
assert lifespan.error_occurred
|
||||
assert lifespan.error_occured
|
||||
assert not lifespan.should_exit
|
||||
await lifespan.shutdown()
|
||||
|
||||
loop = asyncio.new_event_loop()
|
||||
loop.run_until_complete(test())
|
||||
loop.close()
|
||||
|
||||
|
||||
def test_lifespan_on_with_error():
|
||||
@ -117,22 +113,21 @@ def test_lifespan_on_with_error():
|
||||
lifespan = LifespanOn(config)
|
||||
|
||||
await lifespan.startup()
|
||||
assert lifespan.error_occurred
|
||||
assert lifespan.error_occured
|
||||
assert lifespan.should_exit
|
||||
await lifespan.shutdown()
|
||||
|
||||
loop = asyncio.new_event_loop()
|
||||
loop.run_until_complete(test())
|
||||
loop.close()
|
||||
|
||||
|
||||
@pytest.mark.parametrize("mode", ("auto", "on"))
|
||||
@pytest.mark.parametrize("raise_exception", (True, False))
|
||||
def test_lifespan_with_failed_startup(mode, raise_exception, caplog):
|
||||
def test_lifespan_with_failed_startup(mode, raise_exception):
|
||||
async def app(scope, receive, send):
|
||||
message = await receive()
|
||||
assert message["type"] == "lifespan.startup"
|
||||
await send({"type": "lifespan.startup.failed", "message": "the lifespan event failed"})
|
||||
await send({"type": "lifespan.startup.failed"})
|
||||
if raise_exception:
|
||||
# App should be able to re-raise an exception if startup failed.
|
||||
raise RuntimeError()
|
||||
@ -143,50 +138,34 @@ def test_lifespan_with_failed_startup(mode, raise_exception, caplog):
|
||||
|
||||
await lifespan.startup()
|
||||
assert lifespan.startup_failed
|
||||
assert lifespan.error_occurred is raise_exception
|
||||
assert lifespan.error_occured is raise_exception
|
||||
assert lifespan.should_exit
|
||||
await lifespan.shutdown()
|
||||
|
||||
loop = asyncio.new_event_loop()
|
||||
loop.run_until_complete(test())
|
||||
loop.close()
|
||||
error_messages = [
|
||||
record.message for record in caplog.records if record.name == "uvicorn.error" and record.levelname == "ERROR"
|
||||
]
|
||||
assert "the lifespan event failed" in error_messages.pop(0)
|
||||
assert "Application startup failed. Exiting." in error_messages.pop(0)
|
||||
|
||||
|
||||
def test_lifespan_scope_asgi3app():
|
||||
@pytest.mark.parametrize("mode", ("auto", "on"))
|
||||
def test_lifespan_scope_asgi3app(mode):
|
||||
async def asgi3app(scope, receive, send):
|
||||
assert scope == {
|
||||
"type": "lifespan",
|
||||
"asgi": {"version": "3.0", "spec_version": "2.0"},
|
||||
"state": {},
|
||||
}
|
||||
assert scope == {"version": "3.0", "spec_version": "2.0"}
|
||||
|
||||
async def test():
|
||||
config = Config(app=asgi3app, lifespan="on")
|
||||
config = Config(app=asgi3app, lifespan=mode)
|
||||
lifespan = LifespanOn(config)
|
||||
|
||||
await lifespan.startup()
|
||||
assert not lifespan.startup_failed
|
||||
assert not lifespan.error_occurred
|
||||
assert not lifespan.should_exit
|
||||
await lifespan.shutdown()
|
||||
|
||||
loop = asyncio.new_event_loop()
|
||||
loop.run_until_complete(test())
|
||||
loop.close()
|
||||
|
||||
|
||||
def test_lifespan_scope_asgi2app():
|
||||
@pytest.mark.parametrize("mode", ("auto", "on"))
|
||||
def test_lifespan_scope_asgi2app(mode):
|
||||
def asgi2app(scope):
|
||||
assert scope == {
|
||||
"type": "lifespan",
|
||||
"asgi": {"version": "2.0", "spec_version": "2.0"},
|
||||
"state": {},
|
||||
}
|
||||
assert scope == {"version": "2.0", "spec_version": "2.0"}
|
||||
|
||||
async def asgi(receive, send):
|
||||
pass
|
||||
@ -194,7 +173,7 @@ def test_lifespan_scope_asgi2app():
|
||||
return asgi
|
||||
|
||||
async def test():
|
||||
config = Config(app=asgi2app, lifespan="on")
|
||||
config = Config(app=asgi2app, lifespan=mode)
|
||||
lifespan = LifespanOn(config)
|
||||
|
||||
await lifespan.startup()
|
||||
@ -202,63 +181,3 @@ def test_lifespan_scope_asgi2app():
|
||||
|
||||
loop = asyncio.new_event_loop()
|
||||
loop.run_until_complete(test())
|
||||
loop.close()
|
||||
|
||||
|
||||
@pytest.mark.parametrize("mode", ("auto", "on"))
|
||||
@pytest.mark.parametrize("raise_exception", (True, False))
|
||||
def test_lifespan_with_failed_shutdown(mode, raise_exception, caplog):
|
||||
async def app(scope, receive, send):
|
||||
message = await receive()
|
||||
assert message["type"] == "lifespan.startup"
|
||||
await send({"type": "lifespan.startup.complete"})
|
||||
message = await receive()
|
||||
assert message["type"] == "lifespan.shutdown"
|
||||
await send({"type": "lifespan.shutdown.failed", "message": "the lifespan event failed"})
|
||||
|
||||
if raise_exception:
|
||||
# App should be able to re-raise an exception if startup failed.
|
||||
raise RuntimeError()
|
||||
|
||||
async def test():
|
||||
config = Config(app=app, lifespan=mode)
|
||||
lifespan = LifespanOn(config)
|
||||
|
||||
await lifespan.startup()
|
||||
assert not lifespan.startup_failed
|
||||
await lifespan.shutdown()
|
||||
assert lifespan.shutdown_failed
|
||||
assert lifespan.error_occurred is raise_exception
|
||||
assert lifespan.should_exit
|
||||
|
||||
loop = asyncio.new_event_loop()
|
||||
loop.run_until_complete(test())
|
||||
error_messages = [
|
||||
record.message for record in caplog.records if record.name == "uvicorn.error" and record.levelname == "ERROR"
|
||||
]
|
||||
assert "the lifespan event failed" in error_messages.pop(0)
|
||||
assert "Application shutdown failed. Exiting." in error_messages.pop(0)
|
||||
loop.close()
|
||||
|
||||
|
||||
def test_lifespan_state():
|
||||
async def app(scope, receive, send):
|
||||
message = await receive()
|
||||
assert message["type"] == "lifespan.startup"
|
||||
await send({"type": "lifespan.startup.complete"})
|
||||
scope["state"]["foo"] = 123
|
||||
message = await receive()
|
||||
assert message["type"] == "lifespan.shutdown"
|
||||
await send({"type": "lifespan.shutdown.complete"})
|
||||
|
||||
async def test():
|
||||
config = Config(app=app, lifespan="on")
|
||||
lifespan = LifespanOn(config)
|
||||
|
||||
await lifespan.startup()
|
||||
assert lifespan.state == {"foo": 123}
|
||||
await lifespan.shutdown()
|
||||
|
||||
loop = asyncio.new_event_loop()
|
||||
loop.run_until_complete(test())
|
||||
loop.close()
|
||||
|
||||
@ -1,184 +1,91 @@
|
||||
import importlib
|
||||
import inspect
|
||||
import socket
|
||||
import sys
|
||||
from logging import WARNING
|
||||
from pathlib import Path
|
||||
import asyncio
|
||||
import threading
|
||||
import time
|
||||
|
||||
import httpx
|
||||
import pytest
|
||||
import requests
|
||||
|
||||
import uvicorn.server
|
||||
from tests.utils import run_server
|
||||
from uvicorn import Server
|
||||
from uvicorn._types import ASGIReceiveCallable, ASGISendCallable, Scope
|
||||
from uvicorn.config import Config
|
||||
from uvicorn.main import run
|
||||
from uvicorn.supervisors import Multiprocess
|
||||
|
||||
pytestmark = pytest.mark.anyio
|
||||
from uvicorn.main import Server
|
||||
|
||||
|
||||
async def app(scope: Scope, receive: ASGIReceiveCallable, send: ASGISendCallable) -> None:
|
||||
async def app(scope, receive, send):
|
||||
assert scope["type"] == "http"
|
||||
await send({"type": "http.response.start", "status": 204, "headers": []})
|
||||
await send({"type": "http.response.body", "body": b"", "more_body": False})
|
||||
|
||||
|
||||
def _has_ipv6(host: str):
|
||||
sock = None
|
||||
has_ipv6 = False
|
||||
if socket.has_ipv6:
|
||||
try:
|
||||
sock = socket.socket(socket.AF_INET6)
|
||||
sock.bind((host, 0))
|
||||
has_ipv6 = True
|
||||
except Exception: # pragma: no cover
|
||||
pass
|
||||
if sock:
|
||||
sock.close()
|
||||
return has_ipv6
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"host, url",
|
||||
[
|
||||
pytest.param(None, "http://127.0.0.1", id="default"),
|
||||
pytest.param("localhost", "http://127.0.0.1", id="hostname"),
|
||||
pytest.param(
|
||||
"::1",
|
||||
"http://[::1]",
|
||||
id="ipv6",
|
||||
marks=pytest.mark.skipif(not _has_ipv6("::1"), reason="IPV6 not enabled"),
|
||||
),
|
||||
pytest.param(None, "http://127.0.0.1:8000", id="default"),
|
||||
pytest.param("localhost", "http://127.0.0.1:8000", id="hostname"),
|
||||
pytest.param("::1", "http://[::1]:8000", id="ipv6"),
|
||||
],
|
||||
)
|
||||
async def test_run(host, url: str, unused_tcp_port: int):
|
||||
config = Config(app=app, host=host, loop="asyncio", limit_max_requests=1, port=unused_tcp_port)
|
||||
async with run_server(config):
|
||||
async with httpx.AsyncClient() as client:
|
||||
response = await client.get(f"{url}:{unused_tcp_port}")
|
||||
def test_run(host, url):
|
||||
config = Config(app=app, host=host, loop="asyncio", limit_max_requests=1)
|
||||
server = Server(config=config)
|
||||
thread = threading.Thread(target=server.run)
|
||||
thread.start()
|
||||
while not server.started:
|
||||
time.sleep(0.01)
|
||||
response = requests.get(url)
|
||||
assert response.status_code == 204
|
||||
thread.join()
|
||||
|
||||
|
||||
async def test_run_multiprocess(unused_tcp_port: int):
|
||||
config = Config(app=app, loop="asyncio", workers=2, limit_max_requests=1, port=unused_tcp_port)
|
||||
async with run_server(config):
|
||||
async with httpx.AsyncClient() as client:
|
||||
response = await client.get(f"http://127.0.0.1:{unused_tcp_port}")
|
||||
def test_run_multiprocess():
|
||||
config = Config(app=app, loop="asyncio", workers=2, limit_max_requests=1)
|
||||
server = Server(config=config)
|
||||
thread = threading.Thread(target=server.run)
|
||||
thread.start()
|
||||
while not server.started:
|
||||
time.sleep(0.01)
|
||||
response = requests.get("http://127.0.0.1:8000")
|
||||
assert response.status_code == 204
|
||||
thread.join()
|
||||
|
||||
|
||||
async def test_run_reload(unused_tcp_port: int):
|
||||
config = Config(app=app, loop="asyncio", reload=True, limit_max_requests=1, port=unused_tcp_port)
|
||||
async with run_server(config):
|
||||
async with httpx.AsyncClient() as client:
|
||||
response = await client.get(f"http://127.0.0.1:{unused_tcp_port}")
|
||||
def test_run_reload():
|
||||
config = Config(app=app, loop="asyncio", reload=True, limit_max_requests=1)
|
||||
server = Server(config=config)
|
||||
thread = threading.Thread(target=server.run)
|
||||
thread.start()
|
||||
while not server.started:
|
||||
time.sleep(0.01)
|
||||
response = requests.get("http://127.0.0.1:8000")
|
||||
assert response.status_code == 204
|
||||
thread.join()
|
||||
|
||||
|
||||
def test_run_invalid_app_config_combination(caplog: pytest.LogCaptureFixture) -> None:
|
||||
with pytest.raises(SystemExit) as exit_exception:
|
||||
run(app, reload=True)
|
||||
assert exit_exception.value.code == 1
|
||||
assert caplog.records[-1].name == "uvicorn.error"
|
||||
assert caplog.records[-1].levelno == WARNING
|
||||
assert caplog.records[-1].message == (
|
||||
"You must pass the application as an import string to enable 'reload' or 'workers'."
|
||||
)
|
||||
|
||||
|
||||
def test_run_fails_fast_in_parent_on_bad_app_path(
|
||||
caplog: pytest.LogCaptureFixture, monkeypatch: pytest.MonkeyPatch
|
||||
) -> None:
|
||||
"""Bad app path with `--workers > 1` exits in the parent.
|
||||
|
||||
Regression for https://github.com/encode/uvicorn/discussions/2440: without
|
||||
parent-side validation the supervisor restarts dying workers forever.
|
||||
"""
|
||||
|
||||
def fail(*args: object, **kwargs: object) -> None: # pragma: no cover
|
||||
pytest.fail("parent reached supervisor; should have exited on bad app path")
|
||||
|
||||
monkeypatch.setattr(Config, "bind_socket", fail)
|
||||
monkeypatch.setattr(Multiprocess, "run", fail)
|
||||
|
||||
with pytest.raises(SystemExit) as exit_exception:
|
||||
run("tests.test_main:nonexistent_attr", workers=2)
|
||||
assert exit_exception.value.code == 1
|
||||
assert any("Error loading ASGI app" in record.message for record in caplog.records)
|
||||
|
||||
|
||||
def test_run_imports_app_before_starting_event_loop(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
|
||||
"""`uvicorn.run()` imports the app before `Server.run` opens the event loop.
|
||||
|
||||
Regression for https://github.com/encode/uvicorn/issues/941: an app whose
|
||||
module body calls `asyncio.run(...)` crashes with "loop already running"
|
||||
if Uvicorn imports it inside the server's event loop. The parent must
|
||||
import the app synchronously, before `Server.run` enters `asyncio.run`.
|
||||
"""
|
||||
module = tmp_path / "eager_async_app.py"
|
||||
module.write_text(
|
||||
"import asyncio\n"
|
||||
"async def _build():\n"
|
||||
" async def app(scope, receive, send):\n"
|
||||
" pass\n"
|
||||
" return app\n"
|
||||
"app = asyncio.run(_build())\n"
|
||||
)
|
||||
monkeypatch.syspath_prepend(str(tmp_path))
|
||||
|
||||
imported_before_server_run: list[bool] = []
|
||||
|
||||
def tracking_run(self: Server, sockets: object = None) -> None:
|
||||
imported_before_server_run.append("eager_async_app" in sys.modules)
|
||||
self.started = True
|
||||
|
||||
monkeypatch.setattr(Server, "run", tracking_run)
|
||||
|
||||
# The import side effect (`eager_async_app` lands in `sys.modules`) must
|
||||
# happen before `Server.run`, which is where the event loop opens.
|
||||
run("eager_async_app:app")
|
||||
|
||||
assert imported_before_server_run == [True]
|
||||
|
||||
|
||||
def test_run_startup_failure(caplog: pytest.LogCaptureFixture) -> None:
|
||||
def test_run_with_shutdown():
|
||||
async def app(scope, receive, send):
|
||||
assert scope["type"] == "lifespan"
|
||||
message = await receive()
|
||||
if message["type"] == "lifespan.startup":
|
||||
raise RuntimeError("Startup failed")
|
||||
assert scope["type"] == "http"
|
||||
while True:
|
||||
time.sleep(1)
|
||||
|
||||
with pytest.raises(SystemExit) as exit_exception:
|
||||
run(app, lifespan="on")
|
||||
assert exit_exception.value.code == 3
|
||||
config = Config(app=app, loop="asyncio", workers=2, limit_max_requests=1)
|
||||
server = Server(config=config)
|
||||
sock = config.bind_socket()
|
||||
exc = True
|
||||
|
||||
def safe_run():
|
||||
nonlocal exc, server
|
||||
try:
|
||||
exc = None
|
||||
config.setup_event_loop()
|
||||
loop = asyncio.get_event_loop()
|
||||
loop.run_until_complete(server.serve(sockets=[sock]))
|
||||
except Exception as e:
|
||||
exc = e
|
||||
|
||||
def test_run_match_config_params() -> None:
|
||||
config_params = {
|
||||
key: repr(value)
|
||||
for key, value in inspect.signature(Config.__init__).parameters.items()
|
||||
if key not in ("self", "timeout_notify", "callback_notify")
|
||||
}
|
||||
run_params = {
|
||||
key: repr(value) for key, value in inspect.signature(run).parameters.items() if key not in ("app_dir",)
|
||||
}
|
||||
assert config_params == run_params
|
||||
thread = threading.Thread(target=safe_run)
|
||||
thread.start()
|
||||
|
||||
while not server.started:
|
||||
time.sleep(0.01)
|
||||
|
||||
async def test_exit_on_create_server_with_invalid_host() -> None:
|
||||
with pytest.raises(SystemExit) as exc_info:
|
||||
config = Config(app=app, host="illegal_host")
|
||||
server = Server(config=config)
|
||||
await server.serve()
|
||||
assert exc_info.value.code == 1
|
||||
|
||||
|
||||
def test_deprecated_server_state_from_main() -> None:
|
||||
with pytest.deprecated_call(
|
||||
match="uvicorn.main.ServerState is deprecated, use uvicorn.server.ServerState instead."
|
||||
):
|
||||
main = importlib.import_module("uvicorn.main")
|
||||
server_state_cls = getattr(main, "ServerState")
|
||||
assert server_state_cls is uvicorn.server.ServerState
|
||||
server.should_exit = True
|
||||
thread.join()
|
||||
assert exc is None
|
||||
|
||||
@ -1,263 +0,0 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import contextlib
|
||||
import contextvars
|
||||
import json
|
||||
import logging
|
||||
import signal
|
||||
import sys
|
||||
from collections.abc import Callable, Generator
|
||||
from contextlib import AbstractContextManager
|
||||
|
||||
import httpx
|
||||
import pytest
|
||||
|
||||
from tests.protocols.test_http import SIMPLE_GET_REQUEST
|
||||
from tests.utils import run_server
|
||||
from uvicorn._types import ASGIApplication, ASGIReceiveCallable, ASGISendCallable, Scope
|
||||
from uvicorn.config import Config
|
||||
from uvicorn.protocols.http.flow_control import HIGH_WATER_LIMIT
|
||||
from uvicorn.protocols.http.h11_impl import H11Protocol
|
||||
from uvicorn.protocols.http.httptools_impl import HttpToolsProtocol
|
||||
from uvicorn.server import Server
|
||||
|
||||
pytestmark = pytest.mark.anyio
|
||||
|
||||
|
||||
# asyncio does NOT allow raising in signal handlers, so to detect
|
||||
# raised signals raised a mutable `witness` receives the signal
|
||||
@contextlib.contextmanager
|
||||
def capture_signal_sync(sig: signal.Signals) -> Generator[list[int], None, None]:
|
||||
"""Replace `sig` handling with a normal exception via `signal"""
|
||||
witness: list[int] = []
|
||||
original_handler = signal.signal(sig, lambda signum, frame: witness.append(signum))
|
||||
yield witness
|
||||
signal.signal(sig, original_handler)
|
||||
|
||||
|
||||
@contextlib.contextmanager
|
||||
def capture_signal_async(sig: signal.Signals) -> Generator[list[int], None, None]: # pragma: py-win32
|
||||
"""Replace `sig` handling with a normal exception via `asyncio"""
|
||||
witness: list[int] = []
|
||||
original_handler = signal.getsignal(sig)
|
||||
asyncio.get_running_loop().add_signal_handler(sig, witness.append, sig)
|
||||
yield witness
|
||||
signal.signal(sig, original_handler)
|
||||
|
||||
|
||||
async def dummy_app(scope, receive, send): # pragma: py-win32
|
||||
pass
|
||||
|
||||
|
||||
async def app(scope: Scope, receive: ASGIReceiveCallable, send: ASGISendCallable) -> None:
|
||||
assert scope["type"] == "http"
|
||||
await send({"type": "http.response.start", "status": 200, "headers": []})
|
||||
await send({"type": "http.response.body", "body": b"", "more_body": False})
|
||||
|
||||
|
||||
if sys.platform == "win32": # pragma: py-not-win32
|
||||
signals = [signal.SIGBREAK]
|
||||
signal_captures = [capture_signal_sync]
|
||||
else: # pragma: py-win32
|
||||
signals = [signal.SIGTERM, signal.SIGINT]
|
||||
signal_captures = [capture_signal_sync, capture_signal_async]
|
||||
|
||||
|
||||
@pytest.mark.parametrize("exception_signal", signals)
|
||||
@pytest.mark.parametrize("capture_signal", signal_captures)
|
||||
async def test_server_interrupt(
|
||||
exception_signal: signal.Signals,
|
||||
capture_signal: Callable[[signal.Signals], AbstractContextManager[None]],
|
||||
unused_tcp_port: int,
|
||||
): # pragma: py-win32
|
||||
"""Test interrupting a Server that is run explicitly inside asyncio"""
|
||||
|
||||
async def interrupt_running(srv: Server):
|
||||
while not srv.started:
|
||||
await asyncio.sleep(0.01)
|
||||
signal.raise_signal(exception_signal)
|
||||
|
||||
server = Server(Config(app=dummy_app, loop="asyncio", port=unused_tcp_port))
|
||||
asyncio.create_task(interrupt_running(server))
|
||||
with capture_signal(exception_signal) as witness:
|
||||
await server.serve()
|
||||
assert witness
|
||||
# set by the server's graceful exit handler
|
||||
assert server.should_exit
|
||||
|
||||
|
||||
async def test_shutdown_on_early_exit_during_startup(unused_tcp_port: int):
|
||||
"""Test that lifespan.shutdown is called even when should_exit is set during startup."""
|
||||
startup_complete = False
|
||||
shutdown_complete = False
|
||||
|
||||
async def app(scope: Scope, receive: ASGIReceiveCallable, send: ASGISendCallable) -> None:
|
||||
nonlocal startup_complete, shutdown_complete
|
||||
if scope["type"] == "lifespan":
|
||||
while True:
|
||||
message = await receive()
|
||||
if message["type"] == "lifespan.startup":
|
||||
await asyncio.sleep(0.5)
|
||||
await send({"type": "lifespan.startup.complete"})
|
||||
startup_complete = True
|
||||
elif message["type"] == "lifespan.shutdown":
|
||||
await send({"type": "lifespan.shutdown.complete"})
|
||||
shutdown_complete = True
|
||||
return
|
||||
|
||||
config = Config(app=app, lifespan="on", port=unused_tcp_port)
|
||||
server = Server(config=config)
|
||||
|
||||
# Simulate a reload signal arriving during startup:
|
||||
# set should_exit before the 0.5s startup sleep finishes.
|
||||
async def set_exit():
|
||||
await asyncio.sleep(0.2)
|
||||
server.should_exit = True
|
||||
|
||||
asyncio.create_task(set_exit())
|
||||
await server.serve()
|
||||
|
||||
assert startup_complete
|
||||
assert shutdown_complete, "lifespan.shutdown was not called despite startup completing"
|
||||
|
||||
|
||||
async def test_request_than_limit_max_requests_warn_log(
|
||||
unused_tcp_port: int, http_protocol_cls: type[H11Protocol | HttpToolsProtocol], caplog: pytest.LogCaptureFixture
|
||||
):
|
||||
caplog.set_level(logging.INFO, logger="uvicorn.error")
|
||||
config = Config(app=app, limit_max_requests=1, port=unused_tcp_port, http=http_protocol_cls)
|
||||
async with run_server(config):
|
||||
async with httpx.AsyncClient() as client:
|
||||
tasks = [client.get(f"http://127.0.0.1:{unused_tcp_port}") for _ in range(2)]
|
||||
responses = await asyncio.gather(*tasks)
|
||||
assert len(responses) == 2
|
||||
assert "Maximum request limit of 1 exceeded. Terminating process." in caplog.text
|
||||
|
||||
|
||||
async def test_limit_max_requests_jitter(
|
||||
unused_tcp_port: int, http_protocol_cls: type[H11Protocol | HttpToolsProtocol], caplog: pytest.LogCaptureFixture
|
||||
):
|
||||
caplog.set_level(logging.INFO, logger="uvicorn.error")
|
||||
config = Config(
|
||||
app=app, limit_max_requests=1, limit_max_requests_jitter=2, port=unused_tcp_port, http=http_protocol_cls
|
||||
)
|
||||
async with run_server(config) as server:
|
||||
limit = server.limit_max_requests
|
||||
assert limit is not None
|
||||
assert 1 <= limit <= 3
|
||||
async with httpx.AsyncClient() as client:
|
||||
tasks = [client.get(f"http://127.0.0.1:{unused_tcp_port}") for _ in range(limit + 1)]
|
||||
await asyncio.gather(*tasks)
|
||||
assert f"Maximum request limit of {limit} exceeded. Terminating process." in caplog.text
|
||||
|
||||
|
||||
@contextlib.asynccontextmanager
|
||||
async def _raw_server(
|
||||
*,
|
||||
app: ASGIApplication,
|
||||
port: int,
|
||||
http_protocol_cls: type[H11Protocol | HttpToolsProtocol],
|
||||
reset_contextvars: bool = False,
|
||||
):
|
||||
config = Config(app=app, port=port, loop="asyncio", http=http_protocol_cls, reset_contextvars=reset_contextvars)
|
||||
server = Server(config=config)
|
||||
task = asyncio.create_task(server.serve())
|
||||
|
||||
while not server.started:
|
||||
await asyncio.sleep(0.01)
|
||||
|
||||
reader, writer = await asyncio.open_connection("127.0.0.1", port)
|
||||
|
||||
async def extract_json_body(request: bytes):
|
||||
writer.write(request)
|
||||
await writer.drain()
|
||||
|
||||
status, *headers = (await reader.readuntil(b"\r\n\r\n")).split(b"\r\n")[:-2]
|
||||
assert status == b"HTTP/1.1 200 OK"
|
||||
|
||||
content_length = next(int(h.split(b":", 1)[1]) for h in headers if h.lower().startswith(b"content-length:"))
|
||||
return json.loads(await reader.readexactly(content_length))
|
||||
|
||||
try:
|
||||
yield extract_json_body
|
||||
finally:
|
||||
writer.close()
|
||||
await writer.wait_closed()
|
||||
server.should_exit = True
|
||||
await task
|
||||
|
||||
|
||||
async def test_contextvars_preserved_by_default(
|
||||
http_protocol_cls: type[H11Protocol | HttpToolsProtocol], unused_tcp_port: int
|
||||
):
|
||||
"""By default, context set outside the ASGI task is visible inside it."""
|
||||
ctx: contextvars.ContextVar[str] = contextvars.ContextVar("ctx")
|
||||
ctx.set("outer-value")
|
||||
|
||||
async def app(scope: Scope, receive: ASGIReceiveCallable, send: ASGISendCallable):
|
||||
assert scope["type"] == "http"
|
||||
while True:
|
||||
message = await receive()
|
||||
assert message["type"] == "http.request"
|
||||
if not message["more_body"]:
|
||||
break
|
||||
body = json.dumps({"ctx": ctx.get("MISSING")}).encode("utf-8")
|
||||
headers = [(b"content-type", b"application/json"), (b"content-length", str(len(body)).encode("utf-8"))]
|
||||
await send({"type": "http.response.start", "status": 200, "headers": headers})
|
||||
await send({"type": "http.response.body", "body": body})
|
||||
|
||||
async with _raw_server(app=app, http_protocol_cls=http_protocol_cls, port=unused_tcp_port) as extract_json_body:
|
||||
assert await extract_json_body(SIMPLE_GET_REQUEST) == {"ctx": "outer-value"}
|
||||
|
||||
|
||||
async def test_reset_contextvars_asyncio(
|
||||
http_protocol_cls: type[H11Protocol | HttpToolsProtocol], unused_tcp_port: int
|
||||
):
|
||||
"""With reset_contextvars=True, each ASGI run starts with a fresh context.
|
||||
|
||||
Non-regression test for https://github.com/encode/uvicorn/issues/2167.
|
||||
"""
|
||||
default_contextvars = {c.name for c in contextvars.copy_context().keys()}
|
||||
ctx: contextvars.ContextVar[str] = contextvars.ContextVar("ctx")
|
||||
|
||||
async def app(scope: Scope, receive: ASGIReceiveCallable, send: ASGISendCallable):
|
||||
assert scope["type"] == "http"
|
||||
|
||||
# initial context should be empty
|
||||
initial_context = {
|
||||
n: v for c, v in contextvars.copy_context().items() if (n := c.name) not in default_contextvars
|
||||
}
|
||||
# set any contextvar before the body is read
|
||||
ctx.set(scope["path"])
|
||||
|
||||
while True:
|
||||
message = await receive()
|
||||
assert message["type"] == "http.request"
|
||||
if not message["more_body"]:
|
||||
break
|
||||
|
||||
body = json.dumps(initial_context).encode("utf-8")
|
||||
headers = [(b"content-type", b"application/json"), (b"content-length", str(len(body)).encode("utf-8"))]
|
||||
await send({"type": "http.response.start", "status": 200, "headers": headers})
|
||||
await send({"type": "http.response.body", "body": body})
|
||||
|
||||
# body larger than HIGH_WATER_LIMIT forces a reading pause on the main thread
|
||||
# and a resumption inside the ASGI task, which is where the original pollution showed up.
|
||||
large_body = b"a" * (HIGH_WATER_LIMIT + 1)
|
||||
large_request = b"\r\n".join(
|
||||
[
|
||||
b"POST /large-body HTTP/1.1",
|
||||
b"Host: example.org",
|
||||
b"Content-Type: application/octet-stream",
|
||||
f"Content-Length: {len(large_body)}".encode(),
|
||||
b"",
|
||||
large_body,
|
||||
]
|
||||
)
|
||||
|
||||
async with _raw_server(
|
||||
app=app, http_protocol_cls=http_protocol_cls, port=unused_tcp_port, reset_contextvars=True
|
||||
) as extract_json_body:
|
||||
assert await extract_json_body(large_request) == {}
|
||||
assert await extract_json_body(SIMPLE_GET_REQUEST) == {}
|
||||
@ -1,16 +1,28 @@
|
||||
from __future__ import annotations
|
||||
import contextlib
|
||||
import sys
|
||||
import threading
|
||||
import time
|
||||
import warnings
|
||||
from functools import partialmethod
|
||||
|
||||
import ssl
|
||||
from collections.abc import Callable
|
||||
from typing import TypeAlias
|
||||
|
||||
import httpx
|
||||
import pytest
|
||||
import requests
|
||||
from urllib3.exceptions import InsecureRequestWarning
|
||||
|
||||
from tests.utils import run_server
|
||||
from uvicorn.config import Config
|
||||
from uvicorn.main import Server
|
||||
|
||||
DefaultFactory: TypeAlias = Callable[[], ssl.SSLContext]
|
||||
|
||||
@contextlib.contextmanager
|
||||
def no_ssl_verification(session=requests.Session):
|
||||
old_request = session.request
|
||||
session.request = partialmethod(old_request, verify=False)
|
||||
|
||||
with warnings.catch_warnings():
|
||||
warnings.simplefilter("ignore", InsecureRequestWarning)
|
||||
yield
|
||||
|
||||
session.request = old_request
|
||||
|
||||
|
||||
async def app(scope, receive, send):
|
||||
@ -19,189 +31,69 @@ async def app(scope, receive, send):
|
||||
await send({"type": "http.response.body", "body": b"", "more_body": False})
|
||||
|
||||
|
||||
@pytest.mark.anyio
|
||||
async def test_run(
|
||||
tls_ca_ssl_context,
|
||||
tls_certificate_server_cert_path,
|
||||
tls_certificate_private_key_path,
|
||||
tls_ca_certificate_pem_path,
|
||||
unused_tcp_port: int,
|
||||
@pytest.mark.skipif(
|
||||
sys.platform.startswith("win"), reason="Skipping SSL test on Windows"
|
||||
)
|
||||
def test_run(tls_ca_certificate_pem_path, tls_ca_certificate_private_key_path):
|
||||
config = Config(
|
||||
app=app,
|
||||
loop="asyncio",
|
||||
limit_max_requests=1,
|
||||
ssl_keyfile=tls_ca_certificate_private_key_path,
|
||||
ssl_certfile=tls_ca_certificate_pem_path,
|
||||
)
|
||||
server = Server(config=config)
|
||||
thread = threading.Thread(target=server.run)
|
||||
thread.start()
|
||||
while not server.started:
|
||||
time.sleep(0.01)
|
||||
with no_ssl_verification():
|
||||
response = requests.get("https://127.0.0.1:8000")
|
||||
assert response.status_code == 204
|
||||
thread.join()
|
||||
|
||||
|
||||
@pytest.mark.skipif(
|
||||
sys.platform.startswith("win"), reason="Skipping SSL test on Windows"
|
||||
)
|
||||
def test_run_chain(tls_certificate_pem_path):
|
||||
config = Config(
|
||||
app=app,
|
||||
loop="asyncio",
|
||||
limit_max_requests=1,
|
||||
ssl_certfile=tls_certificate_pem_path,
|
||||
)
|
||||
server = Server(config=config)
|
||||
thread = threading.Thread(target=server.run)
|
||||
thread.start()
|
||||
while not server.started:
|
||||
time.sleep(0.01)
|
||||
with no_ssl_verification():
|
||||
response = requests.get("https://127.0.0.1:8000")
|
||||
assert response.status_code == 204
|
||||
thread.join()
|
||||
|
||||
|
||||
@pytest.mark.skipif(
|
||||
sys.platform.startswith("win"), reason="Skipping SSL test on Windows"
|
||||
)
|
||||
def test_run_password(
|
||||
tls_ca_certificate_pem_path, tls_ca_certificate_private_key_encrypted_path
|
||||
):
|
||||
config = Config(
|
||||
app=app,
|
||||
loop="asyncio",
|
||||
limit_max_requests=1,
|
||||
ssl_keyfile=tls_certificate_private_key_path,
|
||||
ssl_certfile=tls_certificate_server_cert_path,
|
||||
ssl_ca_certs=tls_ca_certificate_pem_path,
|
||||
port=unused_tcp_port,
|
||||
)
|
||||
async with run_server(config):
|
||||
async with httpx.AsyncClient(verify=tls_ca_ssl_context) as client:
|
||||
response = await client.get(f"https://127.0.0.1:{unused_tcp_port}")
|
||||
assert response.status_code == 204
|
||||
|
||||
|
||||
@pytest.mark.anyio
|
||||
async def test_run_chain(
|
||||
tls_ca_ssl_context,
|
||||
tls_certificate_key_and_chain_path,
|
||||
tls_ca_certificate_pem_path,
|
||||
unused_tcp_port: int,
|
||||
):
|
||||
config = Config(
|
||||
app=app,
|
||||
loop="asyncio",
|
||||
limit_max_requests=1,
|
||||
ssl_certfile=tls_certificate_key_and_chain_path,
|
||||
ssl_ca_certs=tls_ca_certificate_pem_path,
|
||||
port=unused_tcp_port,
|
||||
)
|
||||
async with run_server(config):
|
||||
async with httpx.AsyncClient(verify=tls_ca_ssl_context) as client:
|
||||
response = await client.get(f"https://127.0.0.1:{unused_tcp_port}")
|
||||
assert response.status_code == 204
|
||||
|
||||
|
||||
@pytest.mark.anyio
|
||||
async def test_run_chain_only(tls_ca_ssl_context, tls_certificate_key_and_chain_path, unused_tcp_port: int):
|
||||
config = Config(
|
||||
app=app,
|
||||
loop="asyncio",
|
||||
limit_max_requests=1,
|
||||
ssl_certfile=tls_certificate_key_and_chain_path,
|
||||
port=unused_tcp_port,
|
||||
)
|
||||
async with run_server(config):
|
||||
async with httpx.AsyncClient(verify=tls_ca_ssl_context) as client:
|
||||
response = await client.get(f"https://127.0.0.1:{unused_tcp_port}")
|
||||
assert response.status_code == 204
|
||||
|
||||
|
||||
@pytest.mark.anyio
|
||||
async def test_run_password(
|
||||
tls_ca_ssl_context,
|
||||
tls_certificate_server_cert_path,
|
||||
tls_ca_certificate_pem_path,
|
||||
tls_certificate_private_key_encrypted_path,
|
||||
unused_tcp_port: int,
|
||||
):
|
||||
config = Config(
|
||||
app=app,
|
||||
loop="asyncio",
|
||||
limit_max_requests=1,
|
||||
ssl_keyfile=tls_certificate_private_key_encrypted_path,
|
||||
ssl_certfile=tls_certificate_server_cert_path,
|
||||
ssl_keyfile=tls_ca_certificate_private_key_encrypted_path,
|
||||
ssl_certfile=tls_ca_certificate_pem_path,
|
||||
ssl_keyfile_password="uvicorn password for the win",
|
||||
ssl_ca_certs=tls_ca_certificate_pem_path,
|
||||
port=unused_tcp_port,
|
||||
)
|
||||
async with run_server(config):
|
||||
async with httpx.AsyncClient(verify=tls_ca_ssl_context) as client:
|
||||
response = await client.get(f"https://127.0.0.1:{unused_tcp_port}")
|
||||
server = Server(config=config)
|
||||
thread = threading.Thread(target=server.run)
|
||||
thread.start()
|
||||
while not server.started:
|
||||
time.sleep(0.01)
|
||||
with no_ssl_verification():
|
||||
response = requests.get("https://127.0.0.1:8000")
|
||||
assert response.status_code == 204
|
||||
|
||||
|
||||
@pytest.mark.anyio
|
||||
async def test_run_ssl_context_factory_default(
|
||||
tls_ca_ssl_context: ssl.SSLContext,
|
||||
tls_certificate_server_cert_path: str,
|
||||
tls_certificate_private_key_path: str,
|
||||
unused_tcp_port: int,
|
||||
) -> None:
|
||||
"""A factory that just delegates to the default factory should produce a working server."""
|
||||
|
||||
def ssl_context_factory(config: Config, default_ssl_context_factory: DefaultFactory) -> ssl.SSLContext:
|
||||
return default_ssl_context_factory()
|
||||
|
||||
config = Config(
|
||||
app=app,
|
||||
loop="asyncio",
|
||||
limit_max_requests=1,
|
||||
ssl_keyfile=tls_certificate_private_key_path,
|
||||
ssl_certfile=tls_certificate_server_cert_path,
|
||||
ssl_context_factory=ssl_context_factory,
|
||||
port=unused_tcp_port,
|
||||
)
|
||||
async with run_server(config):
|
||||
async with httpx.AsyncClient(verify=tls_ca_ssl_context) as client:
|
||||
response = await client.get(f"https://127.0.0.1:{unused_tcp_port}")
|
||||
assert response.status_code == 204
|
||||
|
||||
|
||||
@pytest.mark.anyio
|
||||
async def test_run_ssl_context_factory_custom(
|
||||
tls_ca_ssl_context: ssl.SSLContext,
|
||||
tls_certificate_server_cert_path: str,
|
||||
tls_certificate_private_key_path: str,
|
||||
unused_tcp_port: int,
|
||||
) -> None:
|
||||
"""A factory that builds its own SSLContext from scratch should work without ssl_keyfile/ssl_certfile."""
|
||||
|
||||
def ssl_context_factory(config: Config, default_ssl_context_factory: DefaultFactory) -> ssl.SSLContext:
|
||||
ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
|
||||
ctx.load_cert_chain(tls_certificate_server_cert_path, tls_certificate_private_key_path)
|
||||
return ctx
|
||||
|
||||
config = Config(
|
||||
app=app,
|
||||
loop="asyncio",
|
||||
limit_max_requests=1,
|
||||
ssl_context_factory=ssl_context_factory,
|
||||
port=unused_tcp_port,
|
||||
)
|
||||
async with run_server(config):
|
||||
async with httpx.AsyncClient(verify=tls_ca_ssl_context) as client:
|
||||
response = await client.get(f"https://127.0.0.1:{unused_tcp_port}")
|
||||
assert response.status_code == 204
|
||||
|
||||
|
||||
def test_ssl_context_factory_mutates_default(
|
||||
tls_certificate_server_cert_path: str,
|
||||
tls_certificate_private_key_path: str,
|
||||
) -> None:
|
||||
"""The factory can call the default and mutate the result (e.g., bump TLS minimum version)."""
|
||||
|
||||
def ssl_context_factory(config: Config, default_ssl_context_factory: DefaultFactory) -> ssl.SSLContext:
|
||||
ctx = default_ssl_context_factory()
|
||||
ctx.minimum_version = ssl.TLSVersion.TLSv1_3
|
||||
return ctx
|
||||
|
||||
config = Config(
|
||||
app=app,
|
||||
ssl_keyfile=tls_certificate_private_key_path,
|
||||
ssl_certfile=tls_certificate_server_cert_path,
|
||||
ssl_context_factory=ssl_context_factory,
|
||||
)
|
||||
config.load()
|
||||
assert config.is_ssl
|
||||
assert isinstance(config.ssl, ssl.SSLContext)
|
||||
assert config.ssl.minimum_version == ssl.TLSVersion.TLSv1_3
|
||||
|
||||
|
||||
def test_default_ssl_context_factory_requires_ssl_certfile() -> None:
|
||||
"""Calling `default_ssl_context_factory()` without `ssl_certfile` raises a clear error."""
|
||||
|
||||
def ssl_context_factory(config: Config, default_ssl_context_factory: DefaultFactory) -> ssl.SSLContext:
|
||||
return default_ssl_context_factory()
|
||||
|
||||
config = Config(app=app, ssl_context_factory=ssl_context_factory)
|
||||
with pytest.raises(RuntimeError, match="requires `ssl_certfile`"):
|
||||
config.load()
|
||||
|
||||
|
||||
def test_ssl_context_factory_must_return_ssl_context() -> None:
|
||||
def bad_factory(config: Config, default_ssl_context_factory: DefaultFactory) -> object:
|
||||
return "not an SSLContext"
|
||||
|
||||
config = Config(app=app, ssl_context_factory=bad_factory) # type: ignore[arg-type]
|
||||
with pytest.raises(TypeError, match="must return an `ssl.SSLContext`"):
|
||||
config.load()
|
||||
|
||||
|
||||
def test_is_ssl_true_when_only_factory_set() -> None:
|
||||
def ssl_context_factory(config: Config, default_ssl_context_factory: DefaultFactory) -> ssl.SSLContext:
|
||||
return ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER) # pragma: no cover
|
||||
|
||||
config = Config(app=app, ssl_context_factory=ssl_context_factory)
|
||||
assert config.is_ssl is True
|
||||
thread.join()
|
||||
|
||||
@ -1,43 +0,0 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import socket
|
||||
from unittest.mock import patch
|
||||
|
||||
from uvicorn._subprocess import SpawnProcess, get_subprocess, subprocess_started
|
||||
from uvicorn._types import ASGIReceiveCallable, ASGISendCallable, Scope
|
||||
from uvicorn.config import Config
|
||||
|
||||
|
||||
def server_run(sockets: list[socket.socket]): # pragma: no cover
|
||||
...
|
||||
|
||||
|
||||
async def app(scope: Scope, receive: ASGIReceiveCallable, send: ASGISendCallable) -> None: # pragma: no cover
|
||||
...
|
||||
|
||||
|
||||
def test_get_subprocess() -> None:
|
||||
fdsock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
|
||||
fd = fdsock.fileno()
|
||||
config = Config(app=app, fd=fd)
|
||||
config.load()
|
||||
|
||||
process = get_subprocess(config, server_run, [fdsock])
|
||||
assert isinstance(process, SpawnProcess)
|
||||
|
||||
fdsock.close()
|
||||
|
||||
|
||||
def test_subprocess_started() -> None:
|
||||
fdsock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
|
||||
fd = fdsock.fileno()
|
||||
config = Config(app=app, fd=fd)
|
||||
config.load()
|
||||
|
||||
with patch("tests.test_subprocess.server_run") as mock_run:
|
||||
with patch.object(config, "configure_logging") as mock_config_logging:
|
||||
subprocess_started(config, server_run, [fdsock], None)
|
||||
mock_run.assert_called_once()
|
||||
mock_config_logging.assert_called_once()
|
||||
|
||||
fdsock.close()
|
||||
@ -1,56 +0,0 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import os
|
||||
import signal
|
||||
import sys
|
||||
from collections.abc import AsyncIterator
|
||||
from contextlib import asynccontextmanager, contextmanager
|
||||
from pathlib import Path
|
||||
from socket import socket
|
||||
|
||||
from uvicorn import Config, Server
|
||||
|
||||
|
||||
@asynccontextmanager
|
||||
async def run_server(config: Config, sockets: list[socket] | None = None) -> AsyncIterator[Server]:
|
||||
server = Server(config=config)
|
||||
task = asyncio.create_task(server.serve(sockets=sockets))
|
||||
while not server.started:
|
||||
await asyncio.sleep(0.05)
|
||||
try:
|
||||
yield server
|
||||
finally:
|
||||
await server.shutdown()
|
||||
task.cancel()
|
||||
|
||||
|
||||
@contextmanager
|
||||
def assert_signal(sig: signal.Signals):
|
||||
"""Check that a signal was received and handled in a block"""
|
||||
seen: set[int] = set()
|
||||
prev_handler = signal.signal(sig, lambda num, frame: seen.add(num))
|
||||
try:
|
||||
yield
|
||||
assert sig in seen, f"process signal {signal.Signals(sig)!r} was not received or handled"
|
||||
finally:
|
||||
signal.signal(sig, prev_handler)
|
||||
|
||||
|
||||
@contextmanager
|
||||
def as_cwd(path: Path):
|
||||
"""Changes working directory and returns to previous on exit."""
|
||||
prev_cwd = Path.cwd()
|
||||
os.chdir(path)
|
||||
try:
|
||||
yield
|
||||
finally:
|
||||
os.chdir(prev_cwd)
|
||||
|
||||
|
||||
def get_asyncio_default_loop_per_os() -> type[asyncio.AbstractEventLoop]:
|
||||
"""Get the default asyncio loop per OS."""
|
||||
if sys.platform == "win32":
|
||||
return asyncio.ProactorEventLoop # type: ignore # pragma: nocover
|
||||
else:
|
||||
return asyncio.SelectorEventLoop # pragma: nocover
|
||||
70
tools/cli_usage.py
Normal file
70
tools/cli_usage.py
Normal file
@ -0,0 +1,70 @@
|
||||
"""
|
||||
Look for a marker comment in docs pages, and place the output of
|
||||
`$ uvicorn --help` there. Pass `--check` to ensure the content is in sync.
|
||||
"""
|
||||
import argparse
|
||||
import subprocess
|
||||
import sys
|
||||
import typing
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
def _get_usage_lines() -> typing.List[str]:
|
||||
res = subprocess.run(["uvicorn", "--help"], stdout=subprocess.PIPE)
|
||||
help_text = res.stdout.decode("utf-8")
|
||||
return ["```", "$ uvicorn --help", *help_text.splitlines(), "```"]
|
||||
|
||||
|
||||
def _find_next_codefence_lineno(lines: typing.List[str], after: int) -> int:
|
||||
return next(
|
||||
lineno for lineno, line in enumerate(lines[after:], after) if line == "```"
|
||||
)
|
||||
|
||||
|
||||
def _get_insert_location(lines: typing.List[str]) -> typing.Tuple[int, int]:
|
||||
marker = lines.index("<!-- :cli_usage: -->")
|
||||
start = marker + 1
|
||||
|
||||
if lines[start] == "```":
|
||||
# Already generated.
|
||||
# <!-- :cli_usage: -->
|
||||
# ``` <- start
|
||||
# [...]
|
||||
# ``` <- end
|
||||
next_codefence = _find_next_codefence_lineno(lines, after=start + 1)
|
||||
end = next_codefence + 1
|
||||
else:
|
||||
# Not generated yet.
|
||||
end = start
|
||||
|
||||
return start, end
|
||||
|
||||
|
||||
def _generate_cli_usage(path: Path, check: bool = False) -> int:
|
||||
content = path.read_text()
|
||||
|
||||
lines = content.splitlines()
|
||||
usage_lines = _get_usage_lines()
|
||||
start, end = _get_insert_location(lines)
|
||||
lines = lines[:start] + usage_lines + lines[end:]
|
||||
output = "\n".join(lines) + "\n"
|
||||
|
||||
if check:
|
||||
if content == output:
|
||||
return 0
|
||||
print(f"ERROR: CLI usage in {path} is out of sync. Run scripts/lint to fix.")
|
||||
return 1
|
||||
|
||||
path.write_text(output)
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
parser = argparse.ArgumentParser()
|
||||
parser.add_argument("--check", action="store_true")
|
||||
args = parser.parse_args()
|
||||
paths = [Path("docs", "index.md"), Path("docs", "deployment.md")]
|
||||
rv = 0
|
||||
for path in paths:
|
||||
rv |= _generate_cli_usage(path, check=args.check)
|
||||
sys.exit(rv)
|
||||
@ -1,5 +1,5 @@
|
||||
from uvicorn.config import Config
|
||||
from uvicorn.main import Server, main, run
|
||||
|
||||
__version__ = "0.47.0"
|
||||
__version__ = "0.13.1"
|
||||
__all__ = ["main", "run", "Config", "Server"]
|
||||
|
||||
@ -1,91 +0,0 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import sys
|
||||
from collections.abc import Callable, Coroutine
|
||||
from typing import Any, TypeVar
|
||||
|
||||
__all__ = ["asyncio_run", "iscoroutinefunction"]
|
||||
|
||||
if sys.version_info >= (3, 14):
|
||||
from inspect import iscoroutinefunction
|
||||
else:
|
||||
from asyncio import iscoroutinefunction
|
||||
|
||||
_T = TypeVar("_T")
|
||||
|
||||
if sys.version_info >= (3, 12):
|
||||
asyncio_run = asyncio.run
|
||||
elif sys.version_info >= (3, 11):
|
||||
|
||||
def asyncio_run(
|
||||
main: Coroutine[Any, Any, _T],
|
||||
*,
|
||||
debug: bool = False,
|
||||
loop_factory: Callable[[], asyncio.AbstractEventLoop] | None = None,
|
||||
) -> _T:
|
||||
# asyncio.run from Python 3.12
|
||||
# https://docs.python.org/3/license.html#psf-license
|
||||
with asyncio.Runner(debug=debug, loop_factory=loop_factory) as runner:
|
||||
return runner.run(main)
|
||||
|
||||
else:
|
||||
# modified version of asyncio.run from Python 3.10 to add loop_factory kwarg
|
||||
# https://docs.python.org/3/license.html#psf-license
|
||||
def asyncio_run(
|
||||
main: Coroutine[Any, Any, _T],
|
||||
*,
|
||||
debug: bool = False,
|
||||
loop_factory: Callable[[], asyncio.AbstractEventLoop] | None = None,
|
||||
) -> _T:
|
||||
try:
|
||||
asyncio.get_running_loop()
|
||||
except RuntimeError:
|
||||
pass
|
||||
else:
|
||||
raise RuntimeError("asyncio.run() cannot be called from a running event loop")
|
||||
|
||||
if not asyncio.iscoroutine(main):
|
||||
raise ValueError(f"a coroutine was expected, got {main!r}")
|
||||
|
||||
if loop_factory is None:
|
||||
loop = asyncio.new_event_loop()
|
||||
else:
|
||||
loop = loop_factory()
|
||||
try:
|
||||
if loop_factory is None:
|
||||
asyncio.set_event_loop(loop)
|
||||
if debug is not None:
|
||||
loop.set_debug(debug)
|
||||
return loop.run_until_complete(main)
|
||||
finally:
|
||||
try:
|
||||
_cancel_all_tasks(loop)
|
||||
loop.run_until_complete(loop.shutdown_asyncgens())
|
||||
loop.run_until_complete(loop.shutdown_default_executor())
|
||||
finally:
|
||||
if loop_factory is None:
|
||||
asyncio.set_event_loop(None)
|
||||
loop.close()
|
||||
|
||||
def _cancel_all_tasks(loop: asyncio.AbstractEventLoop) -> None:
|
||||
to_cancel = asyncio.all_tasks(loop)
|
||||
if not to_cancel:
|
||||
return
|
||||
|
||||
for task in to_cancel:
|
||||
task.cancel()
|
||||
|
||||
loop.run_until_complete(asyncio.gather(*to_cancel, return_exceptions=True))
|
||||
|
||||
for task in to_cancel:
|
||||
if task.cancelled():
|
||||
continue
|
||||
if task.exception() is not None:
|
||||
loop.call_exception_handler(
|
||||
{
|
||||
"message": "unhandled exception during asyncio.run() shutdown",
|
||||
"exception": task.exception(),
|
||||
"task": task,
|
||||
}
|
||||
)
|
||||
@ -1,274 +1,31 @@
|
||||
"""
|
||||
Copyright (c) Django Software Foundation and individual contributors.
|
||||
All rights reserved.
|
||||
|
||||
Redistribution and use in source and binary forms, with or without modification,
|
||||
are permitted provided that the following conditions are met:
|
||||
|
||||
1. Redistributions of source code must retain the above copyright notice,
|
||||
this list of conditions and the following disclaimer.
|
||||
|
||||
2. Redistributions in binary form must reproduce the above copyright
|
||||
notice, this list of conditions and the following disclaimer in the
|
||||
documentation and/or other materials provided with the distribution.
|
||||
|
||||
3. Neither the name of Django nor the names of its contributors may be used
|
||||
to endorse or promote products derived from this software without
|
||||
specific prior written permission.
|
||||
|
||||
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
|
||||
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
||||
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
||||
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
|
||||
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
||||
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
||||
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
|
||||
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||||
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
||||
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import sys
|
||||
import types
|
||||
from collections.abc import Awaitable, Callable, Iterable, MutableMapping
|
||||
from typing import Any, Literal, Protocol, TypedDict
|
||||
from typing import Optional
|
||||
|
||||
if sys.version_info >= (3, 11): # pragma: py-lt-311
|
||||
from typing import NotRequired
|
||||
else: # pragma: py-gte-311
|
||||
from typing_extensions import NotRequired
|
||||
|
||||
# WSGI
|
||||
Environ = MutableMapping[str, Any]
|
||||
ExcInfo = tuple[type[BaseException], BaseException, types.TracebackType | None]
|
||||
StartResponse = Callable[[str, Iterable[tuple[str, str]], ExcInfo | None], None]
|
||||
WSGIApp = Callable[[Environ, StartResponse], Iterable[bytes] | BaseException]
|
||||
if sys.version_info < (3, 8):
|
||||
from typing_extensions import Literal, TypedDict
|
||||
else:
|
||||
from typing import Literal, TypedDict
|
||||
|
||||
|
||||
# ASGI
|
||||
class ASGIVersions(TypedDict):
|
||||
spec_version: str
|
||||
version: Literal["2.0"] | Literal["3.0"]
|
||||
|
||||
|
||||
class HTTPScope(TypedDict):
|
||||
type: Literal["http"]
|
||||
asgi: ASGIVersions
|
||||
http_version: str
|
||||
method: str
|
||||
scheme: str
|
||||
path: str
|
||||
raw_path: bytes
|
||||
query_string: bytes
|
||||
root_path: str
|
||||
headers: Iterable[tuple[bytes, bytes]]
|
||||
client: tuple[str, int] | None
|
||||
server: tuple[str, int | None] | None
|
||||
state: NotRequired[dict[str, Any]]
|
||||
extensions: NotRequired[dict[str, dict[object, object]]]
|
||||
|
||||
|
||||
class WebSocketScope(TypedDict):
|
||||
type: Literal["websocket"]
|
||||
asgi: ASGIVersions
|
||||
http_version: str
|
||||
scheme: str
|
||||
path: str
|
||||
raw_path: bytes
|
||||
query_string: bytes
|
||||
root_path: str
|
||||
headers: Iterable[tuple[bytes, bytes]]
|
||||
client: tuple[str, int] | None
|
||||
server: tuple[str, int | None] | None
|
||||
subprotocols: Iterable[str]
|
||||
state: NotRequired[dict[str, Any]]
|
||||
extensions: NotRequired[dict[str, dict[object, object]]]
|
||||
class ASGISpecInfo(TypedDict):
|
||||
version: str
|
||||
spec_version: Optional[Literal["2.0", "2.1"]]
|
||||
|
||||
|
||||
class LifespanScope(TypedDict):
|
||||
type: Literal["lifespan"]
|
||||
asgi: ASGIVersions
|
||||
state: NotRequired[dict[str, Any]]
|
||||
asgi: ASGISpecInfo
|
||||
|
||||
|
||||
WWWScope = HTTPScope | WebSocketScope
|
||||
Scope = HTTPScope | WebSocketScope | LifespanScope
|
||||
class LifespanReceiveMessage(TypedDict):
|
||||
type: Literal["lifespan.startup", "lifespan.shutdown"]
|
||||
|
||||
|
||||
class HTTPRequestEvent(TypedDict):
|
||||
type: Literal["http.request"]
|
||||
body: bytes
|
||||
more_body: bool
|
||||
|
||||
|
||||
class HTTPResponseDebugEvent(TypedDict):
|
||||
type: Literal["http.response.debug"]
|
||||
info: dict[str, object]
|
||||
|
||||
|
||||
class HTTPResponseStartEvent(TypedDict):
|
||||
type: Literal["http.response.start"]
|
||||
status: int
|
||||
headers: NotRequired[Iterable[tuple[bytes, bytes]]]
|
||||
trailers: NotRequired[bool]
|
||||
|
||||
|
||||
class HTTPResponseBodyEvent(TypedDict):
|
||||
type: Literal["http.response.body"]
|
||||
body: bytes
|
||||
more_body: NotRequired[bool]
|
||||
|
||||
|
||||
class HTTPResponseTrailersEvent(TypedDict):
|
||||
type: Literal["http.response.trailers"]
|
||||
headers: Iterable[tuple[bytes, bytes]]
|
||||
more_trailers: bool
|
||||
|
||||
|
||||
class HTTPServerPushEvent(TypedDict):
|
||||
type: Literal["http.response.push"]
|
||||
path: str
|
||||
headers: Iterable[tuple[bytes, bytes]]
|
||||
|
||||
|
||||
class HTTPDisconnectEvent(TypedDict):
|
||||
type: Literal["http.disconnect"]
|
||||
|
||||
|
||||
class WebSocketConnectEvent(TypedDict):
|
||||
type: Literal["websocket.connect"]
|
||||
|
||||
|
||||
class WebSocketAcceptEvent(TypedDict):
|
||||
type: Literal["websocket.accept"]
|
||||
subprotocol: NotRequired[str | None]
|
||||
headers: NotRequired[Iterable[tuple[bytes, bytes]]]
|
||||
|
||||
|
||||
class _WebSocketReceiveEventBytes(TypedDict):
|
||||
type: Literal["websocket.receive"]
|
||||
bytes: bytes
|
||||
text: NotRequired[None]
|
||||
|
||||
|
||||
class _WebSocketReceiveEventText(TypedDict):
|
||||
type: Literal["websocket.receive"]
|
||||
bytes: NotRequired[None]
|
||||
text: str
|
||||
|
||||
|
||||
WebSocketReceiveEvent = _WebSocketReceiveEventBytes | _WebSocketReceiveEventText
|
||||
|
||||
|
||||
class _WebSocketSendEventBytes(TypedDict):
|
||||
type: Literal["websocket.send"]
|
||||
bytes: bytes
|
||||
text: NotRequired[None]
|
||||
|
||||
|
||||
class _WebSocketSendEventText(TypedDict):
|
||||
type: Literal["websocket.send"]
|
||||
bytes: NotRequired[None]
|
||||
text: str
|
||||
|
||||
|
||||
WebSocketSendEvent = _WebSocketSendEventBytes | _WebSocketSendEventText
|
||||
|
||||
|
||||
class WebSocketResponseStartEvent(TypedDict):
|
||||
type: Literal["websocket.http.response.start"]
|
||||
status: int
|
||||
headers: Iterable[tuple[bytes, bytes]]
|
||||
|
||||
|
||||
class WebSocketResponseBodyEvent(TypedDict):
|
||||
type: Literal["websocket.http.response.body"]
|
||||
body: bytes
|
||||
more_body: NotRequired[bool]
|
||||
|
||||
|
||||
class WebSocketDisconnectEvent(TypedDict):
|
||||
type: Literal["websocket.disconnect"]
|
||||
code: int
|
||||
reason: NotRequired[str | None]
|
||||
|
||||
|
||||
class WebSocketCloseEvent(TypedDict):
|
||||
type: Literal["websocket.close"]
|
||||
code: NotRequired[int]
|
||||
reason: NotRequired[str | None]
|
||||
|
||||
|
||||
class LifespanStartupEvent(TypedDict):
|
||||
type: Literal["lifespan.startup"]
|
||||
|
||||
|
||||
class LifespanShutdownEvent(TypedDict):
|
||||
type: Literal["lifespan.shutdown"]
|
||||
|
||||
|
||||
class LifespanStartupCompleteEvent(TypedDict):
|
||||
type: Literal["lifespan.startup.complete"]
|
||||
|
||||
|
||||
class LifespanStartupFailedEvent(TypedDict):
|
||||
type: Literal["lifespan.startup.failed"]
|
||||
message: str
|
||||
|
||||
|
||||
class LifespanShutdownCompleteEvent(TypedDict):
|
||||
type: Literal["lifespan.shutdown.complete"]
|
||||
|
||||
|
||||
class LifespanShutdownFailedEvent(TypedDict):
|
||||
type: Literal["lifespan.shutdown.failed"]
|
||||
message: str
|
||||
|
||||
|
||||
WebSocketEvent = WebSocketReceiveEvent | WebSocketDisconnectEvent | WebSocketConnectEvent
|
||||
|
||||
|
||||
ASGIReceiveEvent = (
|
||||
HTTPRequestEvent
|
||||
| HTTPDisconnectEvent
|
||||
| WebSocketConnectEvent
|
||||
| WebSocketReceiveEvent
|
||||
| WebSocketDisconnectEvent
|
||||
| LifespanStartupEvent
|
||||
| LifespanShutdownEvent
|
||||
)
|
||||
|
||||
|
||||
ASGISendEvent = (
|
||||
HTTPResponseStartEvent
|
||||
| HTTPResponseBodyEvent
|
||||
| HTTPResponseTrailersEvent
|
||||
| HTTPServerPushEvent
|
||||
| HTTPDisconnectEvent
|
||||
| WebSocketAcceptEvent
|
||||
| WebSocketSendEvent
|
||||
| WebSocketResponseStartEvent
|
||||
| WebSocketResponseBodyEvent
|
||||
| WebSocketCloseEvent
|
||||
| LifespanStartupCompleteEvent
|
||||
| LifespanStartupFailedEvent
|
||||
| LifespanShutdownCompleteEvent
|
||||
| LifespanShutdownFailedEvent
|
||||
)
|
||||
|
||||
|
||||
ASGIReceiveCallable = Callable[[], Awaitable[ASGIReceiveEvent]]
|
||||
ASGISendCallable = Callable[[ASGISendEvent], Awaitable[None]]
|
||||
|
||||
|
||||
class ASGI2Protocol(Protocol):
|
||||
def __init__(self, scope: Scope) -> None: ... # pragma: no cover
|
||||
|
||||
async def __call__(self, receive: ASGIReceiveCallable, send: ASGISendCallable) -> None: ... # pragma: no cover
|
||||
|
||||
|
||||
ASGI2Application = type[ASGI2Protocol]
|
||||
ASGI3Application = Callable[[Scope, ASGIReceiveCallable, ASGISendCallable], Awaitable[None]]
|
||||
ASGIApplication = ASGI2Application | ASGI3Application
|
||||
class LifespanSendMessage(TypedDict):
|
||||
type: Literal[
|
||||
"lifespan.startup.complete",
|
||||
"lifespan.startup.failed",
|
||||
"lifespan.shutdown.complete",
|
||||
"lifespan.shutdown.failed",
|
||||
]
|
||||
message: Optional[str]
|
||||
|
||||
@ -1,5 +1,3 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import inspect
|
||||
import json
|
||||
@ -9,29 +7,28 @@ import os
|
||||
import socket
|
||||
import ssl
|
||||
import sys
|
||||
from collections.abc import Awaitable, Callable
|
||||
from configparser import RawConfigParser
|
||||
from pathlib import Path
|
||||
from typing import IO, Any, Literal
|
||||
from typing import List, Tuple
|
||||
|
||||
import click
|
||||
|
||||
from uvicorn._compat import iscoroutinefunction
|
||||
from uvicorn._types import ASGIApplication
|
||||
try:
|
||||
import yaml
|
||||
except ImportError:
|
||||
# If the code below that depends on yaml is exercised, it will raise a NameError.
|
||||
# Install the PyYAML package or the uvicorn[standard] optional dependencies to
|
||||
# enable this functionality.
|
||||
pass
|
||||
|
||||
from uvicorn.importer import ImportFromStringError, import_from_string
|
||||
from uvicorn.logging import TRACE_LOG_LEVEL
|
||||
from uvicorn.middleware.asgi2 import ASGI2Middleware
|
||||
from uvicorn.middleware.debug import DebugMiddleware
|
||||
from uvicorn.middleware.message_logger import MessageLoggerMiddleware
|
||||
from uvicorn.middleware.proxy_headers import ProxyHeadersMiddleware
|
||||
from uvicorn.middleware.wsgi import WSGIMiddleware
|
||||
|
||||
HTTPProtocolType = Literal["auto", "h11", "httptools"]
|
||||
WSProtocolType = Literal["auto", "none", "websockets", "websockets-sansio", "wsproto"]
|
||||
LifespanType = Literal["auto", "on", "off"]
|
||||
LoopFactoryType = Literal["none", "auto", "asyncio", "uvloop"]
|
||||
InterfaceType = Literal["auto", "asgi3", "asgi2", "wsgi"]
|
||||
TRACE_LOG_LEVEL = 5
|
||||
|
||||
LOG_LEVELS: dict[str, int] = {
|
||||
LOG_LEVELS = {
|
||||
"critical": logging.CRITICAL,
|
||||
"error": logging.ERROR,
|
||||
"warning": logging.WARNING,
|
||||
@ -39,34 +36,36 @@ LOG_LEVELS: dict[str, int] = {
|
||||
"debug": logging.DEBUG,
|
||||
"trace": TRACE_LOG_LEVEL,
|
||||
}
|
||||
HTTP_PROTOCOLS: dict[str, str] = {
|
||||
HTTP_PROTOCOLS = {
|
||||
"auto": "uvicorn.protocols.http.auto:AutoHTTPProtocol",
|
||||
"h11": "uvicorn.protocols.http.h11_impl:H11Protocol",
|
||||
"httptools": "uvicorn.protocols.http.httptools_impl:HttpToolsProtocol",
|
||||
}
|
||||
WS_PROTOCOLS: dict[str, str | None] = {
|
||||
WS_PROTOCOLS = {
|
||||
"auto": "uvicorn.protocols.websockets.auto:AutoWebSocketsProtocol",
|
||||
"none": None,
|
||||
"websockets": "uvicorn.protocols.websockets.websockets_impl:WebSocketProtocol",
|
||||
"websockets-sansio": "uvicorn.protocols.websockets.websockets_sansio_impl:WebSocketsSansIOProtocol",
|
||||
"wsproto": "uvicorn.protocols.websockets.wsproto_impl:WSProtocol",
|
||||
}
|
||||
LIFESPAN: dict[str, str] = {
|
||||
LIFESPAN = {
|
||||
"auto": "uvicorn.lifespan.on:LifespanOn",
|
||||
"on": "uvicorn.lifespan.on:LifespanOn",
|
||||
"off": "uvicorn.lifespan.off:LifespanOff",
|
||||
}
|
||||
LOOP_FACTORIES: dict[str, str | None] = {
|
||||
LOOP_SETUPS = {
|
||||
"none": None,
|
||||
"auto": "uvicorn.loops.auto:auto_loop_factory",
|
||||
"asyncio": "uvicorn.loops.asyncio:asyncio_loop_factory",
|
||||
"uvloop": "uvicorn.loops.uvloop:uvloop_loop_factory",
|
||||
"auto": "uvicorn.loops.auto:auto_loop_setup",
|
||||
"asyncio": "uvicorn.loops.asyncio:asyncio_setup",
|
||||
"uvloop": "uvicorn.loops.uvloop:uvloop_setup",
|
||||
}
|
||||
INTERFACES: list[InterfaceType] = ["auto", "asgi3", "asgi2", "wsgi"]
|
||||
INTERFACES = ["auto", "asgi3", "asgi2", "wsgi"]
|
||||
|
||||
SSL_PROTOCOL_VERSION: int = ssl.PROTOCOL_TLS_SERVER
|
||||
|
||||
LOGGING_CONFIG: dict[str, Any] = {
|
||||
# Fallback to 'ssl.PROTOCOL_SSLv23' in order to support Python < 3.5.3.
|
||||
SSL_PROTOCOL_VERSION = getattr(ssl, "PROTOCOL_TLS", ssl.PROTOCOL_SSLv23)
|
||||
|
||||
|
||||
LOGGING_CONFIG = {
|
||||
"version": 1,
|
||||
"disable_existing_loggers": False,
|
||||
"formatters": {
|
||||
@ -93,7 +92,7 @@ LOGGING_CONFIG: dict[str, Any] = {
|
||||
},
|
||||
},
|
||||
"loggers": {
|
||||
"uvicorn": {"handlers": ["default"], "level": "INFO", "propagate": False},
|
||||
"uvicorn": {"handlers": ["default"], "level": "INFO"},
|
||||
"uvicorn.error": {"level": "INFO"},
|
||||
"uvicorn.access": {"handlers": ["access"], "level": "INFO", "propagate": False},
|
||||
},
|
||||
@ -103,18 +102,12 @@ logger = logging.getLogger("uvicorn.error")
|
||||
|
||||
|
||||
def create_ssl_context(
|
||||
certfile: str | os.PathLike[str],
|
||||
keyfile: str | os.PathLike[str] | None,
|
||||
password: str | None,
|
||||
ssl_version: int,
|
||||
cert_reqs: int,
|
||||
ca_certs: str | os.PathLike[str] | None,
|
||||
ciphers: str | None,
|
||||
) -> ssl.SSLContext:
|
||||
certfile, keyfile, password, ssl_version, cert_reqs, ca_certs, ciphers
|
||||
):
|
||||
ctx = ssl.SSLContext(ssl_version)
|
||||
get_password = (lambda: password) if password else None
|
||||
ctx.load_cert_chain(certfile, keyfile, get_password)
|
||||
ctx.verify_mode = ssl.VerifyMode(cert_reqs)
|
||||
ctx.verify_mode = cert_reqs
|
||||
if ca_certs:
|
||||
ctx.load_verify_locations(ca_certs)
|
||||
if ciphers:
|
||||
@ -122,114 +115,47 @@ def create_ssl_context(
|
||||
return ctx
|
||||
|
||||
|
||||
def is_dir(path: Path) -> bool:
|
||||
try:
|
||||
if not path.is_absolute():
|
||||
path = path.resolve()
|
||||
return path.is_dir()
|
||||
except OSError: # pragma: full coverage
|
||||
return False
|
||||
|
||||
|
||||
def resolve_reload_patterns(patterns_list: list[str], directories_list: list[str]) -> tuple[list[str], list[Path]]:
|
||||
directories: list[Path] = list(set(map(Path, directories_list.copy())))
|
||||
patterns: list[str] = patterns_list.copy()
|
||||
|
||||
current_working_directory = Path.cwd()
|
||||
for pattern in patterns_list:
|
||||
# Special case for the .* pattern, otherwise this would only match
|
||||
# hidden directories which is probably undesired
|
||||
if pattern == ".*":
|
||||
continue # pragma: py-not-linux
|
||||
patterns.append(pattern)
|
||||
if is_dir(Path(pattern)):
|
||||
directories.append(Path(pattern))
|
||||
else:
|
||||
for match in current_working_directory.glob(pattern):
|
||||
if is_dir(match):
|
||||
directories.append(match)
|
||||
|
||||
directories = list(set(directories))
|
||||
directories = list(map(Path, directories))
|
||||
directories = list(map(lambda x: x.resolve(), directories))
|
||||
directories = list({reload_path for reload_path in directories if is_dir(reload_path)})
|
||||
|
||||
children = []
|
||||
for j in range(len(directories)):
|
||||
for k in range(j + 1, len(directories)): # pragma: full coverage
|
||||
if directories[j] in directories[k].parents:
|
||||
children.append(directories[k])
|
||||
elif directories[k] in directories[j].parents:
|
||||
children.append(directories[j])
|
||||
|
||||
directories = list(set(directories).difference(set(children)))
|
||||
|
||||
return list(set(patterns)), directories
|
||||
|
||||
|
||||
def _normalize_dirs(dirs: list[str] | str | None) -> list[str]:
|
||||
if dirs is None:
|
||||
return []
|
||||
if isinstance(dirs, str):
|
||||
return [dirs]
|
||||
return list(set(dirs))
|
||||
|
||||
|
||||
class Config:
|
||||
def __init__(
|
||||
self,
|
||||
app: ASGIApplication | Callable[..., Any] | str,
|
||||
host: str = "127.0.0.1",
|
||||
port: int = 8000,
|
||||
uds: str | None = None,
|
||||
fd: int | None = None,
|
||||
loop: LoopFactoryType | str = "auto",
|
||||
http: type[asyncio.Protocol] | HTTPProtocolType | str = "auto",
|
||||
ws: type[asyncio.Protocol] | WSProtocolType | str = "auto",
|
||||
ws_max_size: int = 16 * 1024 * 1024,
|
||||
ws_max_queue: int = 32,
|
||||
ws_ping_interval: float | None = 20.0,
|
||||
ws_ping_timeout: float | None = 20.0,
|
||||
ws_per_message_deflate: bool = True,
|
||||
lifespan: LifespanType = "auto",
|
||||
env_file: str | os.PathLike[str] | None = None,
|
||||
log_config: dict[str, Any] | str | os.PathLike[str] | RawConfigParser | IO[Any] | None = LOGGING_CONFIG,
|
||||
log_level: str | int | None = None,
|
||||
access_log: bool = True,
|
||||
use_colors: bool | None = None,
|
||||
interface: InterfaceType = "auto",
|
||||
reload: bool = False,
|
||||
reload_dirs: list[str] | str | None = None,
|
||||
reload_delay: float = 0.25,
|
||||
reload_includes: list[str] | str | None = None,
|
||||
reload_excludes: list[str] | str | None = None,
|
||||
workers: int | None = None,
|
||||
proxy_headers: bool = True,
|
||||
server_header: bool = True,
|
||||
date_header: bool = True,
|
||||
forwarded_allow_ips: list[str] | str | None = None,
|
||||
root_path: str = "",
|
||||
limit_concurrency: int | None = None,
|
||||
limit_max_requests: int | None = None,
|
||||
limit_max_requests_jitter: int = 0,
|
||||
backlog: int = 2048,
|
||||
timeout_keep_alive: int = 5,
|
||||
timeout_notify: int = 30,
|
||||
timeout_graceful_shutdown: int | None = None,
|
||||
timeout_worker_healthcheck: int = 5,
|
||||
callback_notify: Callable[..., Awaitable[None]] | None = None,
|
||||
ssl_keyfile: str | os.PathLike[str] | None = None,
|
||||
ssl_certfile: str | os.PathLike[str] | None = None,
|
||||
ssl_keyfile_password: str | None = None,
|
||||
ssl_version: int = SSL_PROTOCOL_VERSION,
|
||||
ssl_cert_reqs: int = ssl.CERT_NONE,
|
||||
ssl_ca_certs: str | os.PathLike[str] | None = None,
|
||||
ssl_ciphers: str = "TLSv1",
|
||||
ssl_context_factory: Callable[[Config, Callable[[], ssl.SSLContext]], ssl.SSLContext] | None = None,
|
||||
headers: list[tuple[str, str]] | None = None,
|
||||
factory: bool = False,
|
||||
h11_max_incomplete_event_size: int | None = None,
|
||||
reset_contextvars: bool = False,
|
||||
app,
|
||||
host="127.0.0.1",
|
||||
port=8000,
|
||||
uds=None,
|
||||
fd=None,
|
||||
loop="auto",
|
||||
http="auto",
|
||||
ws="auto",
|
||||
lifespan="auto",
|
||||
env_file=None,
|
||||
log_config=LOGGING_CONFIG,
|
||||
log_level=None,
|
||||
access_log=True,
|
||||
use_colors=None,
|
||||
interface="auto",
|
||||
debug=False,
|
||||
reload=False,
|
||||
reload_dirs=None,
|
||||
reload_delay=None,
|
||||
workers=None,
|
||||
proxy_headers=True,
|
||||
forwarded_allow_ips=None,
|
||||
root_path="",
|
||||
limit_concurrency=None,
|
||||
limit_max_requests=None,
|
||||
backlog=2048,
|
||||
timeout_keep_alive=5,
|
||||
timeout_notify=30,
|
||||
callback_notify=None,
|
||||
ssl_keyfile=None,
|
||||
ssl_certfile=None,
|
||||
ssl_keyfile_password=None,
|
||||
ssl_version=SSL_PROTOCOL_VERSION,
|
||||
ssl_cert_reqs=ssl.CERT_NONE,
|
||||
ssl_ca_certs=None,
|
||||
ssl_ciphers="TLSv1",
|
||||
headers=None,
|
||||
factory=False,
|
||||
):
|
||||
self.app = app
|
||||
self.host = host
|
||||
@ -239,32 +165,23 @@ class Config:
|
||||
self.loop = loop
|
||||
self.http = http
|
||||
self.ws = ws
|
||||
self.ws_max_size = ws_max_size
|
||||
self.ws_max_queue = ws_max_queue
|
||||
self.ws_ping_interval = ws_ping_interval
|
||||
self.ws_ping_timeout = ws_ping_timeout
|
||||
self.ws_per_message_deflate = ws_per_message_deflate
|
||||
self.lifespan = lifespan
|
||||
self.log_config = log_config
|
||||
self.log_level = log_level
|
||||
self.access_log = access_log
|
||||
self.use_colors = use_colors
|
||||
self.interface = interface
|
||||
self.debug = debug
|
||||
self.reload = reload
|
||||
self.reload_delay = reload_delay
|
||||
self.reload_delay = reload_delay or 0.25
|
||||
self.workers = workers or 1
|
||||
self.proxy_headers = proxy_headers
|
||||
self.server_header = server_header
|
||||
self.date_header = date_header
|
||||
self.root_path = root_path
|
||||
self.limit_concurrency = limit_concurrency
|
||||
self.limit_max_requests = limit_max_requests
|
||||
self.limit_max_requests_jitter = limit_max_requests_jitter
|
||||
self.backlog = backlog
|
||||
self.timeout_keep_alive = timeout_keep_alive
|
||||
self.timeout_notify = timeout_notify
|
||||
self.timeout_graceful_shutdown = timeout_graceful_shutdown
|
||||
self.timeout_worker_healthcheck = timeout_worker_healthcheck
|
||||
self.callback_notify = callback_notify
|
||||
self.ssl_keyfile = ssl_keyfile
|
||||
self.ssl_certfile = ssl_certfile
|
||||
@ -273,62 +190,17 @@ class Config:
|
||||
self.ssl_cert_reqs = ssl_cert_reqs
|
||||
self.ssl_ca_certs = ssl_ca_certs
|
||||
self.ssl_ciphers = ssl_ciphers
|
||||
self.ssl_context_factory = ssl_context_factory
|
||||
self.headers: list[tuple[str, str]] = headers or []
|
||||
self.encoded_headers: list[tuple[bytes, bytes]] = []
|
||||
self.headers = headers if headers else [] # type: List[str]
|
||||
self.encoded_headers = None # type: List[Tuple[bytes, bytes]]
|
||||
self.factory = factory
|
||||
self.h11_max_incomplete_event_size = h11_max_incomplete_event_size
|
||||
self.reset_contextvars = reset_contextvars
|
||||
|
||||
self.loaded = False
|
||||
self.configure_logging()
|
||||
|
||||
self.reload_dirs: list[Path] = []
|
||||
self.reload_dirs_excludes: list[Path] = []
|
||||
self.reload_includes: list[str] = []
|
||||
self.reload_excludes: list[str] = []
|
||||
|
||||
if (reload_dirs or reload_includes or reload_excludes) and not self.should_reload:
|
||||
logger.warning(
|
||||
"Current configuration will not reload as not all conditions are met, please refer to documentation."
|
||||
)
|
||||
|
||||
if self.should_reload:
|
||||
reload_dirs = _normalize_dirs(reload_dirs)
|
||||
reload_includes = _normalize_dirs(reload_includes)
|
||||
reload_excludes = _normalize_dirs(reload_excludes)
|
||||
|
||||
self.reload_includes, self.reload_dirs = resolve_reload_patterns(reload_includes, reload_dirs)
|
||||
|
||||
self.reload_excludes, self.reload_dirs_excludes = resolve_reload_patterns(reload_excludes, [])
|
||||
|
||||
reload_dirs_tmp = self.reload_dirs.copy()
|
||||
|
||||
for directory in self.reload_dirs_excludes:
|
||||
for reload_directory in reload_dirs_tmp:
|
||||
if directory == reload_directory or directory in reload_directory.parents:
|
||||
try:
|
||||
self.reload_dirs.remove(reload_directory)
|
||||
except ValueError: # pragma: full coverage
|
||||
pass
|
||||
|
||||
for pattern in self.reload_excludes:
|
||||
if pattern in self.reload_includes:
|
||||
self.reload_includes.remove(pattern) # pragma: full coverage
|
||||
|
||||
if not self.reload_dirs:
|
||||
if reload_dirs:
|
||||
logger.warning(
|
||||
"Provided reload directories %s did not contain valid "
|
||||
+ "directories, watching current working directory.",
|
||||
reload_dirs,
|
||||
)
|
||||
self.reload_dirs = [Path.cwd()]
|
||||
|
||||
logger.info(
|
||||
"Will watch for changes in these directories: %s",
|
||||
sorted(list(map(str, self.reload_dirs))),
|
||||
)
|
||||
if reload_dirs is None:
|
||||
self.reload_dirs = [os.getcwd()]
|
||||
else:
|
||||
self.reload_dirs = reload_dirs
|
||||
|
||||
if env_file is not None:
|
||||
from dotenv import load_dotenv
|
||||
@ -339,67 +211,52 @@ class Config:
|
||||
if workers is None and "WEB_CONCURRENCY" in os.environ:
|
||||
self.workers = int(os.environ["WEB_CONCURRENCY"])
|
||||
|
||||
self.forwarded_allow_ips: list[str] | str
|
||||
if forwarded_allow_ips is None:
|
||||
self.forwarded_allow_ips = os.environ.get("FORWARDED_ALLOW_IPS", "127.0.0.1")
|
||||
self.forwarded_allow_ips = os.environ.get(
|
||||
"FORWARDED_ALLOW_IPS", "127.0.0.1"
|
||||
)
|
||||
else:
|
||||
self.forwarded_allow_ips = forwarded_allow_ips # pragma: full coverage
|
||||
|
||||
if self.reload and self.workers > 1:
|
||||
logger.warning('"workers" flag is ignored when reloading is enabled.')
|
||||
self.forwarded_allow_ips = forwarded_allow_ips
|
||||
|
||||
@property
|
||||
def asgi_version(self) -> Literal["2.0", "3.0"]:
|
||||
mapping: dict[str, Literal["2.0", "3.0"]] = {
|
||||
"asgi2": "2.0",
|
||||
"asgi3": "3.0",
|
||||
"wsgi": "3.0",
|
||||
}
|
||||
return mapping[self.interface]
|
||||
def asgi_version(self) -> str:
|
||||
return {"asgi2": "2.0", "asgi3": "3.0", "wsgi": "3.0"}[self.interface]
|
||||
|
||||
@property
|
||||
def is_ssl(self) -> bool:
|
||||
return bool(self.ssl_keyfile or self.ssl_certfile or self.ssl_context_factory)
|
||||
return bool(self.ssl_keyfile or self.ssl_certfile)
|
||||
|
||||
@property
|
||||
def use_subprocess(self) -> bool:
|
||||
return bool(self.reload or self.workers > 1)
|
||||
|
||||
def configure_logging(self) -> None:
|
||||
def configure_logging(self):
|
||||
logging.addLevelName(TRACE_LOG_LEVEL, "TRACE")
|
||||
|
||||
if self.log_config is not None:
|
||||
if isinstance(self.log_config, os.PathLike):
|
||||
self.log_config = os.fspath(self.log_config)
|
||||
|
||||
if isinstance(self.log_config, dict):
|
||||
if self.use_colors in (True, False):
|
||||
self.log_config["formatters"]["default"]["use_colors"] = self.use_colors
|
||||
self.log_config["formatters"]["access"]["use_colors"] = self.use_colors
|
||||
self.log_config["formatters"]["default"][
|
||||
"use_colors"
|
||||
] = self.use_colors
|
||||
self.log_config["formatters"]["access"][
|
||||
"use_colors"
|
||||
] = self.use_colors
|
||||
logging.config.dictConfig(self.log_config)
|
||||
elif isinstance(self.log_config, str) and self.log_config.endswith(".json"):
|
||||
elif self.log_config.endswith(".json"):
|
||||
with open(self.log_config) as file:
|
||||
loaded_config = json.load(file)
|
||||
logging.config.dictConfig(loaded_config)
|
||||
elif isinstance(self.log_config, str) and self.log_config.endswith((".yaml", ".yml")):
|
||||
try:
|
||||
import yaml
|
||||
except ImportError as e:
|
||||
raise ImportError(
|
||||
"Install the PyYAML package or uvicorn[standard] to use `--log-config` with YAML files."
|
||||
) from e
|
||||
|
||||
elif self.log_config.endswith((".yaml", ".yml")):
|
||||
with open(self.log_config) as file:
|
||||
loaded_config = yaml.safe_load(file)
|
||||
logging.config.dictConfig(loaded_config)
|
||||
else:
|
||||
# See the note about fileConfig() here:
|
||||
# https://docs.python.org/3/library/logging.config.html#configuration-file-format
|
||||
logging.config.fileConfig(self.log_config, disable_existing_loggers=False)
|
||||
logging.config.fileConfig(
|
||||
self.log_config, disable_existing_loggers=False
|
||||
)
|
||||
|
||||
if self.log_level is not None:
|
||||
if isinstance(self.log_level, str):
|
||||
log_level = LOG_LEVELS[self.log_level.lower()]
|
||||
log_level = LOG_LEVELS[self.log_level]
|
||||
else:
|
||||
log_level = self.log_level
|
||||
logging.getLogger("uvicorn.error").setLevel(log_level)
|
||||
@ -409,42 +266,10 @@ class Config:
|
||||
logging.getLogger("uvicorn.access").handlers = []
|
||||
logging.getLogger("uvicorn.access").propagate = False
|
||||
|
||||
def load_app(self) -> Any:
|
||||
"""Import the app and return it. Exits on failure."""
|
||||
try:
|
||||
return import_from_string(self.app)
|
||||
except ImportFromStringError as exc:
|
||||
logger.error("Error loading ASGI app. %s" % exc)
|
||||
sys.exit(1)
|
||||
|
||||
def load(self) -> None:
|
||||
def load(self):
|
||||
assert not self.loaded
|
||||
|
||||
if self.ssl_context_factory is not None:
|
||||
|
||||
def default_factory() -> ssl.SSLContext:
|
||||
if not self.ssl_certfile:
|
||||
raise RuntimeError(
|
||||
"`default_ssl_context_factory()` requires `ssl_certfile` to be set on `Config`. "
|
||||
"Either pass `ssl_certfile` (and optionally `ssl_keyfile`) or build the `SSLContext` "
|
||||
"directly inside `ssl_context_factory` without calling the default factory."
|
||||
)
|
||||
return create_ssl_context(
|
||||
keyfile=self.ssl_keyfile,
|
||||
certfile=self.ssl_certfile,
|
||||
password=self.ssl_keyfile_password,
|
||||
ssl_version=self.ssl_version,
|
||||
cert_reqs=self.ssl_cert_reqs,
|
||||
ca_certs=self.ssl_ca_certs,
|
||||
ciphers=self.ssl_ciphers,
|
||||
)
|
||||
|
||||
context = self.ssl_context_factory(self, default_factory)
|
||||
if not isinstance(context, ssl.SSLContext):
|
||||
raise TypeError(f"`ssl_context_factory` must return an `ssl.SSLContext`, got {type(context).__name__}")
|
||||
self.ssl: ssl.SSLContext | None = context
|
||||
elif self.is_ssl:
|
||||
assert self.ssl_certfile
|
||||
if self.is_ssl:
|
||||
self.ssl = create_ssl_context(
|
||||
keyfile=self.ssl_keyfile,
|
||||
certfile=self.ssl_certfile,
|
||||
@ -457,49 +282,55 @@ class Config:
|
||||
else:
|
||||
self.ssl = None
|
||||
|
||||
encoded_headers = [(key.lower().encode("latin1"), value.encode("latin1")) for key, value in self.headers]
|
||||
encoded_headers = [
|
||||
(key.lower().encode("latin1"), value.encode("latin1"))
|
||||
for key, value in self.headers
|
||||
]
|
||||
self.encoded_headers = (
|
||||
[(b"server", b"uvicorn")] + encoded_headers
|
||||
if b"server" not in dict(encoded_headers) and self.server_header
|
||||
else encoded_headers
|
||||
)
|
||||
encoded_headers
|
||||
if b"server" in dict(encoded_headers)
|
||||
else [(b"server", b"uvicorn")] + encoded_headers
|
||||
) # type: List[Tuple[bytes, bytes]]
|
||||
|
||||
if isinstance(self.http, str):
|
||||
http_protocol_class = import_from_string(HTTP_PROTOCOLS.get(self.http, self.http))
|
||||
self.http_protocol_class: type[asyncio.Protocol] = http_protocol_class
|
||||
self.http_protocol_class = import_from_string(HTTP_PROTOCOLS[self.http])
|
||||
else:
|
||||
self.http_protocol_class = self.http
|
||||
|
||||
if isinstance(self.ws, str):
|
||||
ws_protocol_class = import_from_string(WS_PROTOCOLS.get(self.ws, self.ws))
|
||||
self.ws_protocol_class: type[asyncio.Protocol] | None = ws_protocol_class
|
||||
self.ws_protocol_class = import_from_string(WS_PROTOCOLS[self.ws])
|
||||
else:
|
||||
self.ws_protocol_class = self.ws
|
||||
|
||||
self.lifespan_class = import_from_string(LIFESPAN[self.lifespan])
|
||||
|
||||
self.loaded_app = self.load_app()
|
||||
|
||||
try:
|
||||
self.loaded_app = self.loaded_app()
|
||||
except TypeError as exc:
|
||||
if self.factory:
|
||||
self.loaded_app = import_from_string(self.app)
|
||||
except ImportFromStringError as exc:
|
||||
logger.error("Error loading ASGI app. %s" % exc)
|
||||
sys.exit(1)
|
||||
|
||||
if self.factory:
|
||||
try:
|
||||
self.loaded_app = self.loaded_app()
|
||||
except TypeError as exc:
|
||||
logger.error("Error loading ASGI app factory: %s", exc)
|
||||
sys.exit(1)
|
||||
else:
|
||||
if not self.factory:
|
||||
logger.warning(
|
||||
"ASGI app factory detected. Using it, but please consider setting the --factory flag explicitly."
|
||||
)
|
||||
elif not inspect.signature(self.loaded_app).parameters:
|
||||
logger.error(
|
||||
"APP seems to be an application factory. "
|
||||
"Run uvicorn with the --factory flag."
|
||||
)
|
||||
sys.exit(1)
|
||||
|
||||
if self.interface == "auto":
|
||||
if inspect.isclass(self.loaded_app):
|
||||
use_asgi_3 = hasattr(self.loaded_app, "__await__")
|
||||
elif inspect.isfunction(self.loaded_app):
|
||||
use_asgi_3 = iscoroutinefunction(self.loaded_app)
|
||||
use_asgi_3 = asyncio.iscoroutinefunction(self.loaded_app)
|
||||
else:
|
||||
call = getattr(self.loaded_app, "__call__", None)
|
||||
use_asgi_3 = iscoroutinefunction(call)
|
||||
use_asgi_3 = asyncio.iscoroutinefunction(call)
|
||||
self.interface = "asgi3" if use_asgi_3 else "asgi2"
|
||||
|
||||
if self.interface == "wsgi":
|
||||
@ -508,81 +339,56 @@ class Config:
|
||||
elif self.interface == "asgi2":
|
||||
self.loaded_app = ASGI2Middleware(self.loaded_app)
|
||||
|
||||
if logger.getEffectiveLevel() <= TRACE_LOG_LEVEL:
|
||||
if self.debug:
|
||||
self.loaded_app = DebugMiddleware(self.loaded_app)
|
||||
if logger.level <= TRACE_LOG_LEVEL:
|
||||
self.loaded_app = MessageLoggerMiddleware(self.loaded_app)
|
||||
if self.proxy_headers:
|
||||
self.loaded_app = ProxyHeadersMiddleware(self.loaded_app, trusted_hosts=self.forwarded_allow_ips)
|
||||
self.loaded_app = ProxyHeadersMiddleware(
|
||||
self.loaded_app, trusted_hosts=self.forwarded_allow_ips
|
||||
)
|
||||
|
||||
self.loaded = True
|
||||
|
||||
def setup_event_loop(self) -> None:
|
||||
raise AttributeError(
|
||||
"The `setup_event_loop` method was replaced by `get_loop_factory` in uvicorn 0.36.0.\n"
|
||||
"None of those methods are supposed to be used directly. If you are doing it, please let me know here: "
|
||||
"https://github.com/Kludex/uvicorn/discussions/2706. Thank you, and sorry for the inconvenience."
|
||||
)
|
||||
def setup_event_loop(self):
|
||||
loop_setup = import_from_string(LOOP_SETUPS[self.loop])
|
||||
if loop_setup is not None:
|
||||
loop_setup()
|
||||
|
||||
def get_loop_factory(self) -> Callable[[], asyncio.AbstractEventLoop] | None:
|
||||
if self.loop in LOOP_FACTORIES:
|
||||
loop_factory: Callable[..., Any] | None = import_from_string(LOOP_FACTORIES[self.loop])
|
||||
else:
|
||||
try:
|
||||
return import_from_string(self.loop)
|
||||
except ImportFromStringError as exc:
|
||||
logger.error("Error loading custom loop setup function. %s" % exc)
|
||||
sys.exit(1)
|
||||
if loop_factory is None:
|
||||
return None
|
||||
return loop_factory(use_subprocess=self.use_subprocess)
|
||||
def bind_socket(self):
|
||||
family = socket.AF_INET
|
||||
addr_format = "%s://%s:%d"
|
||||
|
||||
def bind_socket(self) -> socket.socket:
|
||||
logger_args: list[str | int]
|
||||
if self.uds is not None: # pragma: py-win32
|
||||
path = self.uds
|
||||
sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
|
||||
try:
|
||||
sock.bind(path)
|
||||
uds_perms = 0o666
|
||||
os.chmod(self.uds, uds_perms)
|
||||
except OSError as exc: # pragma: full coverage
|
||||
logger.error(exc)
|
||||
sys.exit(1)
|
||||
if self.host and ":" in self.host:
|
||||
# It's an IPv6 address.
|
||||
family = socket.AF_INET6
|
||||
addr_format = "%s://[%s]:%d"
|
||||
|
||||
message = "Uvicorn running on unix socket %s (Press CTRL+C to quit)"
|
||||
sock_name_format = "%s"
|
||||
color_message = "Uvicorn running on " + click.style(sock_name_format, bold=True) + " (Press CTRL+C to quit)"
|
||||
logger_args = [self.uds]
|
||||
elif self.fd is not None: # pragma: py-win32
|
||||
sock = socket.fromfd(self.fd, socket.AF_UNIX, socket.SOCK_STREAM)
|
||||
message = "Uvicorn running on socket %s (Press CTRL+C to quit)"
|
||||
fd_name_format = "%s"
|
||||
color_message = "Uvicorn running on " + click.style(fd_name_format, bold=True) + " (Press CTRL+C to quit)"
|
||||
logger_args = [sock.getsockname()]
|
||||
else:
|
||||
family = socket.AF_INET
|
||||
addr_format = "%s://%s:%d"
|
||||
|
||||
if self.host and ":" in self.host: # pragma: full coverage
|
||||
# It's an IPv6 address.
|
||||
family = socket.AF_INET6
|
||||
addr_format = "%s://[%s]:%d"
|
||||
|
||||
sock = socket.socket(family=family)
|
||||
sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
|
||||
try:
|
||||
sock.bind((self.host, self.port))
|
||||
except OSError as exc: # pragma: full coverage
|
||||
logger.error(exc)
|
||||
sys.exit(1)
|
||||
|
||||
message = f"Uvicorn running on {addr_format} (Press CTRL+C to quit)"
|
||||
color_message = "Uvicorn running on " + click.style(addr_format, bold=True) + " (Press CTRL+C to quit)"
|
||||
protocol_name = "https" if self.is_ssl else "http"
|
||||
logger_args = [protocol_name, self.host, sock.getsockname()[1]]
|
||||
logger.info(message, *logger_args, extra={"color_message": color_message})
|
||||
sock = socket.socket(family=family)
|
||||
sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
|
||||
try:
|
||||
sock.bind((self.host, self.port))
|
||||
except OSError as exc:
|
||||
logger.error(exc)
|
||||
sys.exit(1)
|
||||
sock.set_inheritable(True)
|
||||
|
||||
message = f"Uvicorn running on {addr_format} (Press CTRL+C to quit)"
|
||||
color_message = (
|
||||
"Uvicorn running on "
|
||||
+ click.style(addr_format, bold=True)
|
||||
+ " (Press CTRL+C to quit)"
|
||||
)
|
||||
protocol_name = "https" if self.is_ssl else "http"
|
||||
logger.info(
|
||||
message,
|
||||
protocol_name,
|
||||
self.host,
|
||||
self.port,
|
||||
extra={"color_message": color_message},
|
||||
)
|
||||
return sock
|
||||
|
||||
@property
|
||||
def should_reload(self) -> bool:
|
||||
return isinstance(self.app, str) and self.reload
|
||||
def should_reload(self):
|
||||
return isinstance(self.app, str) and (self.debug or self.reload)
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue
Block a user