Repository: rafsaf/minimal-fastapi-postgres-template Branch: main Commit: 9048b6d3f2c9 Files: 50 Total size: 85.2 KB Directory structure: gitextract_d8hu4kk5/ ├── .github/ │ ├── dependabot.yml │ └── workflows/ │ ├── dev_build.yml │ ├── tests.yml │ └── type_check.yml ├── .gitignore ├── .pre-commit-config.yaml ├── Dockerfile ├── LICENSE ├── Makefile ├── README.md ├── alembic/ │ ├── README │ ├── env.py │ ├── script.py.mako │ └── versions/ │ └── 20260203_1616_initial_auth_683275eeb305.py ├── alembic.ini ├── app/ │ ├── __init__.py │ ├── auth/ │ │ ├── api_messages.py │ │ ├── dependencies.py │ │ ├── jwt.py │ │ ├── models.py │ │ ├── password.py │ │ ├── responses.py │ │ ├── schemas.py │ │ ├── tests/ │ │ │ ├── __init__.py │ │ │ ├── test_jwt.py │ │ │ ├── test_password.py │ │ │ ├── test_view_delete_current_user.py │ │ │ ├── test_view_login_access_token.py │ │ │ ├── test_view_read_current_user.py │ │ │ ├── test_view_refresh_token.py │ │ │ ├── test_view_register_new_user.py │ │ │ └── test_view_reset_current_user_password.py │ │ └── views.py │ ├── conftest.py │ ├── core/ │ │ ├── __init__.py │ │ ├── config.py │ │ ├── database_session.py │ │ ├── lifespan.py │ │ ├── metrics.py │ │ └── models.py │ ├── main.py │ ├── probe/ │ │ ├── __init__.py │ │ ├── tests/ │ │ │ ├── __init__.py │ │ │ └── test_views.py │ │ └── views.py │ └── tests/ │ ├── auth.py │ └── factories.py ├── docker-compose.yml ├── init.sh └── pyproject.toml ================================================ FILE CONTENTS ================================================ ================================================ FILE: .github/dependabot.yml ================================================ version: 2 updates: - package-ecosystem: uv directory: / schedule: interval: monthly open-pull-requests-limit: 1 allow: - dependency-type: "all" groups: all-dependencies: patterns: - "*" - package-ecosystem: github-actions directory: / schedule: interval: monthly - package-ecosystem: docker directory: / schedule: interval: monthly ================================================ FILE: .github/workflows/dev_build.yml ================================================ name: dev-build on: workflow_run: workflows: ["tests"] branches: [main] types: - completed workflow_dispatch: inputs: tag: description: "Docker image tag" required: true default: "latest" env: IMAGE_TAG: ${{ github.event.inputs.tag || 'latest' }} jobs: dev_build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - name: Login to DockerHub uses: docker/login-action@v3 with: username: ${{ secrets.DOCKER_USER }} password: ${{ secrets.DOCKER_PASS }} - name: Build and push image uses: docker/build-push-action@v6 with: file: Dockerfile push: true tags: rafsaf/minimal-fastapi-postgres-template:${{ env.IMAGE_TAG }} ================================================ FILE: .github/workflows/tests.yml ================================================ name: tests on: push: branches: - "**" tags-ignore: - "*.*" jobs: tests: runs-on: ubuntu-latest services: postgres: image: postgres:18 env: POSTGRES_PASSWORD: postgres options: >- --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5 ports: - 5432:5432 steps: - uses: actions/checkout@v6 - name: "Set up Python" uses: actions/setup-python@v6 with: python-version-file: "pyproject.toml" - name: Install uv uses: astral-sh/setup-uv@v7 with: version: "0.9.2" enable-cache: true - name: Install the project run: uv sync --locked --all-extras --dev shell: bash - name: Run tests env: SECURITY__JWT_SECRET_KEY: very-not-secret DATABASE__HOSTNAME: localhost DATABASE__PASSWORD: postgres run: | uv run pytest ================================================ FILE: .github/workflows/type_check.yml ================================================ name: type-check on: push: branches: - "**" tags-ignore: - "*.*" jobs: type_check: strategy: matrix: check: ["ruff check", "mypy --check", "ruff format --check"] runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - name: "Set up Python" uses: actions/setup-python@v6 with: python-version-file: "pyproject.toml" - name: Install uv uses: astral-sh/setup-uv@v7 with: version: "0.9.2" enable-cache: true - name: Install the project run: uv sync --locked --all-extras --dev shell: bash - name: Run ${{ matrix.check }} run: | uv run ${{ matrix.check }} . ================================================ FILE: .gitignore ================================================ # Byte-compiled / optimized / DLL files __pycache__/ *.py[cod] *$py.class .env # C extensions *.so # Distribution / packaging .Python build/ develop-eggs/ dist/ downloads/ eggs/ .eggs/ lib/ lib64/ parts/ sdist/ var/ wheels/ pip-wheel-metadata/ share/python-wheels/ *.egg-info/ .installed.cfg *.egg MANIFEST # PyInstaller # Usually these files are written by a python script from a template # before PyInstaller builds the exe, so as to inject date/other infos into it. *.manifest *.spec # Installer logs pip-log.txt pip-delete-this-directory.txt # Unit test / coverage reports htmlcov/ .tox/ .nox/ .coverage .coverage.* .cache nosetests.xml coverage.xml *.cover *.py,cover .hypothesis/ .pytest_cache/ log.txt # Translations *.mo *.pot # Django stuff: *.log local_settings.py db.sqlite3 db.sqlite3-journal # Flask stuff: instance/ .webassets-cache # Scrapy stuff: .scrapy # Sphinx documentation docs/_build/ # PyBuilder target/ # Jupyter Notebook .ipynb_checkpoints # IPython profile_default/ ipython_config.py # pyenv .python-version # pipenv # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. # However, in case of collaboration, if having platform-specific dependencies or dependencies # having no cross-platform support, pipenv may install dependencies that don't work, or not # install all needed dependencies. #Pipfile.lock # PEP 582; used by e.g. github.com/David-OConnor/pyflow __pypackages__/ # Celery stuff celerybeat-schedule celerybeat.pid # SageMath parsed files *.sage.py # Environments .venv env/ venv/ ENV/ env.bak/ venv.bak/ # Spyder project settings .spyderproject .spyproject # Rope project settings .ropeproject # mkdocs documentation /site # mypy .mypy_cache/ .dmypy.json dmypy.json # ruff .ruff_cache # Pyre type checker .pyre/ ================================================ FILE: .pre-commit-config.yaml ================================================ repos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: v6.0.0 hooks: - id: check-yaml - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.15.0 hooks: - id: ruff-format - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.15.0 hooks: - id: ruff-check args: [--fix] ================================================ FILE: Dockerfile ================================================ FROM python:3.14-slim-trixie AS base ENV PYTHONUNBUFFERED=1 WORKDIR /build # Create requirements.txt file FROM base AS uv COPY --from=ghcr.io/astral-sh/uv:0.9.2 /uv /uvx /bin/ COPY uv.lock pyproject.toml ./ RUN uv export --no-dev --no-hashes -o /requirements.txt --no-install-workspace --frozen RUN uv export --only-group dev --no-hashes -o /requirements-dev.txt --no-install-workspace --frozen FROM base AS final COPY --from=uv /requirements.txt . # Create venv, add it to path and install requirements RUN python -m venv /venv ENV PATH="/venv/bin:$PATH" RUN pip install -r requirements.txt # Install uvicorn server RUN pip install uvicorn[standard] # Copy the rest of app COPY app app COPY alembic alembic COPY alembic.ini . COPY pyproject.toml . COPY init.sh . # Expose port 8000 for app and optional 9090 for prometheus metrics EXPOSE 8000 EXPOSE 9090 # Make the init script executable RUN chmod +x ./init.sh # Set ENTRYPOINT to always run init.sh ENTRYPOINT ["./init.sh"] # Set CMD to uvicorn # /venv/bin/uvicorn is used because from entrypoint script PATH is new CMD ["/venv/bin/uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "1", "--loop", "uvloop"] ================================================ FILE: LICENSE ================================================ MIT License Copyright (c) 2021 rafsaf Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ================================================ FILE: Makefile ================================================ BIND_PORT ?= 8000 BIND_HOST ?= localhost .PHONY: help help: ## Print this help message grep -E '^[\.a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}' .env: ## Ensure there is env file or create one echo "No .env file found. Want to create it from .env.example? [y/n]" && read answer && if [ $${answer:-'N'} = 'y' ]; then cp .env.example .env;fi .PHONY: local-setup local-setup: ## Setup local postgres database docker compose up -d .PHONY: up up: local-setup ## Run FastAPI development server uv run alembic upgrade head uv run uvicorn app.main:app --reload --host $(BIND_HOST) --port $(BIND_PORT) .PHONY: run run: up ## Alias for `up` .PHONY: down down: ## Stop database docker compose down .PHONY: test test: local-setup ## Run unit tests uv run pytest . .PHONY: lint lint: local-setup ## Run all linters uv run pre-commit run -a uv run mypy . ================================================ FILE: README.md ================================================ # Minimal FastAPI PostgreSQL template [![Live example](https://img.shields.io/badge/live%20example-https%3A%2F%2Fminimal--fastapi--postgres--template.rafsaf.pl-blueviolet)](https://minimal-fastapi-postgres-template.rafsaf.pl/) [![License](https://img.shields.io/github/license/rafsaf/minimal-fastapi-postgres-template)](https://github.com/rafsaf/minimal-fastapi-postgres-template/blob/main/LICENSE) [![Python 3.14](https://img.shields.io/badge/python-3.14-blue)](https://docs.python.org/3/whatsnew/3.14.html) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![Tests](https://github.com/rafsaf/minimal-fastapi-postgres-template/actions/workflows/tests.yml/badge.svg)](https://github.com/rafsaf/minimal-fastapi-postgres-template/actions/workflows/tests.yml) _Check out online example: [https://minimal-fastapi-postgres-template.rafsaf.pl](https://minimal-fastapi-postgres-template.rafsaf.pl), it's 100% code used in template (docker image) with added my domain and https only._ - [Minimal FastAPI PostgreSQL template](#minimal-fastapi-postgresql-template) - [About](#about) - [Features](#features) - [Quickstart](#quickstart) - [1. Create repository from a template](#1-create-repository-from-a-template) - [2. Install dependencies with uv](#2-install-dependencies-with-uv) - [3. Run app](#3-run-app) - [4. Activate pre-commit](#4-activate-pre-commit) - [5. Running tests](#5-running-tests) - [Step by step example - POST and GET endpoints](#step-by-step-example---post-and-get-endpoints) - [1. Create new app](#1-create-new-app) - [2. Create SQLAlchemy model](#2-create-sqlalchemy-model) - [3. Import new models.py file in alembic env.py](#3-import-new-modelspy-file-in-alembic-envpy) - [4. Create and apply alembic migration](#4-create-and-apply-alembic-migration) - [5. Create request and response schemas](#5-create-request-and-response-schemas) - [6. Create endpoints](#6-create-endpoints) - [7. Add Pet model to tests factories](#7-add-pet-model-to-tests-factories) - [8. Create new test file](#8-create-new-test-file) - [9. Write tests](#9-write-tests) - [Design choices](#design-choices) - [Dockerfile](#dockerfile) - [Registration](#registration) - [Delete user endpoint](#delete-user-endpoint) - [JWT and refresh tokens](#jwt-and-refresh-tokens) - [Writing scripts / cron](#writing-scripts--cron) - [Docs URL](#docs-url) - [CORS](#cors) - [Allowed Hosts](#allowed-hosts) - [License](#license) ## About If you are curious about latest changes and rationale, read 2026 update blog post: [Update of minimal-fastapi-postgres-template to version 7.0.0](https://rafsaf.pl/blog/2026/02/07/update-of-minimal-fastapi-postgres-template-to-version-7.0.0/). Enjoy! ## Features - [x] Template repository. - [x] [SQLAlchemy](https://github.com/sqlalchemy/sqlalchemy) 2.0, async queries, best possible autocompletion support. - [x] PostgreSQL 18 database under [asyncpg](https://github.com/MagicStack/asyncpg) interface. - [x] Full [Alembic](https://github.com/alembic/alembic) migrations setup (also in unit tests). - [x] Secure and tested setup for [PyJWT](https://github.com/jpadilla/pyjwt) and [bcrypt](https://github.com/pyca/bcrypt). - [x] Ready to go Dockerfile with [uvicorn](https://www.uvicorn.org/) webserver. - [x] [uv](https://docs.astral.sh/uv/getting-started/installation/), [mypy](https://github.com/python/mypy), [pre-commit](https://github.com/pre-commit/pre-commit) hooks with [ruff](https://github.com/astral-sh/ruff). - [x] Perfect pytest asynchronous test setup and full coverage. ![template-fastapi-minimal-openapi-example](https://rafsaf.pl/blog/2026/02/07/update-of-minimal-fastapi-postgres-template-to-version-7.0.0/minimal-fastapi-postgres-template-2026-02-07-version-7.0.0.png) ## Quickstart ### 1. Create repository from a template See [docs](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template) or just use git clone. ### 2. Install dependencies with [uv](https://docs.astral.sh/uv/getting-started/installation/) ```bash cd your_project_name uv sync ``` Uv should automatically install Python version currently required by template (>=3.14) or use existing Python installation if you already have it. ### 3. Run app ```bash make up ``` Refer to `Makefile` to see shortcut (`apt install build-essential` - on linux) If you want to work without it, this should do: ```bash docker compose up -d alembic upgrade head uvicorn app.main:app --reload ``` You should then use `git init` (if needed) to initialize git repository and access OpenAPI spec at [http://localhost:8000/](http://localhost:8000/) by default. See last section for customizations. ### 4. Activate pre-commit [pre-commit](https://pre-commit.com/) is de facto standard now for pre push activities like isort or black or its nowadays replacement ruff. Refer to `.pre-commit-config.yaml` file to see my current opinionated choices. ```bash # Shortcut make lint ``` Full commands ```bash # Install pre-commit pre-commit install --install-hooks # Run on all files pre-commit run --all-files ``` ### 5. Running tests Note, it will create databases for session and run tests in many processes by default (using pytest-xdist) to speed up execution, based on how many CPU are available in environment. For more details about initial database setup, see logic `app/conftest.py` file, especially `fixture_setup_new_test_database` function. Pytest configuration is also in `[tool.pytest.ini_options]` in `pyproject.toml`. Moreover, there is coverage pytest plugin with required code coverage level 100%. ```bash # see all pytest configuration flags in pyproject.toml pytest # or make test ``` ## Step by step example - POST and GET endpoints I always enjoy to have some kind of an example in templates (even if I don't like it much, _some_ parts may be useful and save my time...), so let's create two example endpoints: - `POST` endpoint `/pets/create` for creating `Pets` with relation to currently logged `User` - `GET` endpoint `/pets/me` for fetching all user's pets. ### 1. Create new app Add `app/pets` folder and `app/pets/__init__.py`. ### 2. Create SQLAlchemy model We will add `Pet` model to `app/pets/models.py`. ```python # app/pets/models.py import sqlalchemy as sa from sqlalchemy.orm import Mapped, mapped_column from app.core.models import Base class Pet(Base): __tablename__ = "pets_pet" id: Mapped[int] = mapped_column(sa.BigInteger, primary_key=True) user_id: Mapped[str] = mapped_column( sa.ForeignKey("auth_user.user_id", ondelete="CASCADE"), ) pet_name: Mapped[str] = mapped_column(sa.String(50), nullable=False) ``` Note, we are using super powerful SQLAlchemy feature here - `Mapped` and `mapped_column` were first introduced in SQLAlchemy 2.0, if this syntax is new for you, read carefully [what's new](https://docs.sqlalchemy.org/en/20/changelog/whatsnew_20.html) part of documentation. ### 3. Import new models.py file in alembic env.py Without this step, alembic won't be able to follow changes in new `models.py` file. In `alembic/env.py` import new file ```python # alembic/env.py (...) # import other models here import app.pets.models # noqa (...) ``` ### 4. Create and apply alembic migration ```bash ### Use below commands in root folder in virtualenv ### # if you see FAILED: Target database is not up to date. # first use alembic upgrade head # Create migration with alembic revision alembic revision --autogenerate -m "create_pet_model" # File similar to "2022050949_create_pet_model_44b7b689ea5f.py" should appear in `/alembic/versions` folder # Apply migration using alembic upgrade alembic upgrade head # (...) # INFO [alembic.runtime.migration] Running upgrade d1252175c146 -> 44b7b689ea5f, create_pet_model ``` PS. Note, alembic is configured in a way that it work with async setup and also detects specific column changes if using `--autogenerate` flag. ### 5. Create request and response schemas ```python # app/pets/schemas.py from pydantic import BaseModel, ConfigDict class PetCreateRequest(BaseModel): pet_name: str class PetResponse(BaseModel): id: int pet_name: str user_id: str model_config = ConfigDict(from_attributes=True) ``` ### 6. Create endpoints ```python # app/pets/views.py from fastapi import APIRouter, Depends, status from sqlalchemy import select from sqlalchemy.ext.asyncio import AsyncSession from app.auth.dependencies import get_current_user from app.auth.models import User from app.core import database_session from app.pets.models import Pet from app.pets.schemas import PetCreateRequest, PetResponse router = APIRouter() @router.post( "/create", response_model=PetResponse, status_code=status.HTTP_201_CREATED, description="Creates new pet. Only for logged users.", ) async def create_new_pet( data: PetCreateRequest, session: AsyncSession = Depends(database_session.new_async_session), current_user: User = Depends(get_current_user), ) -> Pet: new_pet = Pet(user_id=current_user.user_id, pet_name=data.pet_name) session.add(new_pet) await session.commit() return new_pet @router.get( "/me", response_model=list[PetResponse], status_code=status.HTTP_200_OK, description="Get list of pets for currently logged user.", ) async def get_all_my_pets( session: AsyncSession = Depends(database_session.new_async_session), current_user: User = Depends(get_current_user), ) -> list[Pet]: pets = await session.scalars( select(Pet).where(Pet.user_id == current_user.user_id).order_by(Pet.pet_name) ) return list(pets.all()) ``` Now we need to add newly created router to `main.py` app. ```python # main.py (...) from app.pets.views import router as pets_router (...) app.include_router(pets_router, prefix="/pets", tags=["pets"]) ``` ### 7. Add Pet model to tests factories File `app/tests/factories.py` contains `User` model factory already. Every new DB model should also have it, as it really simplify things later (when you have more models and relationships). ```python # app/tests/factories.py (...) from app.pets.models import Pet (...) class PetFactory(SQLAlchemyFactory[Pet]): pet_name = Use(Faker().first_name) ``` ### 8. Create new test file Create folder `app/pet/tests` and inside files `__init__.py` and eg. `test_pets_views.py`. ### 9. Write tests We will write two really simple tests into new file `test_pets_views.py` ```python # app/pet/tests/test_pets_views.py from fastapi import status from httpx import AsyncClient from app.auth.models import User from app.main import app from app.tests.factories import PetFactory async def test_create_new_pet( client: AsyncClient, default_user_headers: dict[str, str], default_user: User ) -> None: response = await client.post( app.url_path_for("create_new_pet"), headers=default_user_headers, json={"pet_name": "Tadeusz"}, ) assert response.status_code == status.HTTP_201_CREATED result = response.json() assert result["user_id"] == default_user.user_id assert result["pet_name"] == "Tadeusz" async def test_get_all_my_pets( client: AsyncClient, default_user_headers: dict[str, str], default_user: User, ) -> None: pet1 = await PetFactory.create_async( user_id=default_user.user_id, pet_name="Alfred" ) pet2 = await PetFactory.create_async( user_id=default_user.user_id, pet_name="Tadeusz" ) response = await client.get( app.url_path_for("get_all_my_pets"), headers=default_user_headers, ) assert response.status_code == status.HTTP_200_OK assert response.json() == [ { "user_id": pet1.user_id, "pet_name": pet1.pet_name, "id": pet1.id, }, { "user_id": pet2.user_id, "pet_name": pet2.pet_name, "id": pet2.id, }, ] ``` ## Design choices There are couple decisions to make and changes that can/should be done after fork. I try to describe below things I consider most opinionated. ### Dockerfile This template has by default included `Dockerfile` with [Uvicorn](https://www.uvicorn.org/) webserver, because it's simple in direct relation to FastAPI and great ease of configuration. You should be able to run container(s) (over :8000 port) and then need to setup the proxy, loadbalancer, with https enbaled, so the app stays behind it. Ye, **it's safe**(as much as anything is safe), you don't need anything except prefered LB. Other webservers to consider: [Nginx Unit](https://unit.nginx.org/), [Daphne](https://github.com/django/daphne), [Hypercorn](https://pgjones.gitlab.io/hypercorn/index.html). ### Registration Is open. You would probably want to either remove it altogether or change. ### Delete user endpoint Rethink `delete_current_user`, maybe you don't need it. ### JWT and refresh tokens By using `/auth/access-token` user can exchange username + password for JWT. Refresh tokens is saved **in database table**. I've seen a lot of other, not always secure or sane setups. It's up to you if you want to change it to be also JWT (which seems to be popular), just one small note: It's `good` design if one can revoke all or preferably some refresh tokens. It's much `worse` design if one cannot. On the other hand, it's fine not to have option to revoke access tokens (as they are shortlived). ### Writing scripts / cron Very rarely app has not some kind of background tasks. Feel free to use `new_script_async_session` if you need to have access to database outside of FastAPI. Cron can be simply: new file, async task with session (doing something), wrapped by `asyncio.run(script_func())`. ### Docs URL Docs page is simply `/` (by default in FastAPI it is `/docs`). You can change it completely for the project, just as title, version, etc. ```python app = FastAPI( title="minimal fastapi postgres template", version="7.0.0", description="https://github.com/rafsaf/minimal-fastapi-postgres-template", openapi_url="/openapi.json", docs_url="/", ) ``` ### CORS If you are not sure what are CORS for, follow [developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS). Most frontend frameworks nowadays operate on `http://localhost:3000` thats why it's included in `BACKEND_CORS_ORIGINS` in `.env` file, before going production be sure to include your frontend domain there, like `https://my-frontend-app.example.com`. ```python app.add_middleware( CORSMiddleware, allow_origins=[str(origin) for origin in config.settings.BACKEND_CORS_ORIGINS], allow_credentials=True, allow_methods=["*"], allow_headers=["*"], ) ``` ### Allowed Hosts This middleware prevents HTTP Host Headers attack, you should put here your server IP or (preferably) full domain under which it's accessible like `example.com`. By default `"localhost", "127.0.0.1", "0.0.0.0"` ```python app.add_middleware(TrustedHostMiddleware, allowed_hosts=config.settings.ALLOWED_HOSTS) ``` ## License The code is under MIT License. It's here for educational purposes, created mainly to have a place where up-to-date Python and FastAPI software lives. Do whatever you want with this code. ================================================ FILE: alembic/README ================================================ Generic single-database configuration. ================================================ FILE: alembic/env.py ================================================ import asyncio from logging.config import fileConfig from sqlalchemy import Connection, engine_from_config, pool from sqlalchemy.ext.asyncio import AsyncEngine from alembic import context from app.core.config import get_settings # this is the Alembic Config object, which provides # access to the values within the .ini file in use. config = context.config # Interpret the config file for Python logging. # This line sets up loggers basically. fileConfig(config.config_file_name) # type: ignore # add your model's MetaData object here # for 'autogenerate' support # from myapp import mymodel # target_metadata = mymodel.Base.metadata from app.core.models import Base # noqa target_metadata = Base.metadata # import other models here import app.auth.models # noqa def get_database_uri() -> str: return get_settings().sqlalchemy_database_uri.render_as_string(hide_password=False) def run_migrations_offline() -> None: """Run migrations in 'offline' mode. This configures the context with just a URL and not an Engine, though an Engine is acceptable here as well. By skipping the Engine creation we don't even need a DBAPI to be available. Calls to context.execute() here emit the given string to the script output. """ url = get_database_uri() context.configure( url=url, target_metadata=target_metadata, literal_binds=True, dialect_opts={"paramstyle": "named"}, compare_type=True, compare_server_default=True, ) with context.begin_transaction(): context.run_migrations() def do_run_migrations(connection: Connection | None) -> None: context.configure( connection=connection, target_metadata=target_metadata, compare_type=True ) with context.begin_transaction(): context.run_migrations() async def run_migrations_online() -> None: """Run migrations in 'online' mode. In this scenario we need to create an Engine and associate a connection with the context. """ configuration = config.get_section(config.config_ini_section) assert configuration configuration["sqlalchemy.url"] = get_database_uri() connectable = AsyncEngine( engine_from_config( configuration, prefix="sqlalchemy.", poolclass=pool.NullPool, future=True, ) ) async with connectable.connect() as connection: await connection.run_sync(do_run_migrations) if context.is_offline_mode(): run_migrations_offline() else: try: loop: asyncio.AbstractEventLoop | None = asyncio.get_running_loop() except RuntimeError: loop = None if loop and loop.is_running(): # pytest-asyncio or other test runner is running the event loop # so we need to use run_coroutine_threadsafe future = asyncio.run_coroutine_threadsafe(run_migrations_online(), loop) future.result(timeout=15) else: # no event loop is running, safe to use asyncio.run asyncio.run(run_migrations_online()) ================================================ FILE: alembic/script.py.mako ================================================ """${message} Revision ID: ${up_revision} Revises: ${down_revision | comma,n} Create Date: ${create_date} """ from alembic import op import sqlalchemy as sa ${imports if imports else ""} # revision identifiers, used by Alembic. revision = ${repr(up_revision)} down_revision = ${repr(down_revision)} branch_labels = ${repr(branch_labels)} depends_on = ${repr(depends_on)} def upgrade(): ${upgrades if upgrades else "pass"} def downgrade(): ${downgrades if downgrades else "pass"} ================================================ FILE: alembic/versions/20260203_1616_initial_auth_683275eeb305.py ================================================ """initial_auth Revision ID: 683275eeb305 Revises: Create Date: 2026-02-03 16:16:09.776977 """ import sqlalchemy as sa from alembic import op # revision identifiers, used by Alembic. revision = "683275eeb305" down_revision = None branch_labels = None depends_on = None def upgrade(): # ### commands auto generated by Alembic - please adjust! ### op.create_table( "auth_user", sa.Column("user_id", sa.String(length=36), nullable=False), sa.Column("email", sa.String(length=256), nullable=False), sa.Column("hashed_password", sa.String(length=128), nullable=False), sa.Column( "created_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False, ), sa.Column( "updated_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False, ), sa.PrimaryKeyConstraint("user_id"), ) op.create_index(op.f("ix_auth_user_email"), "auth_user", ["email"], unique=True) op.create_table( "auth_refresh_token", sa.Column("id", sa.BigInteger(), nullable=False), sa.Column("refresh_token", sa.String(length=512), nullable=False), sa.Column("used", sa.Boolean(), nullable=False), sa.Column("exp", sa.BigInteger(), nullable=False), sa.Column("user_id", sa.String(length=36), nullable=False), sa.ForeignKeyConstraint(["user_id"], ["auth_user.user_id"], ondelete="CASCADE"), sa.PrimaryKeyConstraint("id"), ) op.create_index( op.f("ix_auth_refresh_token_refresh_token"), "auth_refresh_token", ["refresh_token"], unique=True, ) # ### end Alembic commands ### def downgrade(): # ### commands auto generated by Alembic - please adjust! ### op.drop_index( op.f("ix_auth_refresh_token_refresh_token"), table_name="auth_refresh_token" ) op.drop_table("auth_refresh_token") op.drop_index(op.f("ix_auth_user_email"), table_name="auth_user") op.drop_table("auth_user") # ### end Alembic commands ### ================================================ FILE: alembic.ini ================================================ # A generic, single database configuration. [alembic] # path to migration scripts script_location = alembic # template used to generate migration file names; The default value is %%(rev)s_%%(slug)s # Uncomment the line below if you want the files to be prepended with date and time file_template = %%(year)d%%(month).2d%%(day).2d_%%(hour).2d%%(minute).2d_%%(slug)s_%%(rev)s # sys.path path, will be prepended to sys.path if present. # defaults to the current working directory. prepend_sys_path = . # timezone to use when rendering the date within the migration file # as well as the filename. # If specified, requires the python>=3.9 or backports.zoneinfo library. # Any required deps can installed by adding `alembic[tz]` to the pip requirements # string value is passed to ZoneInfo() # leave blank for localtime # timezone = # max length of characters to apply to the # "slug" field truncate_slug_length = 40 # set to 'true' to run the environment during # the 'revision' command, regardless of autogenerate # revision_environment = false # set to 'true' to allow .pyc and .pyo files without # a source .py file to be detected as revisions in the # versions/ directory # sourceless = false # version location specification; This defaults # to ${script_location}/versions. When using multiple version # directories, initial revisions must be specified with --version-path. # The path separator used here should be the separator specified by "version_path_separator" below. # version_locations = %(here)s/bar:%(here)s/bat:${script_location}/versions # version path separator; As mentioned above, this is the character used to split # version_locations. The default within new alembic.ini files is "os", which uses os.pathsep. # If this key is omitted entirely, it falls back to the legacy behavior of splitting on spaces and/or commas. # Valid values for version_path_separator are: # # version_path_separator = : # version_path_separator = ; # version_path_separator = space version_path_separator = os # Use os.pathsep. Default configuration used for new projects. path_separator=os # set to 'true' to search source files recursively # in each "version_locations" directory # new in Alembic version 1.10 # recursive_version_locations = false # the output encoding used when revision files # are written from script.py.mako # output_encoding = utf-8 sqlalchemy.url = driver://user:pass@localhost/dbname [post_write_hooks] hooks = pre_commit pre_commit.type = console_scripts pre_commit.entrypoint = pre-commit pre_commit.options = run --files REVISION_SCRIPT_FILENAME # This section defines scripts or Python functions that are run # on newly generated revision scripts. See the documentation for further # detail and examples # format using "black" - use the console_scripts runner, # against the "black" entrypoint # Logging configuration [loggers] keys = root,sqlalchemy,alembic [handlers] keys = console [formatters] keys = generic [logger_root] level = WARN handlers = console qualname = [logger_sqlalchemy] level = WARN handlers = qualname = sqlalchemy.engine [logger_alembic] level = INFO handlers = qualname = alembic [handler_console] class = StreamHandler args = (sys.stderr,) level = NOTSET formatter = generic [formatter_generic] format = %(levelname)-5.5s [%(name)s] %(message)s datefmt = %H:%M:%S ================================================ FILE: app/__init__.py ================================================ ================================================ FILE: app/auth/api_messages.py ================================================ from typing import Any JWT_ERROR_USER_REMOVED = "User removed" PASSWORD_INVALID = "Incorrect email or password" REFRESH_TOKEN_NOT_FOUND = "Refresh token not found" REFRESH_TOKEN_EXPIRED = "Refresh token expired" REFRESH_TOKEN_ALREADY_USED = "Refresh token already used" EMAIL_ADDRESS_ALREADY_USED = "Cannot use this email address" UNAUTHORIZED_RESPONSES: dict[int | str, dict[str, Any]] = { 401: { "description": "No `Authorization` access token header, token is invalid or user removed", "content": { "application/json": { "examples": { "not authenticated": { "summary": "No authorization token header", "value": {"detail": "Not authenticated"}, }, "invalid token": { "summary": "Token validation failed, decode failed, it may be expired or malformed", "value": {"detail": "Token invalid: {detailed error msg}"}, }, "removed user": { "summary": JWT_ERROR_USER_REMOVED, "value": {"detail": JWT_ERROR_USER_REMOVED}, }, } } }, } } ACCESS_TOKEN_RESPONSES: dict[int | str, dict[str, Any]] = { 400: { "description": "Invalid email or password", "content": {"application/json": {"example": {"detail": PASSWORD_INVALID}}}, }, } REFRESH_TOKEN_RESPONSES: dict[int | str, dict[str, Any]] = { 400: { "description": "Refresh token expired or is already used", "content": { "application/json": { "examples": { "refresh token expired": { "summary": REFRESH_TOKEN_EXPIRED, "value": {"detail": REFRESH_TOKEN_EXPIRED}, }, "refresh token already used": { "summary": REFRESH_TOKEN_ALREADY_USED, "value": {"detail": REFRESH_TOKEN_ALREADY_USED}, }, } } }, }, 404: { "description": "Refresh token does not exist", "content": { "application/json": {"example": {"detail": REFRESH_TOKEN_NOT_FOUND}} }, }, } ================================================ FILE: app/auth/dependencies.py ================================================ from typing import Annotated from fastapi import Depends, HTTPException, status from fastapi.security import OAuth2PasswordBearer from sqlalchemy import select from sqlalchemy.ext.asyncio import AsyncSession from app.auth import api_messages from app.auth.jwt import verify_jwt_token from app.auth.models import User from app.core import database_session oauth2_scheme = OAuth2PasswordBearer(tokenUrl="auth/access-token") async def get_current_user( token: Annotated[str, Depends(oauth2_scheme)], session: AsyncSession = Depends(database_session.new_async_session), ) -> User: token_payload = verify_jwt_token(token) user = await session.scalar(select(User).where(User.user_id == token_payload.sub)) if user is None: raise HTTPException( status_code=status.HTTP_401_UNAUTHORIZED, detail=api_messages.JWT_ERROR_USER_REMOVED, ) return user ================================================ FILE: app/auth/jwt.py ================================================ import time import jwt from fastapi import HTTPException, status from pydantic import BaseModel from app.core.config import get_settings # Payload follows RFC 7519 # https://www.rfc-editor.org/rfc/rfc7519#section-4.1 class JWTTokenPayload(BaseModel): iss: str sub: str exp: int iat: int class JWTToken(BaseModel): payload: JWTTokenPayload access_token: str def create_jwt_token(user_id: str) -> JWTToken: iat = int(time.time()) exp = iat + get_settings().security.jwt_access_token_expire_secs token_payload = JWTTokenPayload( iss=get_settings().security.jwt_issuer, sub=user_id, exp=exp, iat=iat, ) access_token = jwt.encode( token_payload.model_dump(), key=get_settings().security.jwt_secret_key.get_secret_value(), algorithm=get_settings().security.jwt_algorithm, ) return JWTToken(payload=token_payload, access_token=access_token) def verify_jwt_token(token: str) -> JWTTokenPayload: # Pay attention to verify_signature passed explicite, even if it is the default. # Verification is based on expected payload fields like "exp", "iat" etc. # so if you rename for example "exp" to "my_custom_exp", this is gonna break, # jwt.ExpiredSignatureError will not be raised, that can potentialy # be major security risk - not validating tokens at all. # If unsure, jump into jwt.decode code, make sure tests are passing # https://pyjwt.readthedocs.io/en/stable/usage.html#encoding-decoding-tokens-with-hs256 try: raw_payload = jwt.decode( token, get_settings().security.jwt_secret_key.get_secret_value(), algorithms=[get_settings().security.jwt_algorithm], options={"verify_signature": True}, issuer=get_settings().security.jwt_issuer, ) except jwt.InvalidTokenError as e: raise HTTPException( status_code=status.HTTP_401_UNAUTHORIZED, detail=f"Token invalid: {e}", ) return JWTTokenPayload(**raw_payload) ================================================ FILE: app/auth/models.py ================================================ # SQL Alchemy models declaration. # https://docs.sqlalchemy.org/en/20/orm/quickstart.html#declare-models # mapped_column syntax from SQLAlchemy 2.0. # https://alembic.sqlalchemy.org/en/latest/tutorial.html # Note, it is used by alembic migrations logic, see `alembic/env.py` # Alembic shortcuts: # # create migration # alembic revision --autogenerate -m "migration_name" # # apply all migrations # alembic upgrade head import uuid from datetime import datetime import sqlalchemy as sa from sqlalchemy.orm import Mapped, mapped_column, relationship from app.core.models import Base class User(Base): __tablename__ = "auth_user" user_id: Mapped[str] = mapped_column( sa.String(36), primary_key=True, default=lambda _: str(uuid.uuid4()) ) email: Mapped[str] = mapped_column( sa.String(256), nullable=False, unique=True, index=True ) hashed_password: Mapped[str] = mapped_column(sa.String(128), nullable=False) created_at: Mapped[datetime] = mapped_column( sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False ) updated_at: Mapped[datetime] = mapped_column( sa.DateTime(timezone=True), server_default=sa.func.now(), onupdate=sa.func.now(), nullable=False, ) refresh_tokens: Mapped[list["RefreshToken"]] = relationship(back_populates="user") # noqa: UP037 class RefreshToken(Base): __tablename__ = "auth_refresh_token" id: Mapped[int] = mapped_column(sa.BigInteger, primary_key=True) refresh_token: Mapped[str] = mapped_column( sa.String(512), nullable=False, unique=True, index=True ) used: Mapped[bool] = mapped_column(sa.Boolean, nullable=False, default=False) exp: Mapped[int] = mapped_column(sa.BigInteger, nullable=False) user_id: Mapped[str] = mapped_column( sa.ForeignKey("auth_user.user_id", ondelete="CASCADE"), ) user: Mapped[User] = relationship(back_populates="refresh_tokens") ================================================ FILE: app/auth/password.py ================================================ import bcrypt from app.core.config import get_settings def verify_password(plain_password: str, hashed_password: str) -> bool: return bcrypt.checkpw( plain_password.encode("utf-8"), hashed_password.encode("utf-8") ) def get_password_hash(password: str) -> str: return bcrypt.hashpw( password.encode(), bcrypt.gensalt(get_settings().security.password_bcrypt_rounds), ).decode() DUMMY_PASSWORD = get_password_hash("") ================================================ FILE: app/auth/responses.py ================================================ from pydantic import BaseModel, ConfigDict, EmailStr class BaseResponse(BaseModel): model_config = ConfigDict(from_attributes=True) class AccessTokenResponse(BaseResponse): token_type: str = "Bearer" access_token: str expires_at: int refresh_token: str refresh_token_expires_at: int class UserResponse(BaseResponse): user_id: str email: EmailStr ================================================ FILE: app/auth/schemas.py ================================================ from pydantic import BaseModel, ConfigDict, EmailStr class RefreshTokenRequest(BaseModel): refresh_token: str class UserUpdatePasswordRequest(BaseModel): password: str class UserCreateRequest(BaseModel): email: EmailStr password: str class AccessTokenResponse(BaseModel): token_type: str = "Bearer" access_token: str expires_at: int refresh_token: str refresh_token_expires_at: int model_config = ConfigDict(from_attributes=True) class UserResponse(BaseModel): user_id: str email: EmailStr model_config = ConfigDict(from_attributes=True) ================================================ FILE: app/auth/tests/__init__.py ================================================ ================================================ FILE: app/auth/tests/test_jwt.py ================================================ import time import pytest from fastapi import HTTPException from freezegun import freeze_time from pydantic import SecretStr from app.auth import jwt from app.core.config import get_settings def test_jwt_access_token_can_be_decoded_back_into_user_id() -> None: user_id = "test_user_id" token = jwt.create_jwt_token(user_id) payload = jwt.verify_jwt_token(token=token.access_token) assert payload.sub == user_id @freeze_time("2024-01-01") def test_jwt_payload_is_correct() -> None: user_id = "test_user_id" token = jwt.create_jwt_token(user_id) assert token.payload.iat == int(time.time()) assert token.payload.sub == user_id assert token.payload.iss == get_settings().security.jwt_issuer assert ( token.payload.exp == int(time.time()) + get_settings().security.jwt_access_token_expire_secs ) def test_jwt_error_after_exp_time() -> None: user_id = "test_user_id" with freeze_time("2024-01-01"): token = jwt.create_jwt_token(user_id) with freeze_time("2024-02-01"): with pytest.raises(HTTPException) as e: jwt.verify_jwt_token(token=token.access_token) assert e.value.detail == "Token invalid: Signature has expired" def test_jwt_error_before_iat_time() -> None: user_id = "test_user_id" with freeze_time("2024-01-01"): token = jwt.create_jwt_token(user_id) with freeze_time("2023-12-01"): with pytest.raises(HTTPException) as e: jwt.verify_jwt_token(token=token.access_token) assert e.value.detail == "Token invalid: The token is not yet valid (iat)" def test_jwt_error_with_invalid_token() -> None: with pytest.raises(HTTPException) as e: jwt.verify_jwt_token(token="invalid!") assert e.value.detail == "Token invalid: Not enough segments" def test_jwt_error_with_invalid_issuer() -> None: user_id = "test_user_id" token = jwt.create_jwt_token(user_id) get_settings().security.jwt_issuer = "another_issuer" with pytest.raises(HTTPException) as e: jwt.verify_jwt_token(token=token.access_token) assert e.value.detail == "Token invalid: Invalid issuer" def test_jwt_error_with_invalid_secret_key() -> None: user_id = "test_user_id" token = jwt.create_jwt_token(user_id) get_settings().security.jwt_secret_key = SecretStr("x" * 32) with pytest.raises(HTTPException) as e: jwt.verify_jwt_token(token=token.access_token) assert e.value.detail == "Token invalid: Signature verification failed" ================================================ FILE: app/auth/tests/test_password.py ================================================ from app.auth.password import get_password_hash, verify_password def test_hashed_password_is_verified() -> None: pwd_hash = get_password_hash("my_password") assert verify_password("my_password", pwd_hash) def test_invalid_password_is_not_verified() -> None: pwd_hash = get_password_hash("my_password") assert not verify_password("my_password_invalid", pwd_hash) ================================================ FILE: app/auth/tests/test_view_delete_current_user.py ================================================ from fastapi import status from httpx import AsyncClient from sqlalchemy import select from sqlalchemy.ext.asyncio import AsyncSession from app.auth.models import User from app.main import app async def test_delete_current_user_status_code( client: AsyncClient, default_user_headers: dict[str, str], ) -> None: response = await client.delete( app.url_path_for("delete_current_user"), headers=default_user_headers, ) assert response.status_code == status.HTTP_204_NO_CONTENT async def test_delete_current_user_is_deleted_in_db( client: AsyncClient, default_user_headers: dict[str, str], default_user: User, session: AsyncSession, ) -> None: await client.delete( app.url_path_for("delete_current_user"), headers=default_user_headers, ) user = await session.scalar( select(User).where(User.user_id == default_user.user_id) ) assert user is None ================================================ FILE: app/auth/tests/test_view_login_access_token.py ================================================ import time from fastapi import status from freezegun import freeze_time from httpx import AsyncClient from sqlalchemy import func, select from sqlalchemy.ext.asyncio import AsyncSession from app.auth import api_messages from app.auth.jwt import verify_jwt_token from app.auth.models import RefreshToken, User from app.core.config import get_settings from app.main import app from app.tests.auth import TESTS_USER_PASSWORD async def test_login_access_token_has_response_status_code( client: AsyncClient, default_user: User, ) -> None: response = await client.post( app.url_path_for("login_access_token"), data={ "username": default_user.email, "password": TESTS_USER_PASSWORD, }, headers={"Content-Type": "application/x-www-form-urlencoded"}, ) assert response.status_code == status.HTTP_200_OK, response.text async def test_login_access_token_jwt_has_valid_token_type( client: AsyncClient, default_user: User, ) -> None: response = await client.post( app.url_path_for("login_access_token"), data={ "username": default_user.email, "password": TESTS_USER_PASSWORD, }, headers={"Content-Type": "application/x-www-form-urlencoded"}, ) assert response.status_code == status.HTTP_200_OK, response.text token = response.json() assert token["token_type"] == "Bearer" @freeze_time("2023-01-01") async def test_login_access_token_jwt_has_valid_expire_time( client: AsyncClient, default_user: User, ) -> None: response = await client.post( app.url_path_for("login_access_token"), data={ "username": default_user.email, "password": TESTS_USER_PASSWORD, }, headers={"Content-Type": "application/x-www-form-urlencoded"}, ) assert response.status_code == status.HTTP_200_OK, response.text token = response.json() current_timestamp = int(time.time()) assert ( token["expires_at"] == current_timestamp + get_settings().security.jwt_access_token_expire_secs ) @freeze_time("2023-01-01") async def test_login_access_token_returns_valid_jwt_access_token( client: AsyncClient, default_user: User, ) -> None: response = await client.post( app.url_path_for("login_access_token"), data={ "username": default_user.email, "password": TESTS_USER_PASSWORD, }, headers={"Content-Type": "application/x-www-form-urlencoded"}, ) assert response.status_code == status.HTTP_200_OK, response.text now = int(time.time()) token = response.json() token_payload = verify_jwt_token(token["access_token"]) assert token_payload.sub == default_user.user_id assert token_payload.iat == now assert token_payload.exp == token["expires_at"] async def test_login_access_token_refresh_token_has_valid_expire_time( client: AsyncClient, default_user: User, ) -> None: response = await client.post( app.url_path_for("login_access_token"), data={ "username": default_user.email, "password": TESTS_USER_PASSWORD, }, headers={"Content-Type": "application/x-www-form-urlencoded"}, ) assert response.status_code == status.HTTP_200_OK, response.text token = response.json() current_time = int(time.time()) assert ( token["refresh_token_expires_at"] == current_time + get_settings().security.jwt_refresh_token_expire_secs ) async def test_login_access_token_refresh_token_exists_in_db( client: AsyncClient, default_user: User, session: AsyncSession, ) -> None: response = await client.post( app.url_path_for("login_access_token"), data={ "username": default_user.email, "password": TESTS_USER_PASSWORD, }, headers={"Content-Type": "application/x-www-form-urlencoded"}, ) assert response.status_code == status.HTTP_200_OK, response.text token = response.json() token_db_count = await session.scalar( select(func.count()).where(RefreshToken.refresh_token == token["refresh_token"]) ) assert token_db_count == 1 async def test_login_access_token_refresh_token_in_db_has_valid_fields( client: AsyncClient, default_user: User, session: AsyncSession, ) -> None: response = await client.post( app.url_path_for("login_access_token"), data={ "username": default_user.email, "password": TESTS_USER_PASSWORD, }, headers={"Content-Type": "application/x-www-form-urlencoded"}, ) assert response.status_code == status.HTTP_200_OK, response.text token = response.json() result = await session.scalars( select(RefreshToken).where(RefreshToken.refresh_token == token["refresh_token"]) ) refresh_token = result.one() assert refresh_token.user_id == default_user.user_id assert refresh_token.exp == token["refresh_token_expires_at"] assert not refresh_token.used async def test_auth_access_token_fail_for_not_existing_user_with_message( client: AsyncClient, ) -> None: response = await client.post( app.url_path_for("login_access_token"), data={ "username": "non-existing", "password": "bla", }, headers={"Content-Type": "application/x-www-form-urlencoded"}, ) assert response.status_code == status.HTTP_400_BAD_REQUEST, response.text assert response.json() == {"detail": api_messages.PASSWORD_INVALID} async def test_auth_access_token_fail_for_invalid_password_with_message( client: AsyncClient, default_user: User, ) -> None: response = await client.post( app.url_path_for("login_access_token"), data={ "username": default_user.email, "password": "invalid", }, headers={"Content-Type": "application/x-www-form-urlencoded"}, ) assert response.status_code == status.HTTP_400_BAD_REQUEST, response.text assert response.json() == {"detail": api_messages.PASSWORD_INVALID} ================================================ FILE: app/auth/tests/test_view_read_current_user.py ================================================ from fastapi import status from freezegun import freeze_time from httpx import AsyncClient from sqlalchemy import delete from sqlalchemy.ext.asyncio import AsyncSession from app.auth import api_messages from app.auth.jwt import create_jwt_token from app.auth.models import User from app.main import app async def test_read_current_user_status_code( client: AsyncClient, default_user_headers: dict[str, str], default_user: User, ) -> None: response = await client.get( app.url_path_for("read_current_user"), headers=default_user_headers, ) assert response.status_code == status.HTTP_200_OK async def test_read_current_user_response( client: AsyncClient, default_user_headers: dict[str, str], default_user: User, ) -> None: response = await client.get( app.url_path_for("read_current_user"), headers=default_user_headers, ) assert response.json() == { "user_id": default_user.user_id, "email": default_user.email, } async def test_api_raise_401_on_jwt_decode_errors( client: AsyncClient, ) -> None: response = await client.get( app.url_path_for("read_current_user"), headers={"Authorization": "Bearer garbage-invalid-jwt"}, ) assert response.status_code == status.HTTP_401_UNAUTHORIZED, response.text assert response.json() == {"detail": "Token invalid: Not enough segments"} async def test_api_raise_401_on_jwt_expired_token( client: AsyncClient, default_user: User, ) -> None: with freeze_time("2023-01-01"): jwt = create_jwt_token(default_user.user_id) with freeze_time("2023-02-01"): response = await client.get( app.url_path_for("read_current_user"), headers={"Authorization": f"Bearer {jwt.access_token}"}, ) assert response.status_code == status.HTTP_401_UNAUTHORIZED, response.text assert response.json() == {"detail": "Token invalid: Signature has expired"} async def test_api_raise_401_on_jwt_user_deleted( client: AsyncClient, default_user_headers: dict[str, str], default_user: User, session: AsyncSession, ) -> None: await session.execute(delete(User).where(User.user_id == default_user.user_id)) await session.commit() response = await client.get( app.url_path_for("read_current_user"), headers=default_user_headers, ) assert response.status_code == status.HTTP_401_UNAUTHORIZED, response.text assert response.json() == {"detail": api_messages.JWT_ERROR_USER_REMOVED} ================================================ FILE: app/auth/tests/test_view_refresh_token.py ================================================ import time from fastapi import status from freezegun import freeze_time from httpx import AsyncClient from sqlalchemy import func, select from sqlalchemy.ext.asyncio import AsyncSession from app.auth import api_messages from app.auth.jwt import verify_jwt_token from app.auth.models import RefreshToken, User from app.core.config import get_settings from app.main import app async def test_refresh_token_fails_with_message_when_token_does_not_exist( client: AsyncClient, ) -> None: response = await client.post( app.url_path_for("refresh_token"), json={ "refresh_token": "blaxx", }, ) assert response.status_code == status.HTTP_404_NOT_FOUND assert response.json() == {"detail": api_messages.REFRESH_TOKEN_NOT_FOUND} async def test_refresh_token_fails_with_message_when_token_is_expired( client: AsyncClient, default_user: User, session: AsyncSession, ) -> None: test_refresh_token = RefreshToken( user_id=default_user.user_id, refresh_token="blaxx", exp=int(time.time()) - 1, ) session.add(test_refresh_token) await session.commit() response = await client.post( app.url_path_for("refresh_token"), json={ "refresh_token": "blaxx", }, ) assert response.status_code == status.HTTP_400_BAD_REQUEST assert response.json() == {"detail": api_messages.REFRESH_TOKEN_EXPIRED} async def test_refresh_token_fails_with_message_when_token_is_used( client: AsyncClient, default_user: User, session: AsyncSession, ) -> None: test_refresh_token = RefreshToken( user_id=default_user.user_id, refresh_token="blaxx", exp=int(time.time()) + 1000, used=True, ) session.add(test_refresh_token) await session.commit() response = await client.post( app.url_path_for("refresh_token"), json={ "refresh_token": "blaxx", }, ) assert response.status_code == status.HTTP_400_BAD_REQUEST assert response.json() == {"detail": api_messages.REFRESH_TOKEN_ALREADY_USED} async def test_refresh_token_success_response_status_code( client: AsyncClient, default_user: User, session: AsyncSession, ) -> None: test_refresh_token = RefreshToken( user_id=default_user.user_id, refresh_token="blaxx", exp=int(time.time()) + 1000, used=False, ) session.add(test_refresh_token) await session.commit() response = await client.post( app.url_path_for("refresh_token"), json={ "refresh_token": "blaxx", }, ) assert response.status_code == status.HTTP_200_OK async def test_refresh_token_success_old_token_is_used( client: AsyncClient, default_user: User, session: AsyncSession, ) -> None: test_refresh_token = RefreshToken( user_id=default_user.user_id, refresh_token="blaxx", exp=int(time.time()) + 1000, used=False, ) session.add(test_refresh_token) await session.commit() await client.post( app.url_path_for("refresh_token"), json={ "refresh_token": "blaxx", }, ) used_test_refresh_token = await session.scalar( select(RefreshToken).where(RefreshToken.refresh_token == "blaxx") ) assert used_test_refresh_token is not None assert used_test_refresh_token.used async def test_refresh_token_success_jwt_has_valid_token_type( client: AsyncClient, default_user: User, session: AsyncSession, ) -> None: test_refresh_token = RefreshToken( user_id=default_user.user_id, refresh_token="blaxx", exp=int(time.time()) + 1000, used=False, ) session.add(test_refresh_token) await session.commit() response = await client.post( app.url_path_for("refresh_token"), json={ "refresh_token": "blaxx", }, ) token = response.json() assert token["token_type"] == "Bearer" @freeze_time("2023-01-01") async def test_refresh_token_success_jwt_has_valid_expire_time( client: AsyncClient, default_user: User, session: AsyncSession, ) -> None: test_refresh_token = RefreshToken( user_id=default_user.user_id, refresh_token="blaxx", exp=int(time.time()) + 1000, used=False, ) session.add(test_refresh_token) await session.commit() response = await client.post( app.url_path_for("refresh_token"), json={ "refresh_token": "blaxx", }, ) token = response.json() current_timestamp = int(time.time()) assert ( token["expires_at"] == current_timestamp + get_settings().security.jwt_access_token_expire_secs ) @freeze_time("2023-01-01") async def test_refresh_token_success_jwt_has_valid_access_token( client: AsyncClient, default_user: User, session: AsyncSession, ) -> None: test_refresh_token = RefreshToken( user_id=default_user.user_id, refresh_token="blaxx", exp=int(time.time()) + 1000, used=False, ) session.add(test_refresh_token) await session.commit() response = await client.post( app.url_path_for("refresh_token"), json={ "refresh_token": "blaxx", }, ) now = int(time.time()) token = response.json() token_payload = verify_jwt_token(token["access_token"]) assert token_payload.sub == default_user.user_id assert token_payload.iat == now assert token_payload.exp == token["expires_at"] @freeze_time("2023-01-01") async def test_refresh_token_success_refresh_token_has_valid_expire_time( client: AsyncClient, default_user: User, session: AsyncSession, ) -> None: test_refresh_token = RefreshToken( user_id=default_user.user_id, refresh_token="blaxx", exp=int(time.time()) + 1000, used=False, ) session.add(test_refresh_token) await session.commit() response = await client.post( app.url_path_for("refresh_token"), json={ "refresh_token": "blaxx", }, ) token = response.json() current_time = int(time.time()) assert ( token["refresh_token_expires_at"] == current_time + get_settings().security.jwt_refresh_token_expire_secs ) async def test_refresh_token_success_new_refresh_token_is_in_db( client: AsyncClient, default_user: User, session: AsyncSession, ) -> None: test_refresh_token = RefreshToken( user_id=default_user.user_id, refresh_token="blaxx", exp=int(time.time()) + 1000, used=False, ) session.add(test_refresh_token) await session.commit() response = await client.post( app.url_path_for("refresh_token"), json={ "refresh_token": "blaxx", }, ) token = response.json() token_db_count = await session.scalar( select(func.count()).where(RefreshToken.refresh_token == token["refresh_token"]) ) assert token_db_count == 1 ================================================ FILE: app/auth/tests/test_view_register_new_user.py ================================================ from fastapi import status from httpx import AsyncClient from sqlalchemy import func, select from sqlalchemy.ext.asyncio import AsyncSession from app.auth import api_messages from app.auth.models import User from app.main import app from app.tests.factories import UserFactory async def test_register_new_user_status_code( client: AsyncClient, ) -> None: response = await client.post( app.url_path_for("register_new_user"), json={ "email": "test@email.com", "password": "testtesttest", }, ) assert response.status_code == status.HTTP_201_CREATED async def test_register_new_user_creates_record_in_db( client: AsyncClient, session: AsyncSession, ) -> None: await client.post( app.url_path_for("register_new_user"), json={ "email": "test@email.com", "password": "testtesttest", }, ) user_count = await session.scalar( select(func.count()).where(User.email == "test@email.com") ) assert user_count == 1 async def test_register_new_user_cannot_create_already_created_user( client: AsyncClient, session: AsyncSession, ) -> None: existing_user = await UserFactory.create_async() response = await client.post( app.url_path_for("register_new_user"), json={ "email": existing_user.email, "password": "testtesttest", }, ) assert response.status_code == status.HTTP_400_BAD_REQUEST assert response.json() == {"detail": api_messages.EMAIL_ADDRESS_ALREADY_USED} ================================================ FILE: app/auth/tests/test_view_reset_current_user_password.py ================================================ from fastapi import status from httpx import AsyncClient from sqlalchemy import select from sqlalchemy.ext.asyncio import AsyncSession from app.auth.models import User from app.auth.password import verify_password from app.main import app async def test_reset_current_user_password_status_code( client: AsyncClient, default_user_headers: dict[str, str], ) -> None: response = await client.post( app.url_path_for("reset_current_user_password"), headers=default_user_headers, json={"password": "test_pwd"}, ) assert response.status_code == status.HTTP_204_NO_CONTENT async def test_reset_current_user_password_is_changed_in_db( client: AsyncClient, default_user_headers: dict[str, str], default_user: User, session: AsyncSession, ) -> None: await client.post( app.url_path_for("reset_current_user_password"), headers=default_user_headers, json={"password": "test_pwd"}, ) user = await session.scalar( select(User).where(User.user_id == default_user.user_id) ) assert user is not None assert verify_password("test_pwd", user.hashed_password) ================================================ FILE: app/auth/views.py ================================================ import secrets import time from fastapi import APIRouter, Depends, HTTPException, status from fastapi.security import OAuth2PasswordRequestForm from sqlalchemy import delete, select from sqlalchemy.exc import IntegrityError from sqlalchemy.ext.asyncio import AsyncSession from app.auth import api_messages, dependencies from app.auth.jwt import create_jwt_token from app.auth.models import RefreshToken, User from app.auth.password import ( DUMMY_PASSWORD, get_password_hash, verify_password, ) from app.auth.schemas import ( AccessTokenResponse, RefreshTokenRequest, UserCreateRequest, UserResponse, UserUpdatePasswordRequest, ) from app.core.config import get_settings from app.core.database_session import new_async_session router = APIRouter(responses=api_messages.UNAUTHORIZED_RESPONSES) @router.get("/me", response_model=UserResponse, description="Get current user") async def read_current_user( current_user: User = Depends(dependencies.get_current_user), ) -> User: return current_user @router.delete( "/me", status_code=status.HTTP_204_NO_CONTENT, description="Delete current user", ) async def delete_current_user( current_user: User = Depends(dependencies.get_current_user), session: AsyncSession = Depends(new_async_session), ) -> None: await session.execute(delete(User).where(User.user_id == current_user.user_id)) await session.commit() @router.post( "/reset-password", status_code=status.HTTP_204_NO_CONTENT, description="Update current user password", ) async def reset_current_user_password( user_update_password: UserUpdatePasswordRequest, session: AsyncSession = Depends(new_async_session), current_user: User = Depends(dependencies.get_current_user), ) -> None: current_user.hashed_password = get_password_hash(user_update_password.password) session.add(current_user) await session.commit() @router.post( "/access-token", response_model=AccessTokenResponse, responses=api_messages.ACCESS_TOKEN_RESPONSES, description="OAuth2 compatible token, get an access token for future requests using username and password", ) async def login_access_token( session: AsyncSession = Depends(new_async_session), form_data: OAuth2PasswordRequestForm = Depends(), ) -> AccessTokenResponse: user = await session.scalar(select(User).where(User.email == form_data.username)) if user is None: # this is naive method to not return early verify_password(form_data.password, DUMMY_PASSWORD) raise HTTPException( status_code=status.HTTP_400_BAD_REQUEST, detail=api_messages.PASSWORD_INVALID, ) if not verify_password(form_data.password, user.hashed_password): raise HTTPException( status_code=status.HTTP_400_BAD_REQUEST, detail=api_messages.PASSWORD_INVALID, ) jwt_token = create_jwt_token(user_id=user.user_id) refresh_token = RefreshToken( user_id=user.user_id, refresh_token=secrets.token_urlsafe(32), exp=int(time.time() + get_settings().security.jwt_refresh_token_expire_secs), ) session.add(refresh_token) await session.commit() return AccessTokenResponse( access_token=jwt_token.access_token, expires_at=jwt_token.payload.exp, refresh_token=refresh_token.refresh_token, refresh_token_expires_at=refresh_token.exp, ) @router.post( "/refresh-token", response_model=AccessTokenResponse, responses=api_messages.REFRESH_TOKEN_RESPONSES, description="OAuth2 compatible token, get an access token for future requests using refresh token", ) async def refresh_token( data: RefreshTokenRequest, session: AsyncSession = Depends(new_async_session), ) -> AccessTokenResponse: token = await session.scalar( select(RefreshToken) .where(RefreshToken.refresh_token == data.refresh_token) .with_for_update(skip_locked=True) ) if token is None: raise HTTPException( status_code=status.HTTP_404_NOT_FOUND, detail=api_messages.REFRESH_TOKEN_NOT_FOUND, ) elif time.time() > token.exp: raise HTTPException( status_code=status.HTTP_400_BAD_REQUEST, detail=api_messages.REFRESH_TOKEN_EXPIRED, ) elif token.used: raise HTTPException( status_code=status.HTTP_400_BAD_REQUEST, detail=api_messages.REFRESH_TOKEN_ALREADY_USED, ) token.used = True session.add(token) jwt_token = create_jwt_token(user_id=token.user_id) refresh_token = RefreshToken( user_id=token.user_id, refresh_token=secrets.token_urlsafe(32), exp=int(time.time() + get_settings().security.jwt_refresh_token_expire_secs), ) session.add(refresh_token) await session.commit() return AccessTokenResponse( access_token=jwt_token.access_token, expires_at=jwt_token.payload.exp, refresh_token=refresh_token.refresh_token, refresh_token_expires_at=refresh_token.exp, ) @router.post( "/register", response_model=UserResponse, description="Create new user", status_code=status.HTTP_201_CREATED, ) async def register_new_user( new_user: UserCreateRequest, session: AsyncSession = Depends(new_async_session), ) -> User: user = await session.scalar(select(User).where(User.email == new_user.email)) if user is not None: raise HTTPException( status_code=status.HTTP_400_BAD_REQUEST, detail=api_messages.EMAIL_ADDRESS_ALREADY_USED, ) user = User( email=new_user.email, hashed_password=get_password_hash(new_user.password), ) session.add(user) try: await session.commit() except IntegrityError: # pragma: no cover await session.rollback() raise HTTPException( status_code=status.HTTP_400_BAD_REQUEST, detail=api_messages.EMAIL_ADDRESS_ALREADY_USED, ) return user ================================================ FILE: app/conftest.py ================================================ import asyncio import os from collections.abc import AsyncGenerator import alembic.command import alembic.config import pytest import pytest_asyncio import sqlalchemy from httpx import ASGITransport, AsyncClient from polyfactory.factories.sqlalchemy_factory import ( SQLAASyncPersistence, SQLAlchemyFactory, ) from sqlalchemy.ext.asyncio import ( AsyncSession, async_sessionmaker, ) from app.auth.jwt import create_jwt_token from app.auth.models import User from app.core import database_session from app.core.config import PROJECT_DIR, get_settings from app.core.database_session import new_async_session from app.main import app as fastapi_app from app.tests.factories import UserFactory @pytest_asyncio.fixture(scope="session", loop_scope="session", autouse=True) async def fixture_setup_new_test_database() -> AsyncGenerator[None]: worker_name = os.getenv("PYTEST_XDIST_WORKER", "gw0") test_db_name = f"test_db_{worker_name}" # create new test db using connection to current database conn = await database_session._ASYNC_ENGINE.connect() await conn.execution_options(isolation_level="AUTOCOMMIT") await conn.execute(sqlalchemy.text(f"DROP DATABASE IF EXISTS {test_db_name}")) await conn.execute(sqlalchemy.text(f"CREATE DATABASE {test_db_name}")) await conn.close() # dispose the original engine before switching to test database await database_session._ASYNC_ENGINE.dispose() session_mpatch = pytest.MonkeyPatch() session_mpatch.setenv("DATABASE__DB", test_db_name) session_mpatch.setenv("SECURITY__PASSWORD_BCRYPT_ROUNDS", "4") # force settings to use now monkeypatched environments get_settings.cache_clear() # monkeypatch test database engine engine = database_session.new_async_engine(get_settings().sqlalchemy_database_uri) session_mpatch.setattr( database_session, "_ASYNC_ENGINE", engine, ) session_mpatch.setattr( database_session, "_ASYNC_SESSIONMAKER", async_sessionmaker(engine, expire_on_commit=False), ) def alembic_upgrade() -> None: # synchronous function to run alembic upgrade alembic_config = alembic.config.Config(PROJECT_DIR / "alembic.ini") alembic.command.upgrade(alembic_config, "head") loop = asyncio.get_running_loop() await loop.run_in_executor(None, alembic_upgrade) yield # cleanup: dispose the test engine await engine.dispose() @pytest_asyncio.fixture(scope="function", loop_scope="session", autouse=True) async def fixture_clean_get_settings_between_tests() -> AsyncGenerator[None]: yield get_settings.cache_clear() @pytest_asyncio.fixture(name="session", loop_scope="session", scope="function") async def fixture_session_with_rollback( monkeypatch: pytest.MonkeyPatch, ) -> AsyncGenerator[AsyncSession]: # we want to monkeypatch new_async_session with one bound to session # that we will always rollback on function scope connection = await database_session._ASYNC_ENGINE.connect() transaction = await connection.begin() session = AsyncSession(bind=connection, expire_on_commit=False) monkeypatch.setattr( database_session, "new_script_async_session", lambda: session, ) fastapi_app.dependency_overrides[new_async_session] = lambda: session # now some work around SQLAlchemyFactory to actually use our session # refer to https://polyfactory.litestar.dev/latest/usage/configuration.html persistence_handler = SQLAASyncPersistence(session=session) # type: ignore setattr(SQLAlchemyFactory, "__async_persistence__", persistence_handler) yield session setattr(SQLAlchemyFactory, "__async_persistence__", None) fastapi_app.dependency_overrides.pop(new_async_session, None) await session.close() await transaction.rollback() await connection.close() @pytest_asyncio.fixture(name="client", loop_scope="session", scope="function") async def fixture_client(session: AsyncSession) -> AsyncGenerator[AsyncClient]: transport = ASGITransport(app=fastapi_app) async with AsyncClient(transport=transport, base_url="http://test") as aclient: aclient.headers.update({"Host": "localhost"}) yield aclient @pytest_asyncio.fixture(name="default_user", loop_scope="session", scope="function") async def fixture_default_user(session: AsyncSession) -> AsyncGenerator[User]: yield await UserFactory.create_async() @pytest_asyncio.fixture( name="default_user_headers", loop_scope="session", scope="function" ) async def fixture_default_user_headers(default_user: User) -> dict[str, str]: access_token = create_jwt_token(user_id=default_user.user_id).access_token return {"Authorization": f"Bearer {access_token}"} ================================================ FILE: app/core/__init__.py ================================================ ================================================ FILE: app/core/config.py ================================================ # File with environment variables and general configuration logic. # Env variables are combined in nested groups like "Security", "Database" etc. # So environment variable (case-insensitive) for jwt_secret_key will be "security__jwt_secret_key" # # Pydantic priority ordering: # # 1. (Most important, will overwrite everything) - environment variables # 2. `.env` file in root folder of project # 3. Default values # # "sqlalchemy_database_uri" is computed field that will create valid database URL # # See https://pydantic-docs.helpmanual.io/usage/settings/ # Note, complex types like lists are read as json-encoded strings. import logging.config from functools import lru_cache from pathlib import Path from pydantic import AnyHttpUrl, BaseModel, Field, SecretStr, computed_field from pydantic_settings import BaseSettings, SettingsConfigDict from sqlalchemy.engine.url import URL PROJECT_DIR = Path(__file__).parent.parent.parent class Security(BaseModel): jwt_issuer: str = "my-app" jwt_secret_key: SecretStr = SecretStr( "change-me-to-a-strong-secret-key-at-least-32-chars-long" ) jwt_access_token_expire_secs: int = Field(default=15 * 60, gt=10) # 15min jwt_refresh_token_expire_secs: int = Field(default=28 * 24 * 3600, gt=60) # 28d jwt_algorithm: str = "HS256" password_bcrypt_rounds: int = 12 allowed_hosts: list[str] = ["localhost", "127.0.0.1", "0.0.0.0"] backend_cors_origins: list[AnyHttpUrl] = [] class Database(BaseModel): hostname: str = "postgres" username: str = "postgres" password: SecretStr = SecretStr("passwd-change-me") port: int = 5432 db: str = "postgres" class Prometheus(BaseModel): enabled: bool = False port: int = 9090 addr: str = "0.0.0.0" stop_delay_secs: int = 0 class Settings(BaseSettings): security: Security = Field(default_factory=Security) database: Database = Field(default_factory=Database) prometheus: Prometheus = Field(default_factory=Prometheus) log_level: str = "INFO" @computed_field # type: ignore[prop-decorator] @property def sqlalchemy_database_uri(self) -> URL: return URL.create( drivername="postgresql+asyncpg", username=self.database.username, password=self.database.password.get_secret_value(), host=self.database.hostname, port=self.database.port, database=self.database.db, ) model_config = SettingsConfigDict( env_file=f"{PROJECT_DIR}/.env", case_sensitive=False, env_nested_delimiter="__", ) @lru_cache(maxsize=1) def get_settings() -> Settings: return Settings() def logging_config(log_level: str) -> None: conf = { "version": 1, "disable_existing_loggers": False, "formatters": { "verbose": { "format": "{asctime} [{levelname}] {name}: {message}", "style": "{", }, }, "handlers": { "stream": { "class": "logging.StreamHandler", "formatter": "verbose", "level": "DEBUG", }, }, "loggers": { "": { "level": log_level, "handlers": ["stream"], "propagate": True, }, }, } logging.config.dictConfig(conf) logging_config(log_level=get_settings().log_level) ================================================ FILE: app/core/database_session.py ================================================ # SQLAlchemy async engine and sessions tools # # https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html # # for pool size configuration: # https://docs.sqlalchemy.org/en/20/core/pooling.html#sqlalchemy.pool.Pool from collections.abc import AsyncGenerator from contextlib import asynccontextmanager from sqlalchemy.engine.url import URL from sqlalchemy.ext.asyncio import ( AsyncEngine, AsyncSession, async_sessionmaker, create_async_engine, ) from app.core.config import get_settings def new_async_engine(uri: URL) -> AsyncEngine: return create_async_engine( uri, pool_pre_ping=True, pool_size=5, max_overflow=10, pool_timeout=30.0, pool_recycle=600, ) _ASYNC_ENGINE = new_async_engine(get_settings().sqlalchemy_database_uri) _ASYNC_SESSIONMAKER = async_sessionmaker(_ASYNC_ENGINE, expire_on_commit=False) async def new_async_session() -> AsyncGenerator[AsyncSession]: # pragma: no cover session = _ASYNC_SESSIONMAKER() try: yield session finally: await session.close() @asynccontextmanager async def new_script_async_session() -> AsyncGenerator[ AsyncSession ]: # pragma: no cover # you can use this version inside scripts that run eg. as cronjobs outside of FastAPI context # that you will run with asyncio.run() # Global enginer and sessionmaker are created by global loop and cannot be shared across loops, # so we need to create new ones here _engine = create_async_engine( get_settings().sqlalchemy_database_uri, pool_pre_ping=True ) _async_sessionmaker = async_sessionmaker(_engine, expire_on_commit=False) session = _async_sessionmaker() try: yield session finally: await session.close() await _engine.dispose() ================================================ FILE: app/core/lifespan.py ================================================ import asyncio import logging from collections.abc import AsyncGenerator from contextlib import asynccontextmanager import prometheus_client from fastapi import FastAPI from app.core import database_session, metrics from app.core.config import get_settings logger = logging.getLogger(__name__) @asynccontextmanager async def lifespan(_: FastAPI) -> AsyncGenerator[None]: # pragma: no cover logger.info("starting application...") if get_settings().prometheus.enabled: logger.info( "starting prometheus client server on interface %s port %d", get_settings().prometheus.addr, get_settings().prometheus.port, ) prometheus_client.start_http_server( addr=get_settings().prometheus.addr, port=get_settings().prometheus.port, ) metrics.APP_STARTED.inc() yield logger.info("shutting down application...") await database_session._ASYNC_ENGINE.dispose() logger.info("disposed database engine and closed connections...") if get_settings().prometheus.enabled: logger.info( "stopping prometheus with delay of %d seconds...", get_settings().prometheus.stop_delay_secs, ) metrics.APP_STOPPED.inc() await asyncio.sleep(get_settings().prometheus.stop_delay_secs) logger.info("bye! application shutdown completed") ================================================ FILE: app/core/metrics.py ================================================ import prometheus_client NAMESPACE = "org" SUBSYSTEM = "app" APP_STARTED = prometheus_client.Counter( "app_started_total", "FastAPI application start count", labelnames=(), namespace=NAMESPACE, subsystem=SUBSYSTEM, ) APP_STOPPED = prometheus_client.Counter( "app_stopped", "FastAPI application stop count", labelnames=(), namespace=NAMESPACE, subsystem=SUBSYSTEM, ) ================================================ FILE: app/core/models.py ================================================ from sqlalchemy.orm import DeclarativeBase class Base(DeclarativeBase): pass ================================================ FILE: app/main.py ================================================ import logging from fastapi import FastAPI from fastapi.middleware.cors import CORSMiddleware from fastapi.middleware.trustedhost import TrustedHostMiddleware from app.auth.views import router as auth_router from app.core import lifespan from app.core.config import get_settings from app.probe.views import router as probe_router logger = logging.getLogger(__name__) app = FastAPI( title="minimal fastapi postgres template", version="7.0.0", description="https://github.com/rafsaf/minimal-fastapi-postgres-template", openapi_url="/openapi.json", docs_url="/", lifespan=lifespan.lifespan, ) app.include_router(auth_router, prefix="/auth", tags=["auth"]) app.include_router(probe_router, prefix="/probe", tags=["probe"]) # Sets all CORS enabled origins app.add_middleware( CORSMiddleware, allow_origins=[ str(origin).rstrip("/") for origin in get_settings().security.backend_cors_origins ], allow_credentials=True, allow_methods=["*"], allow_headers=["*"], ) # Guards against HTTP Host Header attacks app.add_middleware( TrustedHostMiddleware, allowed_hosts=get_settings().security.allowed_hosts, ) ================================================ FILE: app/probe/__init__.py ================================================ ================================================ FILE: app/probe/tests/__init__.py ================================================ ================================================ FILE: app/probe/tests/test_views.py ================================================ from httpx import AsyncClient, codes from app.main import app async def test_live_probe(client: AsyncClient) -> None: response = await client.get(app.url_path_for("live_probe")) assert response.status_code == codes.OK assert response.text == '"ok"' async def test_health_probe(client: AsyncClient) -> None: response = await client.get(app.url_path_for("health_probe")) assert response.status_code == codes.OK assert response.text == '"app and database ok"' ================================================ FILE: app/probe/views.py ================================================ import logging import typing from fastapi import APIRouter, Depends from sqlalchemy.ext.asyncio import AsyncSession from app.core.database_session import new_async_session logger = logging.getLogger(__name__) router = APIRouter() @router.get("/live", response_model=str) async def live_probe() -> typing.Literal["ok"]: return "ok" @router.get("/health", response_model=str) async def health_probe( _: AsyncSession = Depends(new_async_session), ) -> typing.Literal["app and database ok"]: return "app and database ok" ================================================ FILE: app/tests/auth.py ================================================ TESTS_USER_PASSWORD = "geralt" ================================================ FILE: app/tests/factories.py ================================================ import logging from typing import TypeVar from faker import Faker from polyfactory.factories.sqlalchemy_factory import SQLAlchemyFactory from polyfactory.fields import Use from app.auth.models import User from app.auth.password import get_password_hash from app.tests.auth import TESTS_USER_PASSWORD logging.getLogger("factory").setLevel(logging.ERROR) T = TypeVar("T") logger = logging.getLogger(__name__) class UserFactory(SQLAlchemyFactory[User]): email = Use(Faker().email) hashed_password = Use(lambda: get_password_hash(TESTS_USER_PASSWORD)) ================================================ FILE: docker-compose.yml ================================================ services: postgres_db: restart: unless-stopped image: postgres:18 volumes: - postgres_db:/var/lib/postgresql environment: - POSTGRES_DB=${DATABASE__DB} - POSTGRES_USER=${DATABASE__USERNAME} - POSTGRES_PASSWORD=${DATABASE__PASSWORD} env_file: - .env ports: - "${DATABASE__PORT}:5432" volumes: postgres_db: ================================================ FILE: init.sh ================================================ #!/bin/bash set -e echo "Run migrations" alembic upgrade head # Run whatever CMD was passed exec "$@" ================================================ FILE: pyproject.toml ================================================ [project] authors = [{ name = "admin", email = "admin@example.com" }] dependencies = [ "alembic>=1.18.3", "asyncpg>=0.31.0", "bcrypt>=5.0.0", "fastapi>=0.128.0", "prometheus-client>=0.24.1", "pydantic-settings>=2.12.0", "pydantic[email]>=2.12.5", "pyjwt>=2.11.0", "python-multipart>=0.0.22", "sqlalchemy[asyncio]>=2.0.46", ] description = "FastAPI project generated using minimal-fastapi-postgres-template." name = "app" requires-python = ">=3.14,<3.15" version = "0.1.0-alpha" [dependency-groups] dev = [ "coverage>=7.13.2", "freezegun>=1.5.5", "greenlet>=3.3.1", "httpx>=0.28.1", "mypy>=1.19.1", "polyfactory>=3.2.0", "pre-commit>=4.5.1", "pytest-asyncio>=1.3.0", "pytest-cov>=7.0.0", "pytest-xdist>=3.8.0", "pytest>=9.0.2", "ruff>=0.14.14", "uvicorn[standard]>=0.40.0", ] [tool.uv] package = false [build-system] build-backend = "hatchling.build" requires = ["hatchling"] [tool.pytest.ini_options] addopts = "-vv -n auto --cov --cov-report xml --cov-report term-missing --cov-fail-under=100" asyncio_default_test_loop_scope = "session" asyncio_mode = "auto" filterwarnings = [""] testpaths = ["app"] [tool.coverage.run] concurrency = ["greenlet"] omit = ["alembic/*", "app/tests/*", "conftest.py", "test_*.py"] source = ["app"] [tool.mypy] exclude = [".venv", "alembic"] files = "app/**" python_version = "3.14" strict = true [tool.ruff] target-version = "py314" [tool.ruff.lint] # pycodestyle, pyflakes, isort, pylint, pyupgrade ignore = ["E501"] select = ["E", "F", "I", "PL", "UP", "W"]