From 46a0a3a7247d99f90c5bf08c17398bf9c37df7b1 Mon Sep 17 00:00:00 2001 From: WSH032 <614337162@qq.com> Date: Wed, 29 Nov 2023 08:27:57 +0800 Subject: [PATCH] docs: update docs - add `CHANGELOG` - add `CONTRIBUTING` - add favicon --- CHANGELOG.md | 32 +++++ CONTRIBUTING.md | 202 ++++++++++++++++++++++++------ README.md | 49 +++++--- docs/CHANGELOG/CHANGELOG.md | 1 + docs/CONTRIBUTING/CONTRIBUTING.md | 1 + docs/Usage/Security.md | 4 +- docs/images/rocket-24.svg | 1 + mkdocs.yml | 8 ++ pyproject.toml | 4 +- scripts/init-dev.sh | 14 --- src/fastapi_proxy_lib/__init__.py | 4 + 11 files changed, 249 insertions(+), 71 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 docs/CHANGELOG/CHANGELOG.md create mode 100644 docs/CONTRIBUTING/CONTRIBUTING.md create mode 100644 docs/images/rocket-24.svg delete mode 100644 scripts/init-dev.sh diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..11d67aa --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,32 @@ + + + + +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)(**After we publish 1.0.0**). + +- `Added` for new features. +- `Changed` for changes in existing functionality. +- `Deprecated` for soon-to-be removed features. +- `Removed` for now removed features. +- `Fixed` for any bug fixes. +- `Security` in case of vulnerabilities. + + + + +## [Unreleased] + +None. + +## [0.0.1b0] - 2023-11-27 [YANKED] + +!!! danger + **This version has security vulnerabilities, please stop using it.** + +[unreleased]: https://github.com/WSH032/fastapi-proxy-lib/compare/v0.0.1b0...HEAD +[0.0.1b0]: https://github.com/WSH032/fastapi-proxy-lib/releases/tag/v0.0.1b0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b4905a0..e646e68 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,55 +1,183 @@ -# Hi 感谢对本项目感兴趣 + + + -## 代码贡献 +# Contributing -> **Note** -> -> 我们最低支持的版本是`python3.8`，你可以随意使用`python3.8`以上的版本。 -> -> 但是请注意，您的代码要能通过`py >= 3.8`的所有版本的代码风格检查与测试。 +> The guide is modified from [mkdocstrings](https://mkdocstrings.github.io/contributing/#contributing) -我们推荐使用[虚拟环境](https://docs.python.org/3/library/venv.html#creating-virtual-environments)来进行开发 +Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given. -在激活虚拟环境后，运行[./scripts/init.sh](./scripts/init-dev.sh)来为你初始化: +## Environment setup -- [requirements](./requirements-dev.txt) -- [hatch](https://github.com/pypa/hatch) -- [pre-commit](https://pre-commit.com/) -- [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) +First, `fork` and `clone` the repository, then `cd` to the directory. -## 代码风格 +We use [`hatch`](https://github.com/pypa/hatch) and [`pre-commit`](https://pre-commit.com/) to manage our project. -由于本项目主要是python语言，所以我们只强制要求python代码风格。 +You can install them with: -但是涉及到其他语言（例如 `bash`, `toml` 等）的部分，也请尽力保证样式正确。 +```shell +# https://pypa.github.io/pipx/ +python3 -m pip install --user pipx -> **Note** -> 我们启用了大量而严格的`lint`规则，如果你使用`vscode`，我们推荐你安装[./.vscode/extensions.json](./.vscode/extensions.json)中的插件来帮助你实时检查错误 -> -> 如果你打不过检查器，可以使用`# noqa`和`# type: ignore`来跳过检查 -> -> 当然，这些规则可能过于严格，你可以发起一个`issue`或者`pull request`来讨论是否需要修改规则 +pipx install hatch +pipx install pre-commit +``` -### python代码风格(请查看[./pyproject.toml](./pyproject.toml)了解我们的风格) +Then, initialize the env with: -- [Ruff](https://github.com/astral-sh/ruff): 代码质量检查 -- [Blcak](https://github.com/psf/black): 代码格式规范 -- [Pyright](https://github.com/Microsoft/pyright/): 静态类型检查 +```shell +# Init pre-commit +# https://pre-commit.com/#3-install-the-git-hook-scripts +pre-commit install +pre-commit run --all-files -您需要通过以上检查，`pre-commit` 会确保这点。 +# https://hatch.pypa.io/latest/environment/ +hatch shell +``` -你也可以[手动检查](./scripts/lint.sh)和[自动修复](./scripts/format.sh)。 +That's all! Now, you can start to develop. -> **Note** -> `Pyright`检查将发生两次 -> -> - 在`pre-commit`中，`Pyright`不会检查第三方依赖，并且`python`版本为支持的最低版本 -> - 而在`Github Actions`或[手动检查](./scripts/lint.sh)中，`Pyright`将在激活的虚拟环境中检查所有依赖 +## Code style -## 代码测试 +The source code is in `src/` -测试文件位于[./tests/](./tests/) +We use [Ruff](https://github.com/astral-sh/ruff), [Blcak](https://github.com/psf/black), [Pyright](https://github.com/Microsoft/pyright/) + and [Codespell](https://github.com/codespell-project/codespell) to check our code style and lint. -我们使用`pytest`来完成测试，测试将在`Github Actions`中进行。 +Please check `pyproject.toml` to know our style. -你也可以[手动测试](./scripts/pytest.sh)。 +If you want to format or lint-fix your code, you can use the following command: + +```shell +hatch run lint +``` + +or, with `pre-commit`: + +```shell +pre-commit run -a +``` + +or, dry run: + +```shell +hatch run lint-check +``` + +!!! tip + If you use `VSCode`, we strongly recommend you to install the extensions in `.vscode/extensions.json`.
+ Because our code style rules are quite strict.
+ These extensions can help you know where need to be fixed when coding. + +## Testing + +We use [pytest](https://docs.pytest.org/en/stable/) to test our code. + +The test source code is in `tests/` + +You can run the testing with: + +```shell +hatch run test +``` + +## Documentation + +We use [mkdocs](https://www.mkdocs.org), [mkdocs-material](https://squidfunk.github.io/mkdocs-material), [mkdocstrings](https://mkdocstrings.github.io) to build our documentation. + +The documentation source code is in `docs/`, `mkdocs.yml`, + may be there is also some source code in `scripts/` or somewhere (check `mkdocs.yml` to find that). + +Live-reloading docs: + +```shell +hatch run docs:mkdocs serve +``` + +Build docs: + +```shell +hatch run docs:docs-build +``` + +## PR + +- PRs should target the `main` branch. +- Keep branches up to date by `rebase` before merging. +- Do not add multiple unrelated things in same PR. +- Do not submit PRs where you just take existing lines and reformat them without changing what they do. +- Do not change other parts of the code that are not yours for formatting reasons. +- Do not use your clone's main branch to make a PR - create a branch and PR that. + +### Edit `CHANGELOG.md` + +If you have made the corresponding changes, please record them in `CHANGELOG.md`. + +### Commit message convention + +Commit messages must follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), +or, `pre-commit` may be reject your commit. + +!!! info + If you don't know how to finish these, it's okay, feel free to initiate a PR, I will help you continue. + +## More + +There may still be some useful commands in `pyproject.toml`, you can refer to [hatch/environment/scripts](https://hatch.pypa.io/latest/config/environment/overview/#scripts) to use them. + +!!! info + If you find that the commands given in the above examples are incorrect, please open an issue, we greatly appreciate it. + +--- + +## 😢 + +!!! warning + The following 👇 content is for the maintainers of this project, may be you don't need to read it. + +--- + +## deploy-docs + +please refer to `.github/workflows/docs.yml` + +## CI: lint-test + +please refer to `.github/workflows/lint-test.yml` + +## CI: pre-commit-ci auto-update + +Every Monday, `pre-commit-ci` will send a PR for automatic hook version updates, which will trigger a local `ver_sync` hook. + +The `ver_sync` hook will maintain lint tools version consistency between `.pre-commit-config.yaml` and `pyproject.toml`. + +Please check whether the `ver_sync` works properly, then you can accept the PR. + +## Publish and Release 🚀 + +**^^First, edit `CHANGELOG.md` to record the changes.^^** + +Then, please refer to: + +- `.github/workflows/publish.yml` +- +- + +Update version with: + +```shell +hatch version {new_version} +``` + +It will create a commit and tag automatically, then, push the **tag** to GitHub. + +After that, the `publish.yml` workflow will build and publish the package to PyPI. + +> Don't forget to make a `approve` in environment `pypi` for the workflow. + +Finally, edit the `draft release` created by `publish.yml` workflow, and publish the release. + +!!! warning + The creating of tag needs signature verification,
+ please refer to diff --git a/README.md b/README.md index 8f718df..d0dee23 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,19 @@ + + + + # FastAPI Proxy Lib

HTTP/WebSocket proxy for starlette/FastAPI

-| | | -| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| CI/CD | [![CI: lint-test]][CI: lint-test#link] [![CI: docs]][CI: docs#link] | +| | | +| - | - | +| CI/CD | [![CI: lint-test]][CI: lint-test#link] [![pre-commit.ci status]][pre-commit.ci status#link]
[![CI: docs]][CI: docs#link] [![CI: publish]][CI: publish#link] | | Code | [![codecov]][codecov#link] [![Code style: black]][Code style: black#link] [![Ruff]][Ruff#link] [![Checked with pyright]][Checked with pyright#link] | -| Package | [![Python-Version]][Python-Version#link] | -| Meta | [![Hatch project]][Hatch project#link] [![GitHub License]][GitHub License#link] | +| Package | [![PyPI - Version]][PyPI#link] [![PyPI - Downloads]][PyPI#link] [![PyPI - Python Version]][PyPI#link] | +| Meta | [![Hatch project]][Hatch project#link] [![GitHub License]][GitHub License#link] | --- @@ -48,13 +52,12 @@ So, it perfectly supports all features of [httpx.AsyncClient](https://www.python > !!! note > > We follow semantic versioning.
-> This is a young project, and before 1.0.0, there may be changes in the API (though we try to avoid that).
-> We recommend pinning to any minor versions, such as 0.1.x. - -Pypi will come soon, please install from github temporarily: +> This is a young project, and before 1.0.0, there may be changes in the API (we try to avoid that).
+> We will release security updates at any time, please try to keep the version updated, instead of pinning to the old version.
+> pin to `major version` is recommended. ```shell -pip install fastapi-proxy-lib[standard]@git+https://github.com/WSH032/fastapi-proxy-lib.git +pip install fastapi-proxy-lib ``` Perhaps you've noticed that we're installing `fastapi-proxy-lib[standard]` instead of `fastapi-proxy-lib`. The difference is: @@ -82,18 +85,22 @@ uvicorn main:app --host 127.0.0.1 --port 8000 Then, visit `http://127.0.0.1:8000/bar?baz=1`, you will get the response from `http://www.example.com/foo/bar?baz=1`. -For support with `FastAPI router` or only using `Starlette`, please **visit to our [documentation 📚](https://wsh032.github.io/fastapi-proxy-lib/) for more details**. +**[Continue, please visit to our documentation 📚 for more details](https://wsh032.github.io/fastapi-proxy-lib/)**: + +- support for `FastAPI router` +- only `Starlette` dependency +- `WebSocket` proxy ## development - If you find any issues, please don't hesitate to [open an issue](https://github.com/WSH032/fastapi-proxy-lib/issues). - If you need assistance, feel free to [start a discussion](https://github.com/WSH032/fastapi-proxy-lib/discussions). -- [Welcome PR](https://github.com/WSH032/fastapi-proxy-lib/pulls) +- Follow our `CONTRIBUTING.md`, [PR Welcome!](https://github.com/WSH032/fastapi-proxy-lib/pulls) +- Security 😰❗: We value any security vulnerabilities, [please report to us privately](https://github.com/WSH032/fastapi-proxy-lib/security), pretty appreciated for that. English is not the native language of the author (me), so if you find any areas for improvement in the documentation, your feedback is welcome. -If you think this project helpful, consider giving it a star ![GitHub Repo stars](https://img.shields.io/github/stars/wsh032/fastapi-proxy-lib?style=social) - , which makes me happy. :smile: +If you think this project helpful, consider giving it a star ![GitHub Repo stars](https://img.shields.io/github/stars/wsh032/fastapi-proxy-lib?style=social), which makes me happy. :smile: ## License @@ -101,12 +108,16 @@ This project is licensed under the terms of the *Apache License 2.0*. + [CI: lint-test]: https://github.com/WSH032/fastapi-proxy-lib/actions/workflows/lint-test.yml/badge.svg?branch=main [CI: lint-test#link]: https://github.com/WSH032/fastapi-proxy-lib/actions/workflows/lint-test.yml [CI: docs]: https://github.com/WSH032/fastapi-proxy-lib/actions/workflows/docs.yml/badge.svg?branch=main [CI: docs#link]: https://github.com/WSH032/fastapi-proxy-lib/actions/workflows/docs.yml -[Python-Version]: https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2FWSH032%2Ffastapi-proxy%2Fmain%2Fpyproject.toml&logo=python&logoColor=gold&label=Python -[Python-Version#link]: https://github.com/WSH032/fastapi-proxy-lib/blob/main/pyproject.toml +[CI: publish]: https://github.com/WSH032/fastapi-proxy-lib/actions/workflows/publish.yml/badge.svg?branch=main +[CI: publish#link]: https://github.com/WSH032/fastapi-proxy-lib/actions/workflows/publish.yml +[pre-commit.ci status]: https://results.pre-commit.ci/badge/github/WSH032/fastapi-proxy-lib/main.svg +[pre-commit.ci status#link]: https://results.pre-commit.ci/latest/github/WSH032/fastapi-proxy-lib/main + [Code style: black]: https://img.shields.io/badge/code%20style-black-000000.svg [Code style: black#link]: https://github.com/psf/black [GitHub License]: https://img.shields.io/github/license/WSH032/fastapi-proxy-lib?color=9400d3 @@ -115,6 +126,12 @@ This project is licensed under the terms of the *Apache License 2.0*. [Ruff#link]: https://github.com/astral-sh/ruff [Checked with pyright]: https://microsoft.github.io/pyright/img/pyright_badge.svg [Checked with pyright#link]: https://microsoft.github.io/pyright + +[PyPI - Version]: https://img.shields.io/pypi/v/fastapi-proxy-lib?logo=pypi&label=PyPI&logoColor=gold +[PyPI - Downloads]: https://img.shields.io/pypi/dm/fastapi-proxy-lib?color=blue&label=Downloads&logo=pypi&logoColor=gold +[PyPI - Python Version]: https://img.shields.io/pypi/pyversions/fastapi-proxy-lib?logo=python&label=Python&logoColor=gold +[PyPI#link]: https://pypi.org/project/fastapi-proxy-lib + [Hatch project]: https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg [Hatch project#link]: https://github.com/pypa/hatch [codecov]: https://codecov.io/gh/WSH032/fastapi-proxy-lib/graph/badge.svg?token=62QQU06E8X diff --git a/docs/CHANGELOG/CHANGELOG.md b/docs/CHANGELOG/CHANGELOG.md new file mode 100644 index 0000000..786b75d --- /dev/null +++ b/docs/CHANGELOG/CHANGELOG.md @@ -0,0 +1 @@ +--8<-- "CHANGELOG.md" diff --git a/docs/CONTRIBUTING/CONTRIBUTING.md b/docs/CONTRIBUTING/CONTRIBUTING.md new file mode 100644 index 0000000..ea38c9b --- /dev/null +++ b/docs/CONTRIBUTING/CONTRIBUTING.md @@ -0,0 +1 @@ +--8<-- "CONTRIBUTING.md" diff --git a/docs/Usage/Security.md b/docs/Usage/Security.md index b31fb82..6c3376f 100644 --- a/docs/Usage/Security.md +++ b/docs/Usage/Security.md @@ -14,12 +14,12 @@ If you do not explicitly specify it, `ForwardHttpProxy` will issue a warning and - If you want to accept all proxy requests (**never do this on a public server**), you can do it like this: ```python - proxy_filter = lambda _: None + proxy_filter = lambda *_: None ``` - If you want to implement your own proxy filter, please refer to the [fastapi_proxy_lib.core.tool.ProxyFilterProto][]. -## `http` vs `https` +## `http`/`ws` vs `https`/`wss` !!! danger **Never use a server with the HTTPS protocol to proxy a target server (`base_url`) with the HTTP protocol !** diff --git a/docs/images/rocket-24.svg b/docs/images/rocket-24.svg new file mode 100644 index 0000000..8660bbf --- /dev/null +++ b/docs/images/rocket-24.svg @@ -0,0 +1 @@ + diff --git a/mkdocs.yml b/mkdocs.yml index 29fc1cb..3411c78 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,6 +10,9 @@ edit_uri: edit/main/docs/ theme: name: material + icon: + logo: octicons/rocket-24 + favicon: images/rocket-24.svg features: - content.code.copy - content.code.annotate @@ -126,6 +129,7 @@ watch: - src/fastapi_proxy_lib - README.md - CONTRIBUTING.md + - CHANGELOG.md validation: omitted_files: warn @@ -142,3 +146,7 @@ nav: - Usage/Advanced-and-Starlette.md - Usage/Security.md - API Reference: reference/ + - CONTRIBUTING: + - CONTRIBUTING/CONTRIBUTING.md + - CHANGELOG: + - CHANGELOG/CHANGELOG.md diff --git a/pyproject.toml b/pyproject.toml index 4e11f07..d81819b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -63,8 +63,8 @@ source = "regex_commit" commit_extra_args = ["-e"] path = "src/fastapi_proxy_lib/__init__.py" # NOTE: `chore` is required by commitlint -commit_message = "chore(version): 🚀 bump version {current_version} → {new_version}" -tag_message = "🚀 bump version {current_version} → {new_version}" +commit_message = "chore(version): 🚀 bump version v{current_version} → v{new_version}" +tag_message = "🚀 bump version v{current_version} → v{new_version}" # NOTE: `v` prefix is required by github `publish.yml` action tag_name = "v{new_version}" diff --git a/scripts/init-dev.sh b/scripts/init-dev.sh deleted file mode 100644 index 4cfae8b..0000000 --- a/scripts/init-dev.sh +++ /dev/null @@ -1,14 +0,0 @@ -#!/bin/bash - -cd "$(dirname ${0})/.." - -pipx install pre-commit -pipx install hatch - -# Init pre-commit -# https://pre-commit.com/#3-install-the-git-hook-scripts -pre-commit install -pre-commit run --all-files - -# https://hatch.pypa.io/latest/environment/ -hatch shell diff --git a/src/fastapi_proxy_lib/__init__.py b/src/fastapi_proxy_lib/__init__.py index 1caa8ae..de07d3e 100644 --- a/src/fastapi_proxy_lib/__init__.py +++ b/src/fastapi_proxy_lib/__init__.py @@ -1,3 +1,7 @@ """fastapi_proxy_lib package.""" + +# DO NOT EDIT THE `__version__` MANUALLY. +# Use `hatch version {new_version}` instead. +# Refer to `CONTRIBUTING.md` for more info. __version__ = "0.0.1b0"