diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..470dc845 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,3 @@ +docs/ export-ignore +zensical.toml export-ignore +.github/ISSUE_TEMPLATE/ export-ignore diff --git a/.github/workflows/linting.yml b/.github/workflows/linting.yml index e12a747a..cf4670bd 100644 --- a/.github/workflows/linting.yml +++ b/.github/workflows/linting.yml @@ -28,7 +28,13 @@ jobs: - name: Ruff check # --no-sync skips uv run's implicit sync: the step above already installed # every member and extra, and skipping it keeps each step from re-resolving. - run: uv run --no-sync ruff check backend/src backend/tests backend/scripts backend/migrations cli/src cli/tests tools + run: uv run --no-sync ruff check backend/src backend/tests backend/scripts backend/migrations blueprint/tests - name: Ruff format - run: uv run --no-sync ruff format --check backend/src backend/tests backend/scripts backend/migrations cli/src cli/tests tools + run: uv run --no-sync ruff format --check backend/src backend/tests backend/scripts backend/migrations blueprint/tests + + - name: Wiring in sync + run: uv run --no-sync fastro sync --check + + - name: Blueprint lint + run: uv run --no-sync fastro blueprint lint diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 1c94f005..b0f469aa 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -31,10 +31,10 @@ jobs: ENVIRONMENT: local SECRET_KEY: test-secret-key-for-testing-only - - name: Pytest (cli) - run: cd cli && uv run --no-sync pytest + - name: Pytest (blueprint) + run: uv run --no-sync pytest blueprint/tests - removal-drills: + verify: runs-on: ubuntu-latest strategy: fail-fast: false @@ -48,6 +48,9 @@ jobs: - accounts-api-keys - accounts-rbac-tiers - accounts-cache-taskiq + - minimal + - standard + - full - everything steps: - uses: actions/checkout@v4 @@ -64,8 +67,5 @@ jobs: - name: Sync workspace run: uv sync --all-packages --all-extras --locked --python 3.11 - - name: Removal drill - run: uv run --no-sync python tools/removal_drill.py ${{ matrix.preset }} - env: - ENVIRONMENT: local - SECRET_KEY: test-secret-key-for-testing-only + - name: Verify + run: uv run --no-sync fastro blueprint verify ${{ matrix.preset }} diff --git a/.github/workflows/type-checking.yml b/.github/workflows/type-checking.yml index 56698fda..dae60fa6 100644 --- a/.github/workflows/type-checking.yml +++ b/.github/workflows/type-checking.yml @@ -29,14 +29,8 @@ jobs: ENVIRONMENT: local SECRET_KEY: test-secret-key-for-testing-only - - name: Mypy (cli) - run: cd cli && uv run --no-sync mypy -p cli - env: - ENVIRONMENT: local - SECRET_KEY: test-secret-key-for-testing-only - - - name: Mypy (tools) - run: uv run --no-sync mypy tools + - name: Mypy (blueprint tests) + run: uv run --no-sync mypy blueprint/tests env: ENVIRONMENT: local SECRET_KEY: test-secret-key-for-testing-only diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index e292631c..9cc1b795 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -46,13 +46,12 @@ repos: files: ^backend/(src|scripts|migrations|tests)/ types: [python] - - id: mypy_cli - name: Mypy (cli) + - id: fastro_sync_check + name: Wiring in sync (fastro) language: system - entry: bash -c 'cd cli && uv run --no-sync mypy -p cli' + entry: uv run --no-sync fastro sync --check pass_filenames: false - files: ^cli/src/ - types: [python] + files: ^(blueprint\.toml|fastro\.toml|pyproject\.toml|uv\.lock|backend/src/wiring/.*|backend/scripts/seeders\.py|backend/tests/wiring\.py)$ - id: unit_test name: Unit test diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 03de15b1..79d263ee 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,8 +24,13 @@ cd FastAPI-boilerplate uv sync --all-packages --all-extras ``` -`--all-packages` installs both workspace members, and `--all-extras` brings in the -dev tools: a plain `uv sync` leaves you without ruff, mypy or pytest. +`--all-packages` installs the backend, the workspace's one member, and `--all-extras` +brings in the dev tools: a plain `uv sync` leaves you without ruff, mypy or pytest. + +The sync also installs fastro, the CLI that generates projects from this blueprint +and checks it. The root `pyproject.toml` pins fastro to one commit in its `dev` +group. `uv.lock` is at lock revision 5, which uv 0.13.8 wrote, so use uv 0.13.8 or +newer. ### Activating the Virtual Environment @@ -85,6 +90,7 @@ It helps in identifying simple issues before submission to code review. By runni 1. **Committing Your Changes**: After making your changes, use `git commit -am 'Add some fooBar'` to commit them. Pre-commit will run automatically on your files when you commit, ensuring that they meet the required standards. Note: If pre-commit identifies issues, it may block your commit. Fix these issues and commit again. This ensures that all contributions are of high quality. + A commit that touches `blueprint.toml`, `fastro.toml`, a wiring file fastro generates, the root `pyproject.toml`, or `uv.lock` also runs `uv run --no-sync fastro sync --check`, which fails when the wiring in the commit differs from what fastro generates. Run `uv run --no-sync fastro sync` to regenerate the wiring, then commit the result. 1. **Pushing Changes and Creating Pull Request**: Push your changes to the branch using `git push origin feature/fooBar`. Visit your fork on GitHub and create a new Pull Request to the main repository. diff --git a/README.md b/README.md index d0af0a05..b58ae108 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,13 @@ -

Fastro · The Benav Labs FastAPI Boilerplate

+

FastAPI-boilerplate by Benav Labs

- Batteries-included FastAPI starter - vertical-slice modules, swappable infrastructure, plugin-ready CLI. + Batteries-included FastAPI starter - vertical-slice modules, swappable infrastructure, compose files written by fastro.

- Fastro - open-source FastAPI boilerplate with auth, CRUD, jobs, caching and rate-limits + FastAPI-boilerplate - open source, with auth, CRUD, jobs, caching and rate-limits

@@ -47,8 +47,8 @@ * **SQLAdmin**-based admin panel (optional, env-toggled) * [Taskiq](https://taskiq-python.github.io/) workers (Redis or RabbitMQ broker) * Redis or Memcached caching (`@cache` decorator + provider API) -* **Plugin-ready `bp` CLI** - generate compose files, audit env, mount third-party command/feature plugins -* Docker Compose for local / prod / nginx-fronted (generated by the CLI) +* **fastro** - generates the compose files and audits the env +* Docker Compose for local / prod / nginx-fronted (generated by fastro) * Runs on any Postgres - the bundled container, or serverless via [Neon](https://neon.com) ([guide](https://benavlabs.github.io/FastAPI-boilerplate/user-guide/database/neon/)) ## Why and When to use it @@ -57,7 +57,7 @@ * A pragmatic starter with auth, CRUD, jobs, caching and rate-limits * **Sensible defaults** with the freedom to opt-out of modules -* **A foundation that grows** - vertical-slice modules + a plugin-aware CLI for code generators +* **A foundation that grows** - vertical-slice modules, one folder per domain * **Docs over boilerplate** in this README - depth lives on the [docs site](https://benavlabs.github.io/FastAPI-boilerplate/) > **Not a fit** if you need a monorepo microservices scaffold - [see the docs](https://benavlabs.github.io/FastAPI-boilerplate/user-guide/project-structure/) for pointers. @@ -72,20 +72,20 @@ * **Queues**: [Taskiq workers](https://benavlabs.github.io/FastAPI-boilerplate/user-guide/background-tasks/) (Redis or RabbitMQ) * **Rate limits**: [per-tier + per-path rules](https://benavlabs.github.io/FastAPI-boilerplate/user-guide/rate-limiting/) * **Admin**: [SQLAdmin views](https://benavlabs.github.io/FastAPI-boilerplate/user-guide/admin-panel/) (optional, env-toggled) -* **CLI**: [`bp` tool](https://benavlabs.github.io/FastAPI-boilerplate/cli/) for compose scaffolding, env audits, and plugin extensions +* **fastro**: compose scaffolding and env audits -## Fastro vs FastroAI +## FastAPI-boilerplate vs FastroAI -This boilerplate - **Fastro** - is the free, open-source **foundation**: everything you need for a production FastAPI backend. **[FastroAI](https://fastro.ai)** is the paid template built on the same foundation for shipping a **complete SaaS** - Stripe billing (subscriptions, credits, discounts), entitlements, transactional email, and a frontend, all wired together. Building an **AI** product? The PydanticAI agent layer is included too - but every paid feature fits a regular SaaS just as well. +**FastAPI-boilerplate** is the free, open-source **foundation**: everything you need for a production FastAPI backend. **[FastroAI](https://fastro.ai)** is the paid template built on the same foundation for shipping a **complete SaaS** - Stripe billing (subscriptions, credits, discounts), entitlements, transactional email, and a frontend, all wired together. Building an **AI** product? The PydanticAI agent layer is included too - but every paid feature fits a regular SaaS just as well. -| | **Fastro** (this repo · free) | **FastroAI** (paid) | +| | **FastAPI-boilerplate** (this repo · free) | **FastroAI** (paid) | |---|:---:|:---:| | FastAPI + SQLAlchemy 2.0, Pydantic v2 | ✓ | ✓ | | Auth - sessions, OAuth, API keys | ✓ | ✓ **+ JWT** | | FastCRUD · SQLAdmin · Alembic | ✓ | ✓ | | Caching · rate limiting · Taskiq jobs | ✓ | ✓ | | Docker (local / prod / nginx) | ✓ | ✓ | -| `bp` CLI - scaffolding, env audit, plugins | ✓ | | +| fastro - compose scaffolding, env audit | ✓ | | | **Payments** - Stripe: subscriptions, credits, discounts, webhooks | | ✓ | | **Entitlements** - feature gating by plan/tier | | ✓ | | **Transactional email** & notifications | | ✓ | @@ -98,27 +98,25 @@ This boilerplate - **Fastro** - is the free, open-source **foundation**: everyth - FastroAI - the complete SaaS template: payments, entitlements, email, frontend and AI on top of Fastro + FastroAI - the complete SaaS template: payments, entitlements, email, frontend and AI on top of FastAPI-boilerplate

-**Stick with Fastro** if you want a clean, hackable FastAPI backend to build on. +**Stick with FastAPI-boilerplate** if you want a clean, hackable FastAPI backend to build on. **[Get FastroAI →](https://fastro.ai)** if you're shipping a SaaS - AI or not - and want billing, entitlements, email, auth, and a frontend ready out of the box. ## Repo Layout -This is a [uv workspace](https://docs.astral.sh/uv/concepts/projects/workspaces/) with two members. One venv at the root covers both. +This is a [uv workspace](https://docs.astral.sh/uv/concepts/projects/workspaces/) with one member, `backend/`. One venv at the root holds it and fastro. ```text fastapi-boilerplate/ ├── pyproject.toml # workspace root (uv workspace metadata) -├── backend/ # the deployable application -│ ├── src/ # interfaces/, infrastructure/, modules/ -│ ├── pyproject.toml -│ └── Dockerfile # multi-stage: dev / migrate / prod -└── cli/ # `bp` - developer/operator tool (never ships in prod) - └── src/cli/ +└── backend/ # the deployable application + ├── src/ # interfaces/, infrastructure/, modules/ + ├── pyproject.toml + └── Dockerfile # multi-stage: dev / migrate / prod ``` ## Quickstart @@ -126,23 +124,23 @@ fastapi-boilerplate/ ```bash git clone https://github.com//FastAPI-boilerplate cd FastAPI-boilerplate -uv sync --all-packages --all-extras # one venv at the root, both members installed +uv sync --all-packages --all-extras # one venv at the root: the backend, plus fastro ``` Generate a compose file for the deployment shape you want: ```bash -uv run --no-sync bp deploy generate local # hot-reload dev stack -# or: uv run --no-sync bp deploy generate prod # production single-host -# or: uv run --no-sync bp deploy generate nginx # production behind nginx +uv run --no-sync fastro make deploy local # hot-reload dev stack +# or: uv run --no-sync fastro make deploy prod # production single-host +# or: uv run --no-sync fastro make deploy nginx # production behind nginx ``` -Configure your env (the CLI helps with secrets and validation): +Configure your env (fastro helps with secrets and validation): ```bash cp backend/.env.example backend/.env -uv run --no-sync bp env gen-secret # print a fresh SECRET_KEY -uv run --no-sync bp env validate # audit .env against the production validator +uv run --no-sync fastro env secret # print a fresh SECRET_KEY +uv run --no-sync fastro env validate # audit .env against the production validator ``` Bring it up: @@ -168,22 +166,19 @@ uv run --no-sync taskiq worker src.infrastructure.taskiq.worker:default_broker ```bash # generate a fresh production-ready compose file -uv run --no-sync bp deploy generate prod --workers 8 +uv run --no-sync fastro make deploy prod --workers 8 # audit your .env against the production security validator -uv run --no-sync bp env validate +uv run --no-sync fastro env validate # run Alembic migrations cd backend && uv run --no-sync alembic revision --autogenerate -m "" && uv run --no-sync alembic upgrade head # run tests cd backend && uv run --no-sync pytest - -# install bp as a global tool (optional) -uv tool install --editable ./cli ``` -More examples (superuser creation, tiers, rate limits, admin usage, plugin authoring) in the [docs](https://benavlabs.github.io/FastAPI-boilerplate/). +More examples (superuser creation, tiers, rate limits, admin usage) in the [docs](https://benavlabs.github.io/FastAPI-boilerplate/). ## Sponsors diff --git a/backend/.env.example b/backend/.env.example index 03b82981..2263cf62 100644 --- a/backend/.env.example +++ b/backend/.env.example @@ -23,7 +23,7 @@ POSTGRES_ASYNC_PREFIX=postgresql+asyncpg:// # CREATE_TABLES_ON_STARTUP=true # Hosted / serverless Postgres (Neon, RDS, Cloud SQL, ...): DATABASE_URL overrides -# every POSTGRES_* value above. Mind the asyncpg spelling — the driver prefix is +# every POSTGRES_* value above. Mind the asyncpg spelling: the driver prefix is # postgresql+asyncpg:// and TLS is ssl=require, NOT libpq's sslmode=require. # Guide: https://benavlabs.github.io/FastAPI-boilerplate/user-guide/database/neon/ # DATABASE_URL=postgresql+asyncpg://user:password@host.example.com/dbname?ssl=require @@ -40,14 +40,12 @@ POSTGRES_POOL_RECYCLE=-1 # =================================== # Cache Configuration # =================================== +# @fastro if=cache CACHE_ENABLED=true # Options: memcached, redis +# @fastro option=cache.backend CACHE_BACKEND=redis -# Client-side cache settings -CLIENT_CACHE_ENABLED=true -CLIENT_CACHE_MAX_AGE=60 - # Cache Memcached settings (when using CACHE_BACKEND=memcached) CACHE_MEMCACHED_HOST=localhost CACHE_MEMCACHED_PORT=11211 @@ -64,18 +62,29 @@ CACHE_REDIS_PASSWORD= CACHE_REDIS_CONNECT_TIMEOUT=5 CACHE_REDIS_POOL_SIZE=10 +# Before production: set CACHE_REDIS_PASSWORD, and keep CACHE_REDIS_DB to this service +# alone, so a flush here leaves every other service's keys where they were. + # =================================== # Rate Limiting Configuration # =================================== -# Provided by crudauth (Redis-backed). Limits are resolved per request from the +# @fastro if=ratelimit +# The per-caller throttle on the API routes. Limits are resolved per request from the # user's tier and path, falling back to the defaults below. RATE_LIMITER_ENABLED=true +DEFAULT_RATE_LIMIT_LIMIT=100 +DEFAULT_RATE_LIMIT_PERIOD=60 + +# =================================== +# Rate Limiter Store +# =================================== +# @fastro if=accounts +# Where the counters live: the login lockout keeps its own here, and the API throttle, +# where it is selected, shares them. # redis (default), database or memory. Memory counters are per process, so each worker # counts a login lockout on its own; database keeps them in two tables of this project's # database, which every worker shares without a Redis. RATE_LIMITER_BACKEND=redis -DEFAULT_RATE_LIMIT_LIMIT=100 -DEFAULT_RATE_LIMIT_PERIOD=60 # Rate Limiter Redis settings # Uses DB 1 by default to separate from cache (which uses DB 0) @@ -88,6 +97,9 @@ RATE_LIMITER_REDIS_PASSWORD= RATE_LIMITER_REDIS_CONNECT_TIMEOUT=5 RATE_LIMITER_REDIS_POOL_SIZE=10 +# Before production: set RATE_LIMITER_REDIS_PASSWORD, and keep RATE_LIMITER_REDIS_DB to +# the counters alone. + # =================================== # Email Configuration # =================================== @@ -117,6 +129,7 @@ EMAIL_SMTP_TIMEOUT_SECONDS=10 # =================================== # API Keys # =================================== +# @fastro if=api_keys # How many days of key usage rows to keep. Each row carries the caller's address and # user agent, one row per request. 0 keeps every row and prunes nothing, and a value # below 0 is refused at startup. The analytics @@ -131,7 +144,9 @@ KEY_USAGE_RETENTION_DAYS=90 # =================================== # Taskiq Configuration # =================================== +# @fastro if=taskiq # Broker type: 'redis' or 'rabbitmq' +# @fastro option=taskiq.broker TASKIQ_BROKER_TYPE=redis # How many times a task labelled retry_on_error=True runs in all, the first attempt @@ -158,6 +173,9 @@ TASKIQ_RABBITMQ_USER=guest TASKIQ_RABBITMQ_PASSWORD=guest TASKIQ_RABBITMQ_VHOST=/ +# Before production: give RabbitMQ credentials of the project's own rather than +# guest/guest, and keep TASKIQ_REDIS_DB to the broker alone. + # =================================== # Web Server Configuration @@ -177,12 +195,22 @@ CORS_ALLOW_HEADERS=* GZIP_ENABLED=true GZIP_MINIMUM_SIZE=1000 +# Client-side caching: the Cache-Control headers responses carry +CLIENT_CACHE_ENABLED=true +CLIENT_CACHE_MAX_AGE=60 + +# Which peers uvicorn accepts X-Forwarded-For and X-Forwarded-Proto from. Read by +# uvicorn, not by the app, and it decides what request.client and the access logs +# say. Name your proxy's address or subnet; a wildcard lets any client claim any +# address. Leave unset when nothing sits in front of the app. +# FORWARDED_ALLOW_IPS=172.31.240.0/24 + # API documentation settings ENABLE_DOCS_IN_PRODUCTION=false OPENAPI_PREFIX= # =================================== -# Authentication & Security +# Security # =================================== SECRET_KEY=insecure-secret-key-change-this-in-production @@ -190,6 +218,10 @@ SECRET_KEY=insecure-secret-key-change-this-in-production # Automatically validates security settings in production environments PRODUCTION_SECURITY_VALIDATION_ENABLED=true +# =================================== +# Authentication & Security +# =================================== +# @fastro if=accounts # Session Management SESSION_TIMEOUT_MINUTES=30 SESSION_CLEANUP_INTERVAL_MINUTES=15 @@ -217,10 +249,18 @@ SESSION_SECURE_COOKIES=true # workers share them with no Redis; it adds the crudauth_store and crudauth_counters # tables, which need one migration. SESSION_BACKEND=redis -# Sessions, CSRF tokens, OAuth state and login lockout counters use the cache Redis -# connection (CACHE_REDIS_*) on their own DB, so a cache flush doesn't log everyone out. +# Sessions, CSRF tokens, OAuth state and login lockout counters keep their own DB on the +# session Redis connection, so a cache flush doesn't log everyone out. SESSION_REDIS_DB=2 -# Optional full URL for a dedicated session Redis; overrides the cache connection and SESSION_REDIS_DB. +# The connection itself. Left unset, each of these reads the cache's CACHE_REDIS_* where the +# cache is selected, and localhost:6379 with no password otherwise, which is not the compose +# stack's Redis. Set them when there is no cache, or to point sessions somewhere else. Setting +# SESSION_REDIS_PASSWORD overrides the cache's password rather than adding to it. +# SESSION_REDIS_HOST=redis +# SESSION_REDIS_PORT=6379 +# SESSION_REDIS_PASSWORD= +# Optional full URL for a dedicated session Redis; overrides the connection above and +# SESSION_REDIS_DB. # SESSION_REDIS_URL=rediss://user:password@sessions-redis.example.com:6380/0 # CSRF Protection @@ -231,12 +271,6 @@ CSRF_ENABLED=true # IP for login lockout. 0 = direct (socket peer); set 1 behind a single nginx/Caddy. TRUSTED_PROXY_HOPS=0 -# Which peers uvicorn accepts X-Forwarded-For and X-Forwarded-Proto from. Read by -# uvicorn, not by the app, and it decides what request.client and the access logs -# say. Name your proxy's address or subnet; a wildcard lets any client claim any -# address. Leave unset when nothing sits in front of the app. -# FORWARDED_ALLOW_IPS=172.31.240.0/24 - # Password policy (crudauth applies this to every password-writing path) PASSWORD_MIN_LENGTH=8 PASSWORD_REQUIRE_UPPERCASE=true @@ -244,17 +278,24 @@ PASSWORD_REQUIRE_LOWERCASE=true PASSWORD_REQUIRE_DIGIT=true PASSWORD_REQUIRE_SPECIAL=true +# Before production: read the session timeouts above against what you need, keep +# SESSION_REDIS_DB to the session store alone, and make sure the session Redis has a +# password, whether it comes from the cache's or from SESSION_REDIS_PASSWORD. + # =================================== # Admin Interface (SQLAdmin) # =================================== -# Enable/disable the admin interface -ADMIN_ENABLED=true +# @fastro if=admin +# The panel is off until a project asks for it. Set this to true, with credentials of your +# own below, to serve it. +ADMIN_ENABLED=false # Where the panel is mounted; the admin session cookie is scoped to this path ADMIN_BASE_URL=/admin # =================================== # OAuth Configuration # =================================== +# @fastro if=accounts OAUTH_REDIRECT_BASE_URL=http://localhost:8000 # Google OAuth @@ -309,15 +350,25 @@ API_TERMS_OF_SERVICE= # DOCS_URL=/docs # REDOC_URL=/redoc +# =================================== +# Tiers +# =================================== +# @fastro if=tiers +# The tier the initial-data step creates, if it isn't there already. +DEFAULT_TIER_NAME=free + # =================================== # Initial Setup Configuration # =================================== +# @fastro if=accounts # Admin user settings (for initial setup) ADMIN_NAME=Admin User ADMIN_EMAIL=admin@example.com ADMIN_USERNAME=admin ADMIN_PASSWORD=Change-Me-Now-1! +# Before production: set ADMIN_USERNAME and ADMIN_PASSWORD to credentials of your own. + # =================================== # Production Security Checklist # =================================== @@ -325,16 +376,6 @@ ADMIN_PASSWORD=Change-Me-Now-1! # 1. Generate strong SECRET_KEY with high entropy # Example: python -c "import secrets; print(secrets.token_urlsafe(64))" # 2. Set unique database passwords (avoid defaults like 'postgres') -# 3. Set Redis passwords for all instances: -# - CACHE_REDIS_PASSWORD (for cache operations and sessions) -# - RATE_LIMITER_REDIS_PASSWORD (for rate limiting) -# 4. Use separate Redis instances/databases for different services: -# - Cache: CACHE_REDIS_DB=0 (default) -# - Rate Limiter: RATE_LIMITER_REDIS_DB=1 (default) -# - Sessions: SESSION_REDIS_DB=2 (default) -# - Taskiq: TASKIQ_REDIS_DB=3 (default) -# 5. Restrict CORS_ORIGINS to specific domains (avoid *) -# 6. Set strong admin credentials (ADMIN_USERNAME, ADMIN_PASSWORD) -# 7. Review session timeout settings for your security requirements -# 8. Set ENVIRONMENT=production to enable security validation -# 9. Configure RabbitMQ with strong credentials (avoid guest/guest) +# 3. Restrict CORS_ORIGINS to specific domains (avoid *) +# 4. Set ENVIRONMENT=production to enable security validation +# Each selected feature carries its own checks beside the settings they are about. diff --git a/backend/Dockerfile b/backend/Dockerfile index 7636160b..a38d1a23 100644 --- a/backend/Dockerfile +++ b/backend/Dockerfile @@ -10,7 +10,6 @@ COPY --from=ghcr.io/astral-sh/uv:0.9.9 /uv /usr/local/bin/uv # Copy the workspace manifests and uv.lock for deterministic export COPY pyproject.toml uv.lock ./ COPY backend/pyproject.toml backend/pyproject.toml -COPY cli/pyproject.toml cli/pyproject.toml # Export from lock file (not re-resolving dependencies!) # Filter out the local project line and keep only external dependencies diff --git a/backend/pyproject.toml b/backend/pyproject.toml index 2f016c69..27fad392 100644 --- a/backend/pyproject.toml +++ b/backend/pyproject.toml @@ -12,19 +12,15 @@ readme = "README.md" requires-python = ">=3.11" dependencies = [ "aiomcache>=0.8.2", - "aiosqlite>=0.21.0", "alembic>=1.16.4", "anyio>=4.15.1", "asyncpg>=0.30.0", "crudauth[all]>=0.8.2,<0.9.0", "cryptography>=42.0.0", - "faker>=37.1.0", - "fastapi[standard]>=0.115.8", + "fastapi[standard]>=0.115.8,<0.140.7", "fastcrud>=0.21.0", "greenlet>=3.1.1", - "httpx>=0.28.1", "itsdangerous>=2.2.0", - "jinja2>=3.1.6", "pydantic>=2.10.6", "pydantic-settings>=2.14.2", "redis>=6.1.0", @@ -48,6 +44,9 @@ dev = [ "pytest-xdist[psutil]>=3.8.0", "taskiq[reload]>=0.11.20", "pre-commit>=4.0.0", + "faker>=37.1.0", + "httpx>=0.28.1", + "jinja2>=3.1.6", ] [tool.setuptools.packages.find] diff --git a/backend/scripts/baseline.py b/backend/scripts/baseline.py new file mode 100644 index 00000000..cc5dbb91 --- /dev/null +++ b/backend/scripts/baseline.py @@ -0,0 +1,182 @@ +"""Write this project's baseline migration, and check that it recreates the models. + +Run it once, from ``backend/``: + + python -m scripts.baseline + python -m scripts.baseline --check + +It starts a throwaway Postgres, autogenerates the revision against it, applies it to that +empty database, and compares the tables and indexes it created with the ones the models +declare. The revision is left in ``migrations/versions/`` to be committed. ``--check`` deletes +it again, so a project can be checked without gaining a migration. + +A project that already has a revision is refused: a baseline is a project's first migration, +and autogenerating one against an empty database beside a history writes a revision that +recreates what the history already created. +""" + +import argparse +import asyncio +import os +import subprocess +import sys +from pathlib import Path + +backend_dir = Path(__file__).parent.parent +sys.path.append(str(backend_dir)) + +from sqlalchemy import Connection, inspect # noqa: E402 +from testcontainers.postgres import PostgresContainer # noqa: E402 + +from src.infrastructure.database.registry import import_models # noqa: E402 +from src.infrastructure.database.session import Base, build_engine # noqa: E402 + +IMAGE = "postgres:16-alpine" + +MESSAGE = "baseline" +"""What the revision is named after, which alembic turns into the slug its file is named with.""" + +VERSIONS = Path("migrations/versions") + +EXPOSED_PORT = 5432 + + +class BaselineError(Exception): + """What went wrong, as the line the script exits with.""" + + +def alembic(*arguments: str) -> subprocess.CompletedProcess[str]: + return subprocess.run([sys.executable, "-m", "alembic", *arguments], capture_output=True, text=True) + + +def connection_settings(postgres: PostgresContainer) -> dict[str, str]: + """The container, as the settings an alembic run reads the database from. + + ``DATABASE_URL`` is blanked because it wins over these: a configured one would send the + autogenerate at the database the project really uses. + """ + return { + "POSTGRES_SERVER": postgres.get_container_host_ip(), + "POSTGRES_PORT": str(postgres.get_exposed_port(EXPOSED_PORT)), + "POSTGRES_USER": postgres.username, + "POSTGRES_PASSWORD": postgres.password, + "POSTGRES_DB": postgres.dbname, + "DATABASE_URL": "", + } + + +def database_url(postgres: PostgresContainer) -> str: + details = connection_settings(postgres) + + return ( + f"postgresql+asyncpg://{details['POSTGRES_USER']}:{details['POSTGRES_PASSWORD']}" + f"@{details['POSTGRES_SERVER']}:{details['POSTGRES_PORT']}/{details['POSTGRES_DB']}" + ) + + +def declared_schema() -> dict[str, list[str]]: + """The tables and named indexes the models declare, beside the one alembic keeps itself.""" + import_models() + declared = { + name: sorted(str(index.name) for index in table.indexes if index.name is not None) + for name, table in Base.metadata.tables.items() + } + declared["alembic_version"] = [] + + return declared + + +def _reflected(connection: Connection) -> dict[str, list[str]]: + """What is really there: an index a constraint brought with it is not counted twice.""" + inspector = inspect(connection) + + def indexes(table: str) -> list[str]: + found = inspector.get_indexes(table) + named = [index["name"] for index in found if not index.get("duplicates_constraint")] + + return sorted(name for name in named if name is not None) + + return {table: indexes(table) for table in sorted(inspector.get_table_names())} + + +async def created_schema(url: str) -> dict[str, list[str]]: + """What applying the baseline left in the database.""" + engine = build_engine(url) + try: + async with engine.connect() as connection: + return await connection.run_sync(_reflected) + finally: + await engine.dispose() + + +def _revisions() -> list[Path]: + return sorted(VERSIONS.glob("*.py")) + + +def write_revision() -> Path: + """Autogenerate the baseline, and return the one revision it wrote.""" + before = set(_revisions()) + autogenerated = alembic("revision", "--autogenerate", "-m", MESSAGE) + if autogenerated.returncode != 0: + raise BaselineError("autogenerate failed:\n" + autogenerated.stdout + autogenerated.stderr) + + written = [path for path in _revisions() if path not in before] + if len(written) != 1: + raise BaselineError(f"autogenerate wrote {len(written)} revisions, and a baseline is one") + + if not written[0].name.endswith(f"_{MESSAGE}.py"): + raise BaselineError(f"autogenerate wrote {written[0].name}, which is not the baseline") + + return written[0] + + +def write_baseline(url: str, *, keeping: bool) -> str: + """Write the baseline and apply it, and say what it recreated.""" + declared = declared_schema() + revision = write_revision() + try: + applied = alembic("upgrade", "head") + if applied.returncode != 0: + raise BaselineError("upgrade failed:\n" + applied.stdout + applied.stderr) + + created = asyncio.run(created_schema(url)) + if created != declared: + raise BaselineError(f"the baseline left {created}, while the models declare {declared}") + finally: + if not keeping: + revision.unlink(missing_ok=True) + + indexes = sum(len(names) for names in declared.values()) + + return f"a baseline of {len(declared) - 1} tables and {indexes} indexes applies to an empty database" + + +def _refuse_a_history() -> None: + history = _revisions() + if history: + names = ", ".join(path.name for path in history) + + raise BaselineError(f"this project already has {names}, and a baseline is a project's first revision") + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(description="Write this project's baseline migration against a throwaway database.") + parser.add_argument("--check", action="store_true", help="delete the revision afterwards, leaving the tree as it was") + arguments = parser.parse_args(argv) + + os.environ["TESTCONTAINERS_RYUK_DISABLED"] = "true" + try: + _refuse_a_history() + with PostgresContainer(IMAGE) as postgres: + os.environ.update(connection_settings(postgres)) + print(write_baseline(database_url(postgres), keeping=not arguments.check)) + except BaselineError as error: + print(error, file=sys.stderr) + + return 1 + + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/backend/scripts/gen_secret.py b/backend/scripts/gen_secret.py new file mode 100644 index 00000000..4a67b78a --- /dev/null +++ b/backend/scripts/gen_secret.py @@ -0,0 +1,93 @@ +"""Print a secret key the project's own rules accept. + +Run it from ``backend/``: + + python -m scripts.gen_secret [--bytes 32] + +``SECRET_KEY`` signs the session cookies, the CSRF tokens and the admin panel's session, +and production refuses a key its rules read as something a person typed. A draw of random +bytes can land on such a key: about one hex key in twelve million runs through eight +consecutive digits. So this draws again while the rules refuse what it drew, and prints the +last draw either way, which keeps it from drawing for ever. + +It reads no configuration and touches no database, so it works before there is a ``.env`` +to put the key in. The rules are loaded from their own file rather than through +``src.infrastructure.security``, whose import configures logging and writes a line to +stdout: the key is meant to be piped, and a log line would be piped with it. +""" + +import argparse +import importlib.util +import secrets +from pathlib import Path +from types import ModuleType + +RULES_PATH = Path(__file__).parent.parent / "src" / "infrastructure" / "security" / "secret_key.py" +"""The project's own secret-key rules, the ones production refuses a key by.""" + + +def _rules() -> ModuleType: + """The rules module, loaded from its file so nothing around it is imported.""" + spec = importlib.util.spec_from_file_location("secret_key_rules", RULES_PATH) + if spec is None or spec.loader is None: + raise ImportError(f"No secret-key rules at {RULES_PATH}.") + + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + + return module + + +is_weak_secret_key = _rules().is_weak_secret_key + +DRAWS = 8 +"""How many keys are drawn at most; the last one is printed whatever the rules say.""" + +DEFAULT_BYTES = 32 +SMALLEST_BYTES = 16 +LARGEST_BYTES = 128 + + +def generate(byte_count: int = DEFAULT_BYTES) -> str: + """A hex key of ``byte_count`` random bytes, redrawn while the rules refuse it.""" + candidate = secrets.token_hex(byte_count) + for _ in range(DRAWS - 1): + if not is_weak_secret_key(candidate): + break + candidate = secrets.token_hex(byte_count) + + return candidate + + +def parse_byte_count(value: str) -> int: + """``value`` as a byte count the key may be drawn from. + + Raises: + argparse.ArgumentTypeError: it isn't a number, or sits outside the range. + """ + try: + count = int(value) + except ValueError as error: + raise argparse.ArgumentTypeError(f"{value!r} is not a number of bytes.") from error + + if not SMALLEST_BYTES <= count <= LARGEST_BYTES: + raise argparse.ArgumentTypeError(f"{count} is outside {SMALLEST_BYTES} to {LARGEST_BYTES}.") + + return count + + +def main() -> None: + parser = argparse.ArgumentParser(description="Print a secret key suitable for SECRET_KEY.") + parser.add_argument( + "--bytes", + dest="byte_count", + type=parse_byte_count, + default=DEFAULT_BYTES, + help=f"Random bytes to draw, {SMALLEST_BYTES} to {LARGEST_BYTES}; the hex output is twice as long.", + ) + + print(generate(parser.parse_args().byte_count)) + + +if __name__ == "__main__": + main() diff --git a/backend/scripts/seeders.py b/backend/scripts/seeders.py index 80df9ee7..e3beb0bd 100644 --- a/backend/scripts/seeders.py +++ b/backend/scripts/seeders.py @@ -1,6 +1,7 @@ """The initial-data steps ``scripts/setup_initial_data.py`` runs, in order. -Written by the generator in `tools/removal_drill.py`, which a test compares this file against. +Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change +fastro.toml (or [app] in it, for your own code) and run `fastro sync`. """ from collections.abc import Awaitable, Callable diff --git a/backend/scripts/validate_env.py b/backend/scripts/validate_env.py new file mode 100644 index 00000000..b1a1bccf --- /dev/null +++ b/backend/scripts/validate_env.py @@ -0,0 +1,61 @@ +"""Audit this environment the way production would. + +Run it from ``backend/``: + + python -m scripts.validate_env + +The settings are audited as a copy whose ``ENVIRONMENT`` reads ``production``, whatever the +configured one says, so a development or staging configuration is held to the gate that +stops a production boot, and a finding that names an environment names the one it was +checked for. + +It exits 1 when anything critical is found, and 0 otherwise. Warnings are printed and +exit 0: they are worth reading, not worth refusing a boot over. +""" + +import sys +from pathlib import Path + +backend_dir = Path(__file__).parent.parent +sys.path.append(str(backend_dir)) + +from src.infrastructure.config.settings import EnvironmentOption, get_settings # noqa: E402 +from src.infrastructure.security.production_validator import ProductionSecurityValidator # noqa: E402 + + +def audit() -> tuple[list[str], list[str]]: + """The critical findings and the warnings, for these settings read as production.""" + as_production = get_settings().model_copy(update={"ENVIRONMENT": EnvironmentOption.PRODUCTION}) + + return ProductionSecurityValidator(as_production).audit() + + +def report(critical: list[str], warnings: list[str]) -> None: + """Print what the audit found, grouped, or say that it found nothing.""" + if not critical and not warnings: + print("No issues found. Configuration would pass production validation.") + + return + + if critical: + print(f"Critical ({len(critical)}):") + for finding in critical: + print(f" • {finding}") + + if warnings: + if critical: + print() + print(f"Warnings ({len(warnings)}):") + for finding in warnings: + print(f" • {finding}") + + +def main() -> int: + critical, warnings = audit() + report(critical, warnings) + + return 1 if critical else 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/backend/src/infrastructure/auth/settings.py b/backend/src/infrastructure/auth/settings.py index 7099d4b6..fdd21507 100644 --- a/backend/src/infrastructure/auth/settings.py +++ b/backend/src/infrastructure/auth/settings.py @@ -1,14 +1,13 @@ """Settings for the accounts feature: users, sessions, CSRF, login lockout, OAuth.""" from pydantic import AliasChoices, Field -from pydantic_settings import BaseSettings -from ..config.base import config +from ..config.base import EnvSettings from ..config.enums import RateLimiterBackend, SessionBackend from ..redis import redis_url -class AuthSettings(BaseSettings): +class AuthSettings(EnvSettings): """Authentication-related settings. Sessions have their own Redis connection. Each of its fields falls back to the @@ -16,54 +15,54 @@ class AuthSettings(BaseSettings): ``CACHE_REDIS_*`` keeps working. """ - SESSION_TIMEOUT_MINUTES: int = config("SESSION_TIMEOUT_MINUTES", default=30, cast=int) - SESSION_ABSOLUTE_TIMEOUT_HOURS: int | None = config("SESSION_ABSOLUTE_TIMEOUT_HOURS", default=None, cast=int) - FRESH_SIGN_IN_SECONDS: int | None = config("FRESH_SIGN_IN_SECONDS", default=None, cast=int) + SESSION_TIMEOUT_MINUTES: int = 30 + SESSION_ABSOLUTE_TIMEOUT_HOURS: int | None = None + FRESH_SIGN_IN_SECONDS: int | None = None - LOGIN_MAX_ATTEMPTS: int = config("LOGIN_MAX_ATTEMPTS", default=5, cast=int) - LOGIN_ATTEMPT_WINDOW_SECONDS: int = config("LOGIN_ATTEMPT_WINDOW_SECONDS", default=900, cast=int) - LOGIN_LOCKOUT_BASE_SECONDS: int = config("LOGIN_LOCKOUT_BASE_SECONDS", default=300, cast=int) - LOGIN_LOCKOUT_MAX_SECONDS: int = config("LOGIN_LOCKOUT_MAX_SECONDS", default=3600, cast=int) - SESSION_CLEANUP_INTERVAL_MINUTES: int = config("SESSION_CLEANUP_INTERVAL_MINUTES", default=15, cast=int) - MAX_SESSIONS_PER_USER: int = config("MAX_SESSIONS_PER_USER", default=5, cast=int) - SESSION_SECURE_COOKIES: bool = config("SESSION_SECURE_COOKIES", default=True, cast=bool) - SESSION_BACKEND: str = config("SESSION_BACKEND", default=SessionBackend.REDIS.value) + LOGIN_MAX_ATTEMPTS: int = 5 + LOGIN_ATTEMPT_WINDOW_SECONDS: int = 900 + LOGIN_LOCKOUT_BASE_SECONDS: int = 300 + LOGIN_LOCKOUT_MAX_SECONDS: int = 3600 + SESSION_CLEANUP_INTERVAL_MINUTES: int = 15 + MAX_SESSIONS_PER_USER: int = 5 + SESSION_SECURE_COOKIES: bool = True + SESSION_BACKEND: str = SessionBackend.REDIS.value - SESSION_REDIS_DB: int = config("SESSION_REDIS_DB", default=2, cast=int) + SESSION_REDIS_DB: int = 2 SESSION_REDIS_URL_OVERRIDE: str | None = Field( - default=config("SESSION_REDIS_URL", default=None), + default=None, validation_alias="SESSION_REDIS_URL", ) - CSRF_ENABLED: bool = config("CSRF_ENABLED", default=True, cast=bool) + CSRF_ENABLED: bool = True # Number of trusted reverse proxies in front of the app. crudauth resolves the # client IP for login lockout from the last hop of X-Forwarded-For; 0 = the socket # peer (no proxy). Set to 1 behind a single nginx/Caddy, 2 if Cloudflare is also in front. - TRUSTED_PROXY_HOPS: int = config("TRUSTED_PROXY_HOPS", default=0, cast=int) + TRUSTED_PROXY_HOPS: int = 0 - PASSWORD_MIN_LENGTH: int = config("PASSWORD_MIN_LENGTH", default=8, cast=int) - PASSWORD_REQUIRE_UPPERCASE: bool = config("PASSWORD_REQUIRE_UPPERCASE", default=True, cast=bool) - PASSWORD_REQUIRE_LOWERCASE: bool = config("PASSWORD_REQUIRE_LOWERCASE", default=True, cast=bool) - PASSWORD_REQUIRE_DIGIT: bool = config("PASSWORD_REQUIRE_DIGIT", default=True, cast=bool) - PASSWORD_REQUIRE_SPECIAL: bool = config("PASSWORD_REQUIRE_SPECIAL", default=True, cast=bool) + PASSWORD_MIN_LENGTH: int = 8 + PASSWORD_REQUIRE_UPPERCASE: bool = True + PASSWORD_REQUIRE_LOWERCASE: bool = True + PASSWORD_REQUIRE_DIGIT: bool = True + PASSWORD_REQUIRE_SPECIAL: bool = True - OAUTH_GOOGLE_CLIENT_ID: str = config("OAUTH_GOOGLE_CLIENT_ID", default="") - OAUTH_GOOGLE_CLIENT_SECRET: str = config("OAUTH_GOOGLE_CLIENT_SECRET", default="") - OAUTH_GITHUB_CLIENT_ID: str = config("OAUTH_GITHUB_CLIENT_ID", default="") - OAUTH_GITHUB_CLIENT_SECRET: str = config("OAUTH_GITHUB_CLIENT_SECRET", default="") - OAUTH_REDIRECT_BASE_URL: str = config("OAUTH_REDIRECT_BASE_URL", default="http://localhost:8000") + OAUTH_GOOGLE_CLIENT_ID: str = "" + OAUTH_GOOGLE_CLIENT_SECRET: str = "" + OAUTH_GITHUB_CLIENT_ID: str = "" + OAUTH_GITHUB_CLIENT_SECRET: str = "" + OAUTH_REDIRECT_BASE_URL: str = "http://localhost:8000" SESSION_REDIS_HOST: str = Field( - default=config("SESSION_REDIS_HOST", default=config("CACHE_REDIS_HOST", default="localhost")), + default="localhost", validation_alias=AliasChoices("SESSION_REDIS_HOST", "CACHE_REDIS_HOST"), ) SESSION_REDIS_PORT: int = Field( - default=config("SESSION_REDIS_PORT", default=config("CACHE_REDIS_PORT", default=6379), cast=int), + default=6379, validation_alias=AliasChoices("SESSION_REDIS_PORT", "CACHE_REDIS_PORT"), ) SESSION_REDIS_PASSWORD: str | None = Field( - default=config("SESSION_REDIS_PASSWORD", default=config("CACHE_REDIS_PASSWORD", default=None)), + default=None, validation_alias=AliasChoices("SESSION_REDIS_PASSWORD", "CACHE_REDIS_PASSWORD"), ) @@ -81,25 +80,25 @@ def SESSION_REDIS_URL(self) -> str: ) -class LimiterBackendSettings(BaseSettings): +class LimiterBackendSettings(EnvSettings): """The limiter crudauth uses for login lockout, whether or not API routes are throttled.""" - RATE_LIMITER_BACKEND: str = config("RATE_LIMITER_BACKEND", default=RateLimiterBackend.REDIS.value) - RATE_LIMITER_REDIS_HOST: str = config("RATE_LIMITER_REDIS_HOST", default="localhost") - RATE_LIMITER_REDIS_PORT: int = config("RATE_LIMITER_REDIS_PORT", default=6379, cast=int) - RATE_LIMITER_REDIS_DB: int = config("RATE_LIMITER_REDIS_DB", default=1, cast=int) - RATE_LIMITER_REDIS_PASSWORD: str | None = config("RATE_LIMITER_REDIS_PASSWORD", default=None) - RATE_LIMITER_REDIS_CONNECT_TIMEOUT: int = config("RATE_LIMITER_REDIS_CONNECT_TIMEOUT", default=5, cast=int) - RATE_LIMITER_REDIS_POOL_SIZE: int = config("RATE_LIMITER_REDIS_POOL_SIZE", default=10, cast=int) + RATE_LIMITER_BACKEND: str = RateLimiterBackend.REDIS.value + RATE_LIMITER_REDIS_HOST: str = "localhost" + RATE_LIMITER_REDIS_PORT: int = 6379 + RATE_LIMITER_REDIS_DB: int = 1 + RATE_LIMITER_REDIS_PASSWORD: str | None = None + RATE_LIMITER_REDIS_CONNECT_TIMEOUT: int = 5 + RATE_LIMITER_REDIS_POOL_SIZE: int = 10 -class FirstSuperuserSettings(BaseSettings): +class FirstSuperuserSettings(EnvSettings): """The first superuser, created by ``scripts/create_first_superuser.py``.""" - ADMIN_NAME: str = config("ADMIN_NAME", default="") - ADMIN_EMAIL: str = config("ADMIN_EMAIL", default="") - ADMIN_USERNAME: str = config("ADMIN_USERNAME", default="") - ADMIN_PASSWORD: str = config("ADMIN_PASSWORD", default="") + ADMIN_NAME: str = "" + ADMIN_EMAIL: str = "" + ADMIN_USERNAME: str = "" + ADMIN_PASSWORD: str = "" class AccountsSettings(AuthSettings, LimiterBackendSettings, FirstSuperuserSettings): diff --git a/backend/src/infrastructure/auth/setup.py b/backend/src/infrastructure/auth/setup.py index 770307bc..02f7bdaf 100644 --- a/backend/src/infrastructure/auth/setup.py +++ b/backend/src/infrastructure/auth/setup.py @@ -24,6 +24,7 @@ from ...modules.user.constants import NAME_MAX_LENGTH from ...modules.user.models import User from ...wiring.email import EMAIL_SENDER +from ...wiring.signup import NEW_ACCOUNT_FIELDS from ...wiring.transports import EXTRA_TRANSPORTS from ..composition import Lifecycle from ..config.enums import SessionBackend @@ -101,9 +102,14 @@ def _session_transport() -> SessionTransport: ) -def _new_user_fields(context: NewUserContext) -> dict[str, Any]: - """The columns crudauth doesn't fill for an account it creates: the display name.""" - return {"name": context.suggested_name[:NAME_MAX_LENGTH]} +async def _new_user_fields(context: NewUserContext) -> dict[str, Any]: + """The columns crudauth doesn't fill for an account it creates: the display name, and + what ``NEW_ACCOUNT_FIELDS`` sets.""" + fields: dict[str, Any] = {} + for contributed in NEW_ACCOUNT_FIELDS: + fields.update(await contributed(context.db)) + + return {**fields, "name": context.suggested_name[:NAME_MAX_LENGTH]} def _oauth_providers() -> dict[str, OAuthCredentials]: diff --git a/backend/src/infrastructure/cache/settings.py b/backend/src/infrastructure/cache/settings.py index 7d08ca20..e0766078 100644 --- a/backend/src/infrastructure/cache/settings.py +++ b/backend/src/infrastructure/cache/settings.py @@ -1,12 +1,10 @@ """Settings for the cache feature.""" -from pydantic_settings import BaseSettings - -from ..config.base import config +from ..config.base import EnvSettings from ..config.enums import CacheBackend -class CacheSettings(BaseSettings): +class CacheSettings(EnvSettings): """Cache-related settings. This class defines settings for cache connections and behavior across @@ -34,17 +32,17 @@ class CacheSettings(BaseSettings): CACHE_REDIS_POOL_SIZE: Maximum number of connections in the pool. Default is 10. """ - CACHE_ENABLED: bool = config("CACHE_ENABLED", default=True, cast=bool) - CACHE_BACKEND: str = config("CACHE_BACKEND", default=CacheBackend.REDIS.value) + CACHE_ENABLED: bool = True + CACHE_BACKEND: str = CacheBackend.REDIS.value - CACHE_MEMCACHED_HOST: str = config("CACHE_MEMCACHED_HOST", default="localhost") - CACHE_MEMCACHED_PORT: int = config("CACHE_MEMCACHED_PORT", default=11211, cast=int) - CACHE_MEMCACHED_POOL_SIZE: int = config("CACHE_MEMCACHED_POOL_SIZE", default=10, cast=int) - CACHE_MEMCACHED_CONNECT_TIMEOUT: int = config("CACHE_MEMCACHED_CONNECT_TIMEOUT", default=5, cast=int) + CACHE_MEMCACHED_HOST: str = "localhost" + CACHE_MEMCACHED_PORT: int = 11211 + CACHE_MEMCACHED_POOL_SIZE: int = 10 + CACHE_MEMCACHED_CONNECT_TIMEOUT: int = 5 - CACHE_REDIS_HOST: str = config("CACHE_REDIS_HOST", default="localhost") - CACHE_REDIS_PORT: int = config("CACHE_REDIS_PORT", default=6379, cast=int) - CACHE_REDIS_DB: int = config("CACHE_REDIS_DB", default=0, cast=int) - CACHE_REDIS_PASSWORD: str | None = config("CACHE_REDIS_PASSWORD", default=None) - CACHE_REDIS_CONNECT_TIMEOUT: int = config("CACHE_REDIS_CONNECT_TIMEOUT", default=5, cast=int) - CACHE_REDIS_POOL_SIZE: int = config("CACHE_REDIS_POOL_SIZE", default=10, cast=int) + CACHE_REDIS_HOST: str = "localhost" + CACHE_REDIS_PORT: int = 6379 + CACHE_REDIS_DB: int = 0 + CACHE_REDIS_PASSWORD: str | None = None + CACHE_REDIS_CONNECT_TIMEOUT: int = 5 + CACHE_REDIS_POOL_SIZE: int = 10 diff --git a/backend/src/infrastructure/cache/utils.py b/backend/src/infrastructure/cache/utils.py index ab9f9f24..d0980b58 100644 --- a/backend/src/infrastructure/cache/utils.py +++ b/backend/src/infrastructure/cache/utils.py @@ -8,7 +8,7 @@ from pydantic import BaseModel from starlette.requests import Request -from ..auth.scope import scope_fingerprint +from ...wiring.scope import SCOPE_FINGERPRINT def extract_data_inside_brackets(input_string: str) -> list[str]: @@ -117,7 +117,7 @@ def caller_marks(caller: Any) -> str | None: if not isinstance(caller, Principal): return None - narrowed = scope_fingerprint(caller) + narrowed = SCOPE_FINGERPRINT(caller) if SCOPE_FINGERPRINT is not None else None return str(caller.user_id) if narrowed is None else f"{caller.user_id}/{narrowed}" diff --git a/backend/src/infrastructure/composition.py b/backend/src/infrastructure/composition.py index c43886c8..8b36566c 100644 --- a/backend/src/infrastructure/composition.py +++ b/backend/src/infrastructure/composition.py @@ -48,6 +48,11 @@ class Lifecycle: """Removes the rows a feature keeps for a tier that a soft delete already took out.""" +NewAccountFields = Callable[[AsyncSession], Awaitable[dict[str, Any]]] +"""Answers the columns a feature sets on an account as it is created: its own, never the +account's identity, credentials or privileges, which win over it. It reads, and never commits.""" + + @dataclass(frozen=True) class ReadinessCheck: """A dependency the app needs before it can serve, and how to ask whether it is there. diff --git a/backend/src/infrastructure/config/base.py b/backend/src/infrastructure/config/base.py index f4522868..03ea18c9 100644 --- a/backend/src/infrastructure/config/base.py +++ b/backend/src/infrastructure/config/base.py @@ -5,10 +5,13 @@ import logging import os +from collections.abc import Mapping from enum import StrEnum +from types import UnionType +from typing import Any, Union, get_args, get_origin -from pydantic import Field, field_validator -from pydantic_settings import BaseSettings +from pydantic import Field, ValidationInfo, field_validator, model_validator +from pydantic_settings import BaseSettings, EnvSettingsSource, PydanticBaseSettingsSource, SettingsConfigDict from sqlalchemy.engine import URL from starlette.config import Config @@ -48,6 +51,69 @@ def ini_value(value: str) -> str: config = Config(env_path) +FLAG_SPELLINGS = {"true": True, "1": True, "false": False, "0": False} +"""How a flag may be written: the spellings starlette's ``Config`` casts to a bool.""" + + +class _FileAsStarletteReadsIt(EnvSettingsSource): + """The environment file, read as starlette's ``Config`` reads it: one ``NAME=value`` a line, + names exactly as written, values literally, with no ``${...}`` expansion or ``#`` comments. + + Only the fields of the class being built are taken from it, so each mixin leaves the other + mixins' names alone. + """ + + def __init__(self, settings_cls: type[BaseSettings], env_file: Any) -> None: + self.env_file = env_file + super().__init__(settings_cls, case_sensitive=True) + + def _load_env_vars(self) -> Mapping[str, str | None]: + return Config(self.env_file).file_values if self.env_file else {} + + +class EnvSettings(BaseSettings): + """A settings mixin that reads the environment, and the environment file, when it is built. + + The file is the one ``config`` reads, and none under pytest. The environment wins over it. + """ + + model_config = SettingsConfigDict(env_file=None if running_under_pytest else env_path) + + @field_validator("*", mode="before") + @classmethod + def _read_as_starlette_cast_it(cls, value: Any, info: ValidationInfo) -> Any: + """A flag written as text is one of ``true``, ``false``, ``1`` or ``0`` in any case, and a + number written as text is what ``int()`` reads, as when starlette's ``Config`` cast them.""" + if not isinstance(value, str) or info.field_name is None: + return value + + annotation = cls.model_fields[info.field_name].annotation + kinds = set(get_args(annotation)) if get_origin(annotation) in (Union, UnionType) else {annotation} + if bool in kinds: + if value.lower() not in FLAG_SPELLINGS: + raise ValueError(f"{value!r} is not a flag: write true, false, 1 or 0") + + return FLAG_SPELLINGS[value.lower()] + if int in kinds: + return int(value) + + return value + + @classmethod + def settings_customise_sources( + cls, + settings_cls: type[BaseSettings], + init_settings: PydanticBaseSettingsSource, + env_settings: PydanticBaseSettingsSource, + dotenv_settings: PydanticBaseSettingsSource, + file_secret_settings: PydanticBaseSettingsSource, + ) -> tuple[PydanticBaseSettingsSource, ...]: + """The constructor, then the environment, then the file read as starlette reads it.""" + env_file = getattr(dotenv_settings, "env_file", None) + + return init_settings, env_settings, _FileAsStarletteReadsIt(settings_cls, env_file), file_secret_settings + + class EnvironmentOption(StrEnum): """Environment options for the application.""" @@ -57,44 +123,55 @@ class EnvironmentOption(StrEnum): LOCAL = "local" -class EnvironmentSettings(BaseSettings): +class EnvironmentSettings(EnvSettings): """Environment-related settings.""" - ENVIRONMENT: EnvironmentOption = config("ENVIRONMENT", default=EnvironmentOption.DEVELOPMENT, cast=EnvironmentOption) + ENVIRONMENT: EnvironmentOption = EnvironmentOption.DEVELOPMENT SCHEMA_BUILT_ON_STARTUP = (EnvironmentOption.LOCAL, EnvironmentOption.DEVELOPMENT) """The environments where the app builds its schema from the models as it boots.""" -def _creates_tables_by_default() -> bool: - """Whether ``CREATE_TABLES_ON_STARTUP`` is on in the environment this process runs in.""" - environment = config("ENVIRONMENT", default=EnvironmentOption.DEVELOPMENT, cast=EnvironmentOption) - - return environment in SCHEMA_BUILT_ON_STARTUP +def _creates_tables_by_default(environment: str | None = None) -> bool: + """Whether ``CREATE_TABLES_ON_STARTUP`` is on in ``environment``, or in the one the process runs in.""" + return EnvironmentOption(environment or EnvironmentSettings().ENVIRONMENT) in SCHEMA_BUILT_ON_STARTUP -class DatabaseSettings(BaseSettings): +class DatabaseSettings(EnvSettings): """Database-related settings.""" - POSTGRES_USER: str = config("POSTGRES_USER", default="postgres") - POSTGRES_PASSWORD: str = config("POSTGRES_PASSWORD", default="postgres") - POSTGRES_SERVER: str = config("POSTGRES_SERVER", default="localhost") - POSTGRES_PORT: int = config("POSTGRES_PORT", default=5432) - POSTGRES_DB: str = config("POSTGRES_DB", default="postgres") - POSTGRES_ASYNC_PREFIX: str = config("POSTGRES_ASYNC_PREFIX", default="postgresql+asyncpg://") - CREATE_TABLES_ON_STARTUP: bool = config("CREATE_TABLES_ON_STARTUP", default=_creates_tables_by_default(), cast=bool) + POSTGRES_USER: str = "postgres" + POSTGRES_PASSWORD: str = "postgres" + POSTGRES_SERVER: str = "localhost" + POSTGRES_PORT: int = 5432 + POSTGRES_DB: str = "postgres" + POSTGRES_ASYNC_PREFIX: str = "postgresql+asyncpg://" + CREATE_TABLES_ON_STARTUP: bool = Field(default_factory=_creates_tables_by_default) - POSTGRES_POOL_SIZE: int = config("POSTGRES_POOL_SIZE", default=20, cast=int) - POSTGRES_MAX_OVERFLOW: int = config("POSTGRES_MAX_OVERFLOW", default=0, cast=int) - POSTGRES_POOL_PRE_PING: bool = config("POSTGRES_POOL_PRE_PING", default=True, cast=bool) - POSTGRES_POOL_RECYCLE: int = config("POSTGRES_POOL_RECYCLE", default=-1, cast=int) + POSTGRES_POOL_SIZE: int = 20 + POSTGRES_MAX_OVERFLOW: int = 0 + POSTGRES_POOL_PRE_PING: bool = True + POSTGRES_POOL_RECYCLE: int = -1 DATABASE_URL_OVERRIDE: str | None = Field( - default=config("DATABASE_URL", default=None), + default=None, validation_alias="DATABASE_URL", ) + @model_validator(mode="before") + @classmethod + def _tables_follow_the_environment(cls, values: Any) -> Any: + """Default ``CREATE_TABLES_ON_STARTUP`` from the ``ENVIRONMENT`` these settings are built with.""" + if not isinstance(values, dict) or "CREATE_TABLES_ON_STARTUP" in values: + return values + try: + creates = _creates_tables_by_default(values.get("ENVIRONMENT")) + except ValueError: + return values + + return {**values, "CREATE_TABLES_ON_STARTUP": creates} + @property def DATABASE_URL(self) -> str: """Get the full database URL. @@ -126,12 +203,12 @@ def DATABASE_URL(self) -> str: ).render_as_string(hide_password=False) -class CORSSettings(BaseSettings): +class CORSSettings(EnvSettings): """CORS-related settings.""" - CORS_ENABLED: bool = config("CORS_ENABLED", default=True, cast=bool) - CORS_ORIGINS: str = config("CORS_ORIGINS", default="http://localhost:3000,http://localhost:5173") - CORS_ALLOW_CREDENTIALS: bool = config("CORS_ALLOW_CREDENTIALS", default=True, cast=bool) + CORS_ENABLED: bool = True + CORS_ORIGINS: str = "http://localhost:3000,http://localhost:5173" + CORS_ALLOW_CREDENTIALS: bool = True @property def CORS_ORIGINS_LIST(self) -> list[str]: @@ -142,54 +219,54 @@ def CORS_ORIGINS_LIST(self) -> list[str]: """ return [origin.strip() for origin in self.CORS_ORIGINS.split(",") if origin.strip()] - CORS_ALLOW_METHODS: str = config("CORS_ALLOW_METHODS", default="*") - CORS_ALLOW_HEADERS: str = config("CORS_ALLOW_HEADERS", default="*") + CORS_ALLOW_METHODS: str = "*" + CORS_ALLOW_HEADERS: str = "*" -class CompressionSettings(BaseSettings): +class CompressionSettings(EnvSettings): """Compression-related settings.""" - GZIP_ENABLED: bool = config("GZIP_ENABLED", default=True, cast=bool) - GZIP_MINIMUM_SIZE: int = config("GZIP_MINIMUM_SIZE", default=1000, cast=int) + GZIP_ENABLED: bool = True + GZIP_MINIMUM_SIZE: int = 1000 -class ClientCacheSettings(BaseSettings): +class ClientCacheSettings(EnvSettings): """Cache-Control headers the app sets on its own responses.""" - CLIENT_CACHE_ENABLED: bool = config("CLIENT_CACHE_ENABLED", default=True, cast=bool) - CLIENT_CACHE_MAX_AGE: int = config("CLIENT_CACHE_MAX_AGE", default=60, cast=int) + CLIENT_CACHE_ENABLED: bool = True + CLIENT_CACHE_MAX_AGE: int = 60 -class APIDocSettings(BaseSettings): +class APIDocSettings(EnvSettings): """API documentation settings.""" - ENABLE_DOCS_IN_PRODUCTION: bool = config("ENABLE_DOCS_IN_PRODUCTION", default=False, cast=bool) - OPENAPI_PREFIX: str = config("OPENAPI_PREFIX", default="") - DOCS_URL: str = config("DOCS_URL", default="/docs") - REDOC_URL: str = config("REDOC_URL", default="/redoc") - OPENAPI_URL: str = config("OPENAPI_URL", default="/openapi.json") + ENABLE_DOCS_IN_PRODUCTION: bool = False + OPENAPI_PREFIX: str = "" + DOCS_URL: str = "/docs" + REDOC_URL: str = "/redoc" + OPENAPI_URL: str = "/openapi.json" - API_TITLE: str = config("API_TITLE", default="") - API_SUMMARY: str = config("API_SUMMARY", default="") - API_DESCRIPTION: str = config("API_DESCRIPTION", default="") - API_VERSION: str = config("API_VERSION", default="") - API_TERMS_OF_SERVICE: str = config("API_TERMS_OF_SERVICE", default="") + API_TITLE: str = "" + API_SUMMARY: str = "" + API_DESCRIPTION: str = "" + API_VERSION: str = "" + API_TERMS_OF_SERVICE: str = "" - API_CONTACT_NAME: str = config("API_CONTACT_NAME", default="") - API_CONTACT_URL: str = config("API_CONTACT_URL", default="") - API_CONTACT_EMAIL: str = config("API_CONTACT_EMAIL", default="") + API_CONTACT_NAME: str = "" + API_CONTACT_URL: str = "" + API_CONTACT_EMAIL: str = "" - API_LICENSE_NAME: str = config("API_LICENSE_NAME", default="") - API_LICENSE_URL: str = config("API_LICENSE_URL", default="") - API_LICENSE_IDENTIFIER: str = config("API_LICENSE_IDENTIFIER", default="") + API_LICENSE_NAME: str = "" + API_LICENSE_URL: str = "" + API_LICENSE_IDENTIFIER: str = "" - API_TAGS_METADATA: str = config("API_TAGS_METADATA", default="[]") + API_TAGS_METADATA: str = "[]" -class APISettings(BaseSettings): +class APISettings(EnvSettings): """API-related settings.""" - API_PREFIX: str = Field(default=config("API_PREFIX", default="/api"), validate_default=True) + API_PREFIX: str = Field(default="/api", validate_default=True) @field_validator("API_PREFIX") @classmethod @@ -200,56 +277,56 @@ def _a_prefix_the_router_can_mount(cls, value: str) -> str: return value -class AppSettings(BaseSettings): +class AppSettings(EnvSettings): """Application-related settings.""" # Note: For API documentation, prefer using API_* fields in APIDocSettings - APP_NAME: str = config("APP_NAME", default="FastAPI Boilerplate") - APP_DESCRIPTION: str = config("APP_DESCRIPTION", default="") - DEBUG: bool = config("DEBUG", default=False, cast=bool) - VERSION: str = config("VERSION", default="0.1.0") + APP_NAME: str = "FastAPI Boilerplate" + APP_DESCRIPTION: str = "" + DEBUG: bool = False + VERSION: str = "0.1.0" -class EmailSettings(BaseSettings): +class EmailSettings(EnvSettings): """How the account emails are delivered, and who they come from.""" - EMAIL_BACKEND: str = config("EMAIL_BACKEND", default=EmailBackend.CONSOLE.value) - EMAIL_FROM: str = config("EMAIL_FROM", default="no-reply@localhost") - EMAIL_FROM_NAME: str = config("EMAIL_FROM_NAME", default="") + EMAIL_BACKEND: str = EmailBackend.CONSOLE.value + EMAIL_FROM: str = "no-reply@localhost" + EMAIL_FROM_NAME: str = "" - FRONTEND_URL: str = config("FRONTEND_URL", default="http://localhost:3000") + FRONTEND_URL: str = "http://localhost:3000" - EMAIL_SMTP_HOST: str = config("EMAIL_SMTP_HOST", default="") - EMAIL_SMTP_PORT: int = config("EMAIL_SMTP_PORT", default=587, cast=int) - EMAIL_SMTP_USER: str = config("EMAIL_SMTP_USER", default="") - EMAIL_SMTP_PASSWORD: str = config("EMAIL_SMTP_PASSWORD", default="") - EMAIL_SMTP_STARTTLS: bool = config("EMAIL_SMTP_STARTTLS", default=True, cast=bool) - EMAIL_SMTP_TIMEOUT_SECONDS: int = config("EMAIL_SMTP_TIMEOUT_SECONDS", default=10, cast=int) + EMAIL_SMTP_HOST: str = "" + EMAIL_SMTP_PORT: int = 587 + EMAIL_SMTP_USER: str = "" + EMAIL_SMTP_PASSWORD: str = "" + EMAIL_SMTP_STARTTLS: bool = True + EMAIL_SMTP_TIMEOUT_SECONDS: int = 10 -class SecuritySettings(BaseSettings): +class SecuritySettings(EnvSettings): """Security validation settings, and the secret every signed value derives from.""" - SECRET_KEY: str = config("SECRET_KEY", default="insecure-secret-key-change-this") + SECRET_KEY: str = "insecure-secret-key-change-this" - PRODUCTION_SECURITY_VALIDATION_ENABLED: bool = config("PRODUCTION_SECURITY_VALIDATION_ENABLED", default=True, cast=bool) - SECURITY_HEADERS_ENABLED: bool = config("SECURITY_HEADERS_ENABLED", default=True, cast=bool) + PRODUCTION_SECURITY_VALIDATION_ENABLED: bool = True + SECURITY_HEADERS_ENABLED: bool = True -class LoggingSettings(BaseSettings): +class LoggingSettings(EnvSettings): """Centralized logging configuration settings.""" - LOG_LEVEL: str = config("LOG_LEVEL", default=LogLevel.INFO.value) - LOG_FORMAT: str = Field(default=config("LOG_FORMAT", default=""), validate_default=True) + LOG_LEVEL: str = LogLevel.INFO.value + LOG_FORMAT: str = Field(default="", validate_default=True) - LOG_CONSOLE_ENABLED: bool = config("LOG_CONSOLE_ENABLED", default=True, cast=bool) - LOG_FILE_ENABLED: bool = config("LOG_FILE_ENABLED", default=False, cast=bool) - LOG_FILE_PATH: str = config("LOG_FILE_PATH", default="logs/app.log") - LOG_FILE_MAX_SIZE: int = config("LOG_FILE_MAX_SIZE", default=10485760, cast=int) - LOG_FILE_BACKUP_COUNT: int = config("LOG_FILE_BACKUP_COUNT", default=5, cast=int) + LOG_CONSOLE_ENABLED: bool = True + LOG_FILE_ENABLED: bool = False + LOG_FILE_PATH: str = "logs/app.log" + LOG_FILE_MAX_SIZE: int = 10485760 + LOG_FILE_BACKUP_COUNT: int = 5 - LOG_DEVELOPMENT_VERBOSE: bool = config("LOG_DEVELOPMENT_VERBOSE", default=True, cast=bool) - LOG_PRODUCTION_OPTIMIZE: bool = config("LOG_PRODUCTION_OPTIMIZE", default=True, cast=bool) + LOG_DEVELOPMENT_VERBOSE: bool = True + LOG_PRODUCTION_OPTIMIZE: bool = True @field_validator("LOG_FORMAT") @classmethod diff --git a/backend/src/infrastructure/ratelimit/settings.py b/backend/src/infrastructure/ratelimit/settings.py index 08eb30fb..60e72f88 100644 --- a/backend/src/infrastructure/ratelimit/settings.py +++ b/backend/src/infrastructure/ratelimit/settings.py @@ -1,13 +1,11 @@ """Settings for the API rate-limit feature.""" -from pydantic_settings import BaseSettings +from ..config.base import EnvSettings -from ..config.base import config - -class RateLimitSettings(BaseSettings): +class RateLimitSettings(EnvSettings): """Whether API routes are throttled, and the limit used when no tier row matches.""" - RATE_LIMITER_ENABLED: bool = config("RATE_LIMITER_ENABLED", default=True, cast=bool) - DEFAULT_RATE_LIMIT_LIMIT: int = config("DEFAULT_RATE_LIMIT_LIMIT", default=100, cast=int) - DEFAULT_RATE_LIMIT_PERIOD: int = config("DEFAULT_RATE_LIMIT_PERIOD", default=60, cast=int) + RATE_LIMITER_ENABLED: bool = True + DEFAULT_RATE_LIMIT_LIMIT: int = 100 + DEFAULT_RATE_LIMIT_PERIOD: int = 60 diff --git a/backend/src/infrastructure/taskiq/settings.py b/backend/src/infrastructure/taskiq/settings.py index c4556e5e..0f490f0a 100644 --- a/backend/src/infrastructure/taskiq/settings.py +++ b/backend/src/infrastructure/taskiq/settings.py @@ -2,31 +2,30 @@ from urllib.parse import quote -from pydantic_settings import BaseSettings from sqlalchemy.engine import URL -from ..config.base import config +from ..config.base import EnvSettings from ..config.enums import TaskiqBrokerType from ..redis import redis_url -class TaskiqSettings(BaseSettings): +class TaskiqSettings(EnvSettings): """Taskiq async task queue settings.""" - TASKIQ_BROKER_TYPE: str = config("TASKIQ_BROKER_TYPE", default=TaskiqBrokerType.REDIS.value) - TASKIQ_DEFAULT_RETRY_COUNT: int = config("TASKIQ_DEFAULT_RETRY_COUNT", default=3, cast=int) - TASKIQ_RETRY_DELAY_SECONDS: int = config("TASKIQ_RETRY_DELAY_SECONDS", default=0, cast=int) + TASKIQ_BROKER_TYPE: str = TaskiqBrokerType.REDIS.value + TASKIQ_DEFAULT_RETRY_COUNT: int = 3 + TASKIQ_RETRY_DELAY_SECONDS: int = 0 - TASKIQ_REDIS_HOST: str = config("TASKIQ_REDIS_HOST", default="localhost") - TASKIQ_REDIS_PORT: int = config("TASKIQ_REDIS_PORT", default=6379, cast=int) - TASKIQ_REDIS_DB: int = config("TASKIQ_REDIS_DB", default=3, cast=int) - TASKIQ_REDIS_PASSWORD: str | None = config("TASKIQ_REDIS_PASSWORD", default=None) + TASKIQ_REDIS_HOST: str = "localhost" + TASKIQ_REDIS_PORT: int = 6379 + TASKIQ_REDIS_DB: int = 3 + TASKIQ_REDIS_PASSWORD: str | None = None - TASKIQ_RABBITMQ_HOST: str = config("TASKIQ_RABBITMQ_HOST", default="localhost") - TASKIQ_RABBITMQ_PORT: int = config("TASKIQ_RABBITMQ_PORT", default=5672, cast=int) - TASKIQ_RABBITMQ_USER: str = config("TASKIQ_RABBITMQ_USER", default="guest") - TASKIQ_RABBITMQ_PASSWORD: str = config("TASKIQ_RABBITMQ_PASSWORD", default="guest") - TASKIQ_RABBITMQ_VHOST: str = config("TASKIQ_RABBITMQ_VHOST", default="/") + TASKIQ_RABBITMQ_HOST: str = "localhost" + TASKIQ_RABBITMQ_PORT: int = 5672 + TASKIQ_RABBITMQ_USER: str = "guest" + TASKIQ_RABBITMQ_PASSWORD: str = "guest" + TASKIQ_RABBITMQ_VHOST: str = "/" @property def TASKIQ_BROKER_URL(self) -> str: diff --git a/backend/src/interfaces/admin/settings.py b/backend/src/interfaces/admin/settings.py index 1c09511b..3d263d90 100644 --- a/backend/src/interfaces/admin/settings.py +++ b/backend/src/interfaces/admin/settings.py @@ -1,12 +1,10 @@ """Settings for the SQLAdmin panel.""" -from pydantic_settings import BaseSettings +from ...infrastructure.config.base import EnvSettings -from ...infrastructure.config.base import config - -class SQLAdminSettings(BaseSettings): +class SQLAdminSettings(EnvSettings): """SQLAdmin interface settings.""" - ADMIN_ENABLED: bool = config("ADMIN_ENABLED", default=False, cast=bool) - ADMIN_BASE_URL: str = config("ADMIN_BASE_URL", default="/admin") + ADMIN_ENABLED: bool = False + ADMIN_BASE_URL: str = "/admin" diff --git a/backend/src/modules/api_keys/settings.py b/backend/src/modules/api_keys/settings.py index 44e43541..e62436a3 100644 --- a/backend/src/modules/api_keys/settings.py +++ b/backend/src/modules/api_keys/settings.py @@ -1,18 +1,15 @@ """Settings for the API keys feature.""" from pydantic import Field -from pydantic_settings import BaseSettings -from ...infrastructure.config.base import config +from ...infrastructure.config.base import EnvSettings -class APIKeySettings(BaseSettings): +class APIKeySettings(EnvSettings): """How long the usage rows a key's requests write are kept. A day count below zero is refused as the settings load, where a typo would otherwise read as the 0 that keeps every row. """ - KEY_USAGE_RETENTION_DAYS: int = Field( - default=config("KEY_USAGE_RETENTION_DAYS", default=90, cast=int), ge=0, validate_default=True - ) + KEY_USAGE_RETENTION_DAYS: int = Field(default=90, ge=0, validate_default=True) diff --git a/backend/src/modules/tier/hooks.py b/backend/src/modules/tier/hooks.py new file mode 100644 index 00000000..630daaef --- /dev/null +++ b/backend/src/modules/tier/hooks.py @@ -0,0 +1,15 @@ +"""What the tiers feature plugs into other features, listed in ``wiring.signup``.""" + +from typing import Any + +from sqlalchemy.ext.asyncio import AsyncSession + +from ...infrastructure.config.settings import settings +from .crud import crud_tiers + + +async def default_tier(db: AsyncSession) -> dict[str, Any]: + """The tier ``DEFAULT_TIER_NAME`` names, for a new account, or nothing while there is no such tier.""" + tier = await crud_tiers.get(db=db, name=settings.DEFAULT_TIER_NAME, is_deleted=False) + + return {"tier_id": tier["id"]} if tier else {} diff --git a/backend/src/modules/tier/settings.py b/backend/src/modules/tier/settings.py index 5a4c75b8..e7b748b6 100644 --- a/backend/src/modules/tier/settings.py +++ b/backend/src/modules/tier/settings.py @@ -1,11 +1,9 @@ """Settings for the tiers feature.""" -from pydantic_settings import BaseSettings +from ...infrastructure.config.base import EnvSettings -from ...infrastructure.config.base import config - -class TierSettings(BaseSettings): +class TierSettings(EnvSettings): """The tier new users are given when none is named.""" - DEFAULT_TIER_NAME: str = config("DEFAULT_TIER_NAME", default="free") + DEFAULT_TIER_NAME: str = "free" diff --git a/backend/src/modules/user/routes.py b/backend/src/modules/user/routes.py index 8a73326b..3bc926f6 100644 --- a/backend/src/modules/user/routes.py +++ b/backend/src/modules/user/routes.py @@ -42,7 +42,8 @@ - Email address - Password (with security requirements) - New accounts are automatically assigned to the default tier. + Columns other features add to an account are set as it is created, through + `src/wiring/signup.py`. The answer says nothing about whether the address was free. An address that already has an account is answered the same way as one that did not, and the diff --git a/backend/src/modules/user/schemas.py b/backend/src/modules/user/schemas.py index 002c6901..05619f3c 100644 --- a/backend/src/modules/user/schemas.py +++ b/backend/src/modules/user/schemas.py @@ -91,7 +91,12 @@ class UserCreate(UserBase): class UserCreateInternal(UserBase): - """Internal schema for user creation with hashed password.""" + """Internal schema for user creation with hashed password. + + It also carries the columns ``wiring.signup`` has other features set on a new account, + which the user module doesn't name.""" + + model_config = ConfigDict(extra="allow") hashed_password: str google_id: str | None = None diff --git a/backend/src/modules/user/service.py b/backend/src/modules/user/service.py index a9d85b5a..26dbaef9 100644 --- a/backend/src/modules/user/service.py +++ b/backend/src/modules/user/service.py @@ -10,6 +10,7 @@ from ...infrastructure.auth.setup import auth from ...infrastructure.logging import get_logger +from ...wiring.signup import NEW_ACCOUNT_FIELDS from ..common.collisions import refused_constraint from ..common.exceptions import ( PermissionDeniedError, @@ -109,11 +110,17 @@ async def create(self, user: UserCreate, db: AsyncSession) -> dict[str, Any]: if username_exists: raise UserExistsError("Username already taken") + contributed: dict[str, Any] = {} + for fields in NEW_ACCOUNT_FIELDS: + contributed.update(await fields(db)) user_internal = UserCreateInternal( - name=user.name, - username=user.username, - email=email, - hashed_password=hashed_password, + **{ + **auth.repo.filter_provisioning_data(contributed), + "name": user.name, + "username": user.username, + "email": email, + "hashed_password": hashed_password, + } ) try: created_user = await crud_users.create(db=db, object=user_internal, schema_to_select=UserRead) diff --git a/backend/src/wiring/__init__.py b/backend/src/wiring/__init__.py index 80bd5182..4cc6f27b 100644 --- a/backend/src/wiring/__init__.py +++ b/backend/src/wiring/__init__.py @@ -1,5 +1,5 @@ """The composition root: where the selected features meet. -Every module here is hand-maintained until the generator exists, and holds only +Every module beside this one is generated by fastro from ``blueprint.toml``, and holds only imports and literals, so ruff, mypy and an IDE see exactly what is wired. """ diff --git a/backend/src/wiring/admin.py b/backend/src/wiring/admin.py index 683ae994..263ad262 100644 --- a/backend/src/wiring/admin.py +++ b/backend/src/wiring/admin.py @@ -1,6 +1,7 @@ """The model views the admin panel registers. -Written by the generator in `tools/removal_drill.py`, which a test compares this file against. +Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change +fastro.toml (or [app] in it, for your own code) and run `fastro sync`. """ from ..modules.role.admin import RoleAdmin, RolePermissionAdmin, UserRoleAdmin diff --git a/backend/src/wiring/app.py b/backend/src/wiring/app.py index bda0046e..02e62360 100644 --- a/backend/src/wiring/app.py +++ b/backend/src/wiring/app.py @@ -1,7 +1,7 @@ """The composition root: what the app mounts, starts and installs. -Written by the generator in `tools/removal_drill.py`, which a test compares this file against: -imports and literals only, so ruff, mypy and an IDE see exactly what is wired. +Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change +fastro.toml (or [app] in it, for your own code) and run `fastro sync`. """ from collections.abc import Callable diff --git a/backend/src/wiring/cache.py b/backend/src/wiring/cache.py index ab4b866e..d53bd5b5 100644 --- a/backend/src/wiring/cache.py +++ b/backend/src/wiring/cache.py @@ -1,7 +1,7 @@ """The decorator a route caches its response with. -Written by the generator in `tools/removal_drill.py`, which a test compares this file against: -imports and literals only. +Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change +fastro.toml (or [app] in it, for your own code) and run `fastro sync`. """ from ..infrastructure.cache.decorator import cache as cached diff --git a/backend/src/wiring/email.py b/backend/src/wiring/email.py index 723a1086..d472e5c2 100644 --- a/backend/src/wiring/email.py +++ b/backend/src/wiring/email.py @@ -1,8 +1,9 @@ """The sender the account emails go out through. -Written by the generator in `tools/removal_drill.py`, which a test compares this file against: -imports and literals only. It is its own module because ``hooks`` reaches features that import the -accounts feature back. +It is its own module because ``hooks`` reaches features that import the accounts feature back. + +Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change +fastro.toml (or [app] in it, for your own code) and run `fastro sync`. """ from crudauth import EmailSender diff --git a/backend/src/wiring/hooks.py b/backend/src/wiring/hooks.py index 6d542e41..434d9f32 100644 --- a/backend/src/wiring/hooks.py +++ b/backend/src/wiring/hooks.py @@ -1,18 +1,12 @@ """The contributions features make to each other's extension points. -Written by the generator in `tools/removal_drill.py`, which a test compares this file against: -imports and literals only. +Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change +fastro.toml (or [app] in it, for your own code) and run `fastro sync`. """ from ..infrastructure.auth.health import limiter_readiness, sessions_readiness from ..infrastructure.cache.health import readiness as cache_readiness -from ..infrastructure.composition import ( - PermissionSource, - RateLimitResolver, - ReadinessCheck, - TierDeleteGuard, - TierDeleteRelease, -) +from ..infrastructure.composition import PermissionSource, RateLimitResolver, ReadinessCheck, TierDeleteGuard, TierDeleteRelease from ..infrastructure.database.health import readiness as database_readiness from ..infrastructure.database.health import schema_readiness from ..infrastructure.taskiq.health import readiness as broker_readiness diff --git a/backend/src/wiring/models.py b/backend/src/wiring/models.py index a32214fa..363c4324 100644 --- a/backend/src/wiring/models.py +++ b/backend/src/wiring/models.py @@ -1,6 +1,7 @@ """Extension points of the user model: what other features add to ``User``. -Written by the generator in `tools/removal_drill.py`, which a test compares this file against. +Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change +fastro.toml (or [app] in it, for your own code) and run `fastro sync`. """ from ..modules.role.contrib import UserRoleColumns diff --git a/backend/src/wiring/scope.py b/backend/src/wiring/scope.py new file mode 100644 index 00000000..d97d4ab2 --- /dev/null +++ b/backend/src/wiring/scope.py @@ -0,0 +1,15 @@ +"""What tells a credential that carries a scope apart from its account's others. + +It is its own module, importing none of the other wiring, so that whatever keys what it stores by caller can read it. + +Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change +fastro.toml (or [app] in it, for your own code) and run `fastro sync`. +""" + +from collections.abc import Callable + +from crudauth import Principal + +from ..infrastructure.auth.scope import scope_fingerprint + +SCOPE_FINGERPRINT: Callable[[Principal], str | None] | None = scope_fingerprint diff --git a/backend/src/wiring/settings.py b/backend/src/wiring/settings.py index 1d3d4b89..72a1c347 100644 --- a/backend/src/wiring/settings.py +++ b/backend/src/wiring/settings.py @@ -1,7 +1,9 @@ """The project's settings: each selected feature's mixin on top of the core. -Written by the generator in `tools/removal_drill.py`, which a test compares this file against. Core -comes last, so a feature can override a core default rather than the other way round. +Core comes last, so a feature can override a core default rather than the other way round. + +Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change +fastro.toml (or [app] in it, for your own code) and run `fastro sync`. """ from ..infrastructure.auth.settings import AccountsSettings diff --git a/backend/src/wiring/signup.py b/backend/src/wiring/signup.py new file mode 100644 index 00000000..99ef452f --- /dev/null +++ b/backend/src/wiring/signup.py @@ -0,0 +1,12 @@ +"""The columns features set on an account as it is created, on every signup path. + +The account setup reads it, so it is its own module: `wiring/hooks.py` reaches features that import the account setup back. + +Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change +fastro.toml (or [app] in it, for your own code) and run `fastro sync`. +""" + +from ..infrastructure.composition import NewAccountFields +from ..modules.tier.hooks import default_tier + +NEW_ACCOUNT_FIELDS: tuple[NewAccountFields, ...] = (default_tier,) diff --git a/backend/src/wiring/tables.py b/backend/src/wiring/tables.py index 3c9e797c..f18c7cf6 100644 --- a/backend/src/wiring/tables.py +++ b/backend/src/wiring/tables.py @@ -1,7 +1,7 @@ """Modules outside ``src/modules`` that declare tables on ``Base.metadata``. -Written by the generator in `tools/removal_drill.py`, which a test compares this file against: -imports and literals only. +Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change +fastro.toml (or [app] in it, for your own code) and run `fastro sync`. """ TABLE_MODULES: tuple[str, ...] = ("src.infrastructure.auth.store",) diff --git a/backend/src/wiring/tasks.py b/backend/src/wiring/tasks.py index 5e529acd..6fd060b2 100644 --- a/backend/src/wiring/tasks.py +++ b/backend/src/wiring/tasks.py @@ -1,8 +1,12 @@ """The modules whose background tasks the worker registers. -Written by the generator in `tools/removal_drill.py`, which a test compares this file against: -imports and literals only. A task the worker reports as unknown drops its message, so a module -declaring one belongs in this list. +A task the worker reports as unknown drops its message, so a module declaring one belongs in this list. + +Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change +fastro.toml (or [app] in it, for your own code) and run `fastro sync`. """ -TASK_MODULES: tuple[str, ...] = ("src.infrastructure.taskiq.email", "src.modules.api_keys.tasks") +TASK_MODULES: tuple[str, ...] = ( + "src.infrastructure.taskiq.email", + "src.modules.api_keys.tasks", +) diff --git a/backend/src/wiring/transports.py b/backend/src/wiring/transports.py index 8488ccd3..ffb4998b 100644 --- a/backend/src/wiring/transports.py +++ b/backend/src/wiring/transports.py @@ -1,4 +1,8 @@ -"""The authentication transports this project registers beside the session one.""" +"""The authentication transports this project registers beside the session one. + +Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change +fastro.toml (or [app] in it, for your own code) and run `fastro sync`. +""" from crudauth import Transport diff --git a/backend/tests/conftest.py b/backend/tests/conftest.py index 665d169b..38f6ab6d 100644 --- a/backend/tests/conftest.py +++ b/backend/tests/conftest.py @@ -16,8 +16,6 @@ os.environ.setdefault("ADMIN_ENABLED", "true") os.environ.setdefault("ADMIN_USERNAME", "admin") os.environ.setdefault("ADMIN_PASSWORD", "s3cret") -os.environ.setdefault("SQLITE_URI", ":memory:") -os.environ.setdefault("SQLITE_ASYNC_PREFIX", "sqlite+aiosqlite:///") # Disable the testcontainers Ryuk reaper. Under `pytest -n auto`, each xdist worker # is a separate process that spins up its own Ryuk container, and Docker Desktop diff --git a/backend/tests/fixtures/accounts.py b/backend/tests/fixtures/accounts.py index b08a397a..b6a65c91 100644 --- a/backend/tests/fixtures/accounts.py +++ b/backend/tests/fixtures/accounts.py @@ -1,38 +1,40 @@ """Fixtures of the accounts feature: users, and clients signed in as them.""" import time +from collections.abc import AsyncIterator +from uuid import uuid4 import pytest import pytest_asyncio -from crudauth import Principal, get_password_hash +from crudauth import get_password_hash from crudauth.utils import canonical_email from faker import Faker -from httpx import AsyncClient +from httpx import ASGITransport, AsyncClient +from sqlalchemy import update from sqlalchemy.ext.asyncio import AsyncSession -from src.infrastructure.auth.dependencies import ( - get_current_principal, - get_current_superuser, - get_current_user, - get_session_principal, -) from src.infrastructure.auth.setup import auth as crud_auth from src.interfaces.main import app from src.modules.user.models import User +def new_user(*, prefix: str = "u", password: str = "Password123!", is_superuser: bool = False, profile_image_url: str) -> User: + """A user whose username and email no other fixture user has.""" + unique = uuid4().hex + return User( + name=Faker().name(), + username=f"{prefix}{unique[:20]}", + email=f"{unique}@example.com", + hashed_password=get_password_hash(password), + is_superuser=is_superuser, + profile_image_url=profile_image_url, + ) + + @pytest_asyncio.fixture async def test_user(db_session: AsyncSession): """Create a test user.""" - fake = Faker() - user = User( - name=fake.name(), - username=f"u{fake.random_int(10000, 99999)}", - email=fake.email(), - hashed_password=get_password_hash("Password123!"), - is_superuser=False, - profile_image_url="https://example.com/test.jpg", - ) + user = new_user(profile_image_url="https://example.com/test.jpg") db_session.add(user) await db_session.commit() await reset_password_budget(user.id) @@ -51,15 +53,7 @@ async def test_user(db_session: AsyncSession): @pytest_asyncio.fixture async def test_user_2(db_session: AsyncSession): """Second test user for permission tests.""" - fake = Faker() - user = User( - name=fake.name(), - username=f"u{fake.random_int(10000, 99999)}", - email=fake.email(), - hashed_password=get_password_hash("Password123!"), - is_superuser=False, - profile_image_url="https://example.com/test2.jpg", - ) + user = new_user(profile_image_url="https://example.com/test2.jpg") db_session.add(user) await db_session.commit() await reset_password_budget(user.id) @@ -77,14 +71,8 @@ async def test_user_2(db_session: AsyncSession): @pytest_asyncio.fixture async def test_superuser(db_session: AsyncSession): """Create a test superuser.""" - fake = Faker() - user = User( - name=fake.name(), - username=f"su{fake.random_int(10000, 99999)}", - email=fake.email(), - hashed_password=get_password_hash("SuperuserPass123!"), - is_superuser=True, - profile_image_url="https://example.com/superuser.jpg", + user = new_user( + prefix="su", password="SuperuserPass123!", is_superuser=True, profile_image_url="https://example.com/superuser.jpg" ) db_session.add(user) await db_session.commit() @@ -100,72 +88,57 @@ async def test_superuser(db_session: AsyncSession): } -def _principal_for(user: dict) -> Principal: - """The crudauth principal the session transport would resolve for this user. +async def _signed_in_as(user: dict, db: AsyncSession) -> AsyncIterator[AsyncClient]: + """A client of its own, signed in as ``user`` through the login route and carrying its CSRF token. - The auth fixtures override the dict-compat dependencies, so anything reading - the principal directly (permission checks, session routes) needs it too, the - session-only dependency included: these clients stand for a signed-in session. + The address is marked verified first. """ - return Principal( - user_id=user["id"], - transport="session", - is_superuser=user.get("is_superuser", False), - email_verified=True, - recovery_verified=True, - ) + await db.execute(update(User).where(User.id == user["id"]).values(email_verified=True)) + await db.commit() + async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as signed_in: + response = await signed_in.post("/api/v1/auth/login", data={"username": user["username"], "password": user["password"]}) + assert response.status_code == 200, response.text + signed_in.headers["X-CSRF-Token"] = response.json()["csrf_token"] + yield signed_in @pytest_asyncio.fixture -async def auth_client(client: AsyncClient, test_user: dict): - """Authenticated test client (regular user) — overrides get_current_user dependency.""" - - async def override_get_current_user(): - return test_user - - async def override_get_current_principal(): - return _principal_for(test_user) +async def auth_client( + client: AsyncClient, db_session: AsyncSession, test_user: dict, fresh_login_lockout: None +) -> AsyncIterator[AsyncClient]: + """A client signed in as ``test_user``, with a session of its own. - app.dependency_overrides[get_current_user] = override_get_current_user - app.dependency_overrides[get_current_principal] = override_get_current_principal - app.dependency_overrides[get_session_principal] = override_get_current_principal - return client + It takes ``client`` for the database override that fixture installs: without it the login route + reaches the app's own database instead of the test one. + """ + async for signed_in in _signed_in_as(test_user, db_session): + yield signed_in @pytest_asyncio.fixture -async def auth_client_2(client: AsyncClient, test_user_2: dict): - """Authenticated test client for second user.""" - - async def override_get_current_user(): - return test_user_2 +async def auth_client_2( + client: AsyncClient, db_session: AsyncSession, test_user_2: dict, fresh_login_lockout: None +) -> AsyncIterator[AsyncClient]: + """A client signed in as ``test_user_2``, with a session of its own beside ``auth_client``'s. - async def override_get_current_principal(): - return _principal_for(test_user_2) - - app.dependency_overrides[get_current_user] = override_get_current_user - app.dependency_overrides[get_current_principal] = override_get_current_principal - app.dependency_overrides[get_session_principal] = override_get_current_principal - return client + It takes ``client`` for the database override that fixture installs: without it the login route + reaches the app's own database instead of the test one. + """ + async for signed_in in _signed_in_as(test_user_2, db_session): + yield signed_in @pytest_asyncio.fixture -async def superuser_auth_client(client: AsyncClient, test_superuser: dict): - """Authenticated test client (superuser).""" +async def superuser_auth_client( + client: AsyncClient, db_session: AsyncSession, test_superuser: dict, fresh_login_lockout: None +) -> AsyncIterator[AsyncClient]: + """A client signed in as ``test_superuser``, with a session of its own beside the other two. - async def override_get_current_user(): - return test_superuser - - async def override_get_current_principal(): - return _principal_for(test_superuser) - - async def override_get_current_superuser(): - return test_superuser - - app.dependency_overrides[get_current_user] = override_get_current_user - app.dependency_overrides[get_current_principal] = override_get_current_principal - app.dependency_overrides[get_session_principal] = override_get_current_principal - app.dependency_overrides[get_current_superuser] = override_get_current_superuser - return client + It takes ``client`` for the database override that fixture installs: without it the login route + reaches the app's own database instead of the test one. + """ + async for signed_in in _signed_in_as(test_superuser, db_session): + yield signed_in @pytest.fixture(autouse=True) diff --git a/backend/tests/integration/api/v1/api_keys/test_read.py b/backend/tests/integration/api/v1/api_keys/test_read.py index 3dfe4127..5fb6e722 100644 --- a/backend/tests/integration/api/v1/api_keys/test_read.py +++ b/backend/tests/integration/api/v1/api_keys/test_read.py @@ -9,8 +9,6 @@ from sqlalchemy import update from sqlalchemy.ext.asyncio import AsyncSession -from src.infrastructure.auth.dependencies import get_current_user -from src.interfaces.main import app from src.modules.api_keys.models import APIKey pytestmark = pytest.mark.asyncio @@ -25,13 +23,12 @@ async def test_a_missing_api_key_returns_the_generic_not_found(auth_client: Asyn assert body["support_id"] -async def test_another_users_api_key_is_forbidden_generically(auth_client: AsyncClient, test_user_2: dict): +async def test_another_users_api_key_is_forbidden_generically(auth_client: AsyncClient, auth_client_2: AsyncClient): created = await auth_client.post("/api/v1/api-keys/", json={"name": "Cross User Key"}) assert created.status_code == 201 key_id = created.json()["id"] - app.dependency_overrides[get_current_user] = lambda: test_user_2 - response = await auth_client.get(f"/api/v1/api-keys/{key_id}") + response = await auth_client_2.get(f"/api/v1/api-keys/{key_id}") assert response.status_code == 403 body = response.json() diff --git a/backend/tests/integration/api/v1/test_read_endpoint_auth.py b/backend/tests/integration/api/v1/test_read_endpoint_auth.py index 385cb18b..11610c6b 100644 --- a/backend/tests/integration/api/v1/test_read_endpoint_auth.py +++ b/backend/tests/integration/api/v1/test_read_endpoint_auth.py @@ -4,6 +4,8 @@ the routes it actually has instead of a list that has to be kept in step. """ +from typing import Any + import pytest from fastapi.routing import APIRoute from httpx import AsyncClient @@ -19,7 +21,15 @@ ) -@pytest.mark.parametrize("path", COLLECTION_READS) +def _cases(paths: list[str]) -> list[Any]: + """One case per path, or one skipped case that says why when there are none.""" + if paths: + return list(paths) + + return [pytest.param(None, marks=pytest.mark.skip(reason="this project has no collection reads under /api/v1/"))] + + +@pytest.mark.parametrize("path", _cases(COLLECTION_READS)) async def test_read_endpoints_reject_anonymous_callers(client: AsyncClient, path: str): """None of the collection reads answer without a session.""" response = await client.get(path) @@ -27,6 +37,14 @@ async def test_read_endpoints_reject_anonymous_callers(client: AsyncClient, path assert response.status_code == 401 +async def test_a_project_with_no_collection_reads_says_why_the_rule_is_skipped(): + (case,) = _cases([]) + (mark,) = case.marks + + assert mark.name == "skip" + assert mark.kwargs["reason"] == "this project has no collection reads under /api/v1/" + + async def test_every_api_collection_read_is_covered(): """A project with API routes must have found some; one with none has nothing to gate.""" api_routes = [route for route in app.routes if isinstance(route, APIRoute) and route.path.startswith("/api/v1/")] diff --git a/backend/tests/integration/api/v1/users/test_delete.py b/backend/tests/integration/api/v1/users/test_delete.py index e802fde7..24cfbb3f 100644 --- a/backend/tests/integration/api/v1/users/test_delete.py +++ b/backend/tests/integration/api/v1/users/test_delete.py @@ -2,8 +2,11 @@ import pytest from httpx import AsyncClient +from sqlalchemy import select from sqlalchemy.ext.asyncio import AsyncSession +from src.modules.user.models import User + from .test_create import generate_unique_user_data logging.basicConfig(level=logging.INFO) @@ -17,7 +20,8 @@ async def test_soft_delete_success( db_session: AsyncSession, test_user: dict, ): - """Test successful soft deletion of user account.""" + """Deleting one's own account soft-deletes the row, and the session it was signed in with no + longer signs it in.""" username = test_user["username"] logger.info(f"Testing soft deletion for user: {username}") @@ -28,7 +32,10 @@ async def test_soft_delete_success( assert data["message"] == "User account deactivated" get_response = await auth_client.get(f"/api/v1/users/{username}") - assert get_response.status_code == 404 + assert get_response.status_code == 401 + + deleted = await db_session.scalar(select(User.is_deleted).where(User.id == test_user["id"])) + assert deleted is True async def test_soft_delete_unauthorized( @@ -148,13 +155,13 @@ async def test_permanent_delete_nonexistent_user( assert data["detail"] == "User not found." -async def test_delete_cascade_effects( +async def test_an_account_deleted_by_its_owner_is_gone_for_another_user( auth_client: AsyncClient, superuser_auth_client: AsyncClient, db_session: AsyncSession, test_user: dict, ): - """Test cascade effects of user deletion.""" + """A self-deleted account's profile answers 404 to another signed-in user.""" username = test_user["username"] profile = await auth_client.get(f"/api/v1/users/{username}") diff --git a/backend/tests/integration/auth/test_fixture_users.py b/backend/tests/integration/auth/test_fixture_users.py new file mode 100644 index 00000000..47782e3b --- /dev/null +++ b/backend/tests/integration/auth/test_fixture_users.py @@ -0,0 +1,21 @@ +"""Fixture users never collide, however many one test makes.""" + +import pytest +from sqlalchemy import func, select +from sqlalchemy.ext.asyncio import AsyncSession + +from src.modules.user.models import User +from tests.fixtures import accounts + + +async def test_two_thousand_fixture_users_fit_in_one_session(db_session: AsyncSession, monkeypatch: pytest.MonkeyPatch): + """The password hash is stubbed: two thousand real ones take minutes, and the + columns that must not collide are the username and the email.""" + monkeypatch.setattr(accounts, "get_password_hash", lambda password: "not-a-hash") + users = [accounts.new_user(profile_image_url="https://example.com/test.jpg") for _ in range(2000)] + db_session.add_all(users) + await db_session.commit() + + stored = await db_session.scalar(select(func.count()).where(User.id.in_([user.id for user in users]))) + + assert stored == 2000 diff --git a/backend/tests/integration/auth/test_two_clients.py b/backend/tests/integration/auth/test_two_clients.py new file mode 100644 index 00000000..7ae95cbd --- /dev/null +++ b/backend/tests/integration/auth/test_two_clients.py @@ -0,0 +1,24 @@ +"""The two signed-in client fixtures are two users, at the same time, in one test.""" + +from httpx import AsyncClient + + +async def test_each_client_is_signed_in_as_its_own_user( + auth_client: AsyncClient, auth_client_2: AsyncClient, test_user: dict, test_user_2: dict +): + first = await auth_client.get("/api/v1/users/me") + second = await auth_client_2.get("/api/v1/users/me") + + assert first.status_code == second.status_code == 200 + assert first.json()["id"] == test_user["id"] + assert second.json()["id"] == test_user_2["id"] + + +async def test_signing_one_client_out_leaves_the_other_signed_in( + auth_client: AsyncClient, auth_client_2: AsyncClient, test_user: dict +): + signed_out = await auth_client_2.post("/api/v1/auth/logout") + + assert signed_out.status_code == 200 + assert (await auth_client_2.get("/api/v1/users/me")).status_code == 401 + assert (await auth_client.get("/api/v1/users/me")).json()["id"] == test_user["id"] diff --git a/backend/tests/integration/tiers/test_signup_tier.py b/backend/tests/integration/tiers/test_signup_tier.py new file mode 100644 index 00000000..a25cdd85 --- /dev/null +++ b/backend/tests/integration/tiers/test_signup_tier.py @@ -0,0 +1,65 @@ +"""A new account is given the default tier, whether it signed up with a password or a provider.""" + +import pytest +from crudauth import NewUserContext +from crudauth.provisioning import resolve_new_user_fields +from httpx import AsyncClient +from sqlalchemy import select, update +from sqlalchemy.ext.asyncio import AsyncSession + +from src.infrastructure.auth.setup import auth +from src.infrastructure.config.settings import settings +from src.modules.tier.models import Tier +from src.modules.user.models import User + + +def _signup(username: str) -> dict[str, str]: + return {"name": "New Person", "username": username, "email": f"{username}@example.com", "password": "Password123!"} + + +async def _signed_up(client: AsyncClient, db: AsyncSession, username: str) -> User: + response = await client.post("/api/v1/users/", json=_signup(username)) + assert response.status_code == 201, response.text + stored = await db.scalar(select(User).where(User.username == username)) + assert stored is not None + + return stored + + +async def test_a_signup_is_given_the_tier_default_tier_name_names( + client: AsyncClient, db_session: AsyncSession, second_test_tier: dict, test_tier: dict +): + """Another tier was made first, so the one given is the one named, not the first there is.""" + assert test_tier["name"] == settings.DEFAULT_TIER_NAME + assert second_test_tier["id"] < test_tier["id"] + + assert (await _signed_up(client, db_session, "newcomer")).tier_id == test_tier["id"] + + +async def test_a_signup_is_given_whichever_tier_default_tier_name_is_set_to( + client: AsyncClient, db_session: AsyncSession, test_tier: dict, second_test_tier: dict, monkeypatch: pytest.MonkeyPatch +): + monkeypatch.setattr(settings, "DEFAULT_TIER_NAME", second_test_tier["name"]) + + assert (await _signed_up(client, db_session, "upgraded")).tier_id == second_test_tier["id"] + + +async def test_a_signup_with_no_default_tier_there_yet_is_accepted_without_one(client: AsyncClient, db_session: AsyncSession): + assert (await _signed_up(client, db_session, "early")).tier_id is None + + +async def test_a_signup_is_not_given_a_default_tier_that_was_deleted( + client: AsyncClient, db_session: AsyncSession, test_tier: dict +): + await db_session.execute(update(Tier).where(Tier.id == test_tier["id"]).values(is_deleted=True)) + await db_session.commit() + + assert (await _signed_up(client, db_session, "late")).tier_id is None + + +async def test_an_account_a_provider_signs_up_is_given_the_default_tier(db_session: AsyncSession, test_tier: dict): + context = NewUserContext(email="someone@example.com", username="someone", source="oauth", db=db_session) + + fields = await resolve_new_user_fields(auth.new_user_fields, context, auth.repo) + + assert fields["tier_id"] == test_tier["id"] diff --git a/backend/tests/settings_defaults.py b/backend/tests/settings_defaults.py index 343963b4..962ede55 100644 --- a/backend/tests/settings_defaults.py +++ b/backend/tests/settings_defaults.py @@ -1,35 +1,18 @@ -"""Reading a setting's declared default, whatever the environment the suite runs in. +"""Reading a setting's default, whatever the environment the suite runs in. A default is only a default where nothing sets the variable, and the suite sets several of -them before it imports the app. So each read happens in a fresh interpreter whose -environment is this one minus the variable being asked about. +them before it imports the app. Settings read the environment when they're built, so each +read builds them in this environment minus the variable being asked about. """ import os -import subprocess -import sys -from pathlib import Path +from unittest.mock import patch -BACKEND_ROOT = Path(__file__).resolve().parents[1] - -_DECLARED_DEFAULT = """ from src.infrastructure.config.settings import Settings -print("DEFAULT:" + str(Settings.model_fields[{name!r}].default)) -""" - def declared_default(name: str, **environment: str) -> str: - """``Settings``' declared default for ``name``, as a string.""" + """The value ``Settings`` gives ``name`` when nothing sets it, as a string.""" inherited = {key: value for key, value in os.environ.items() if key != name} - result = subprocess.run( - [sys.executable, "-c", _DECLARED_DEFAULT.format(name=name)], - cwd=BACKEND_ROOT, - capture_output=True, - text=True, - check=True, - env={**inherited, **environment}, - ) - line = next(line for line in result.stdout.splitlines() if line.startswith("DEFAULT:")) - - return line.removeprefix("DEFAULT:") + with patch.dict(os.environ, {**inherited, **environment}, clear=True): + return str(getattr(Settings(), name)) diff --git a/backend/tests/unit/infrastructure/auth/test_setup.py b/backend/tests/unit/infrastructure/auth/test_setup.py index cf3a2917..0f09df0e 100644 --- a/backend/tests/unit/infrastructure/auth/test_setup.py +++ b/backend/tests/unit/infrastructure/auth/test_setup.py @@ -225,7 +225,8 @@ def test_one_configured_provider_mounts_the_oauth_router(self, configured: dict[ class TestNewUserFields: """crudauth creates the account; the boilerplate supplies the required display name.""" - def test_the_display_name_is_filled_and_bounded(self): + async def test_the_display_name_is_filled_and_bounded(self, monkeypatch): + monkeypatch.setattr(setup, "NEW_ACCOUNT_FIELDS", ()) context = NewUserContext( email="a" * (NAME_MAX_LENGTH + 10) + "@example.com", username="auser", @@ -233,10 +234,24 @@ def test_the_display_name_is_filled_and_bounded(self): db=None, # type: ignore[arg-type] ) - fields = setup._new_user_fields(context) + fields = await setup._new_user_fields(context) - assert fields["name"] == "a" * NAME_MAX_LENGTH - assert len(fields["name"]) == NAME_MAX_LENGTH + assert fields == {"name": "a" * NAME_MAX_LENGTH} + + async def test_what_each_feature_sets_on_a_new_account_is_added(self, monkeypatch): + session = object() + + async def first(db): + assert db is session + return {"tier_id": 3, "first_column": 1} + + async def second(db): + return {"tier_id": 4, "org": "x", "name": "Someone Else"} + + monkeypatch.setattr(setup, "NEW_ACCOUNT_FIELDS", (first, second)) + context = NewUserContext(email="ann@example.com", username="ann", source="oauth", db=session) # type: ignore[arg-type] + + assert await setup._new_user_fields(context) == {"name": "ann", "tier_id": 4, "first_column": 1, "org": "x"} class TestSessionTransportWiring: diff --git a/backend/tests/unit/infrastructure/cache/backends/test_memcached.py b/backend/tests/unit/infrastructure/cache/backends/test_memcached.py index 232b1399..30a465ea 100644 --- a/backend/tests/unit/infrastructure/cache/backends/test_memcached.py +++ b/backend/tests/unit/infrastructure/cache/backends/test_memcached.py @@ -1,9 +1,17 @@ +"""The memcached backend, which a project only installs aiomcache for when it chooses it. + +The dependency belongs to the `cache.backend=memcached` option, and an option owns no paths, so +a project on the default redis choice receives this file without the package it needs. +""" + import json from unittest.mock import AsyncMock, MagicMock, patch import pytest -from src.infrastructure.cache.backends.memcached import ( +pytest.importorskip("aiomcache") + +from src.infrastructure.cache.backends.memcached import ( # noqa: E402 MemcachedBackend, MemcachedSettings, PatternMatchingNotSupportedError, diff --git a/backend/tests/unit/infrastructure/cache/test_decorator.py b/backend/tests/unit/infrastructure/cache/test_decorator.py index da82705a..df5c938a 100644 --- a/backend/tests/unit/infrastructure/cache/test_decorator.py +++ b/backend/tests/unit/infrastructure/cache/test_decorator.py @@ -10,7 +10,6 @@ from fastapi.routing import APIRoute from pydantic import BaseModel, Field -from src.infrastructure.auth.scope import SCOPE_OWNER_IS_SUPERUSER from src.infrastructure.cache.decorator import cache from src.infrastructure.cache.exceptions import InvalidRequestError from src.infrastructure.uncached import cached as uncached @@ -123,23 +122,6 @@ async def endpoint(request: Request, page: int = 1, items_per_page: int = 10) -> crafted, real = (call.args[0] for call in backend.get.call_args_list) assert crafted != real - async def test_a_scoped_credential_does_not_share_an_entry_with_its_owners_session(self, backend): - """A key holds its owner's permissions narrowed, so a response made for the owner's - session is not one it may be served. - """ - session = Principal(user_id=1, transport="session") - scoped = Principal(user_id=1, transport="apikey", scopes=("user.read",), metadata={SCOPE_OWNER_IS_SUPERUSER: False}) - - @cache(key_prefix="keys", resource_id_name="item_id", caller_from="principal") - async def endpoint(request: Request, item_id: int, principal: Principal) -> dict[str, Any]: - return {"ok": True} - - await endpoint(_request(), item_id=7, principal=session) - await endpoint(_request(), item_id=7, principal=scoped) - - asked = [call.args[0] for call in backend.get.call_args_list] - assert asked[0] != asked[1] - async def test_each_caller_gets_their_own_entry(self, backend): @cache(key_prefix="keys", resource_id_name="item_id", caller_from="principal") async def endpoint(request: Request, item_id: int, principal: Principal) -> dict[str, Any]: diff --git a/backend/tests/unit/infrastructure/cache/test_scoped_callers.py b/backend/tests/unit/infrastructure/cache/test_scoped_callers.py new file mode 100644 index 00000000..1445aedf --- /dev/null +++ b/backend/tests/unit/infrastructure/cache/test_scoped_callers.py @@ -0,0 +1,55 @@ +"""A credential that carries a scope is cached apart from its account's other credentials.""" + +from typing import Any +from unittest.mock import AsyncMock, patch + +import pytest +from crudauth import Principal +from fastapi import Request + +from src.infrastructure.auth.scope import SCOPE_OWNER_IS_SUPERUSER +from src.infrastructure.cache.decorator import cache +from src.infrastructure.cache.utils import caller_marks + + +def _scoped(*scope: str) -> Principal: + """A principal shaped as the API-key transport builds one.""" + return Principal(user_id=7, transport="apikey", scopes=scope, metadata={"api_key_id": 1, SCOPE_OWNER_IS_SUPERUSER: False}) + + +def test_a_credential_that_carries_a_scope_is_marked_apart_from_the_account(): + """A key holds its owner's permissions narrowed, so what it is served is its own.""" + marked = caller_marks(_scoped("user.read")) + + assert marked != "7" + assert marked is not None and marked.startswith("7/") + + +def test_two_scopes_of_one_account_are_marked_apart(): + assert caller_marks(_scoped("user.read")) != caller_marks(_scoped("user.read", "user.update")) + + +def test_one_scope_written_in_either_order_is_marked_the_same(): + """The order the names were stored in is the client's, and holds the same permissions.""" + assert caller_marks(_scoped("user.read", "user.update")) == caller_marks(_scoped("user.update", "user.read")) + + +@pytest.mark.asyncio +async def test_a_scoped_credential_does_not_share_an_entry_with_its_owners_session(): + """A key holds its owner's permissions narrowed, so a response made for the owner's session + is not one it may be served.""" + recorded = AsyncMock() + recorded.get = AsyncMock(return_value=None) + request = Request({"type": "http", "method": "GET", "path": "/items", "query_string": b"", "headers": []}) + + @cache(key_prefix="keys", resource_id_name="item_id", caller_from="principal") + async def endpoint(request: Request, item_id: int, principal: Principal) -> dict[str, Any]: + return {"ok": True} + + with patch("src.infrastructure.cache.decorator.cache_provider") as provider: + provider.get_backend.return_value = recorded + await endpoint(request, item_id=7, principal=Principal(user_id=7, transport="session")) + await endpoint(request, item_id=7, principal=_scoped("user.read")) + + session, scoped = (call.args[0] for call in recorded.get.call_args_list) + assert session != scoped diff --git a/backend/tests/unit/infrastructure/cache/test_utils.py b/backend/tests/unit/infrastructure/cache/test_utils.py index 199dd9ff..5313d9b6 100644 --- a/backend/tests/unit/infrastructure/cache/test_utils.py +++ b/backend/tests/unit/infrastructure/cache/test_utils.py @@ -1,7 +1,8 @@ +import pytest from crudauth import Principal from starlette.datastructures import QueryParams -from src.infrastructure.auth.scope import SCOPE_OWNER_IS_SUPERUSER +from src.infrastructure.cache import utils from src.infrastructure.cache.utils import ( caller_marks, format_extra_data, @@ -12,11 +13,6 @@ DECLARED = {"page", "items_per_page"} -def _scoped(*scope: str) -> Principal: - """A principal shaped as the API-key transport builds one.""" - return Principal(user_id=7, transport="apikey", scopes=scope, metadata={"api_key_id": 1, SCOPE_OWNER_IS_SUPERUSER: False}) - - def test_the_query_is_the_declared_parameters_sorted(): assert format_query(QueryParams("page=2&items_per_page=20"), DECLARED) == "items_per_page=20&page=2" @@ -38,21 +34,17 @@ def test_a_session_is_marked_by_the_account_it_signed_in_as(): assert caller_marks(Principal(user_id=7, transport="session")) == "7" -def test_a_credential_that_carries_a_scope_is_marked_apart_from_the_account(): - """A key holds its owner's permissions narrowed, so what it is served is its own.""" - marked = caller_marks(_scoped("user.read")) - - assert marked != "7" - assert marked is not None and marked.startswith("7/") +def test_a_principal_is_marked_by_its_account_and_the_fingerprint_wired(monkeypatch: pytest.MonkeyPatch): + monkeypatch.setattr(utils, "SCOPE_FINGERPRINT", lambda principal: "narrowed") + assert caller_marks(Principal(user_id=7, transport="apikey", scopes=("user.read",))) == "7/narrowed" -def test_two_scopes_of_one_account_are_marked_apart(): - assert caller_marks(_scoped("user.read")) != caller_marks(_scoped("user.read", "user.update")) +def test_without_a_fingerprint_wired_a_principal_is_marked_by_its_account(monkeypatch: pytest.MonkeyPatch): + """A project without accounts wires none, and has no credential that carries a scope.""" + monkeypatch.setattr(utils, "SCOPE_FINGERPRINT", None) -def test_one_scope_written_in_either_order_is_marked_the_same(): - """The order the names were stored in is the client's, and holds the same permissions.""" - assert caller_marks(_scoped("user.read", "user.update")) == caller_marks(_scoped("user.update", "user.read")) + assert caller_marks(Principal(user_id=7, transport="apikey", scopes=("user.read",))) == "7" def test_an_account_read_any_other_way_is_marked_with_nothing(): diff --git a/backend/tests/unit/infrastructure/config/conftest.py b/backend/tests/unit/infrastructure/config/conftest.py new file mode 100644 index 00000000..a06161d1 --- /dev/null +++ b/backend/tests/unit/infrastructure/config/conftest.py @@ -0,0 +1,23 @@ +import importlib +from pathlib import Path + +import pytest + +import src.infrastructure.config.base as base + + +@pytest.fixture +def reloaded(): + """Re-import the settings module under the test's conditions, and put it back afterwards.""" + yield lambda: importlib.reload(base) + importlib.reload(base) + + +@pytest.fixture +def found_file(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> Path: + """``tmp_path/.env``, as the file the module finds where it would find ``backend/.env``.""" + found = tmp_path / ".env" + found.write_text("") + monkeypatch.setattr(base.os.path, "realpath", lambda path: str(tmp_path / "src" / "infrastructure" / "config" / "base.py")) + + return found diff --git a/backend/tests/unit/infrastructure/config/defaults.json b/backend/tests/unit/infrastructure/config/defaults.json new file mode 100644 index 00000000..b2a3bd04 --- /dev/null +++ b/backend/tests/unit/infrastructure/config/defaults.json @@ -0,0 +1,138 @@ +{ + "ADMIN_BASE_URL": "'/admin'", + "ADMIN_EMAIL": "''", + "ADMIN_ENABLED": "False", + "ADMIN_NAME": "''", + "ADMIN_PASSWORD": "''", + "ADMIN_USERNAME": "''", + "API_CONTACT_EMAIL": "''", + "API_CONTACT_NAME": "''", + "API_CONTACT_URL": "''", + "API_DESCRIPTION": "''", + "API_LICENSE_IDENTIFIER": "''", + "API_LICENSE_NAME": "''", + "API_LICENSE_URL": "''", + "API_PREFIX": "'/api'", + "API_SUMMARY": "''", + "API_TAGS_METADATA": "'[]'", + "API_TERMS_OF_SERVICE": "''", + "API_TITLE": "''", + "API_VERSION": "''", + "APP_DESCRIPTION": "''", + "APP_NAME": "'FastAPI Boilerplate'", + "CACHE_BACKEND": "'redis'", + "CACHE_ENABLED": "True", + "CACHE_MEMCACHED_CONNECT_TIMEOUT": "5", + "CACHE_MEMCACHED_HOST": "'localhost'", + "CACHE_MEMCACHED_POOL_SIZE": "10", + "CACHE_MEMCACHED_PORT": "11211", + "CACHE_REDIS_CONNECT_TIMEOUT": "5", + "CACHE_REDIS_DB": "0", + "CACHE_REDIS_HOST": "'localhost'", + "CACHE_REDIS_PASSWORD": "None", + "CACHE_REDIS_POOL_SIZE": "10", + "CACHE_REDIS_PORT": "6379", + "CLIENT_CACHE_ENABLED": "True", + "CLIENT_CACHE_MAX_AGE": "60", + "CORS_ALLOW_CREDENTIALS": "True", + "CORS_ALLOW_HEADERS": "'*'", + "CORS_ALLOW_METHODS": "'*'", + "CORS_ENABLED": "True", + "CORS_ORIGINS": "'http://localhost:3000,http://localhost:5173'", + "CREATE_TABLES_ON_STARTUP": "True", + "CSRF_ENABLED": "True", + "DATABASE_URL_OVERRIDE": "None", + "DEBUG": "False", + "DEFAULT_RATE_LIMIT_LIMIT": "100", + "DEFAULT_RATE_LIMIT_PERIOD": "60", + "DEFAULT_TIER_NAME": "'free'", + "DOCS_URL": "'/docs'", + "EMAIL_BACKEND": "'console'", + "EMAIL_FROM": "'no-reply@localhost'", + "EMAIL_FROM_NAME": "''", + "EMAIL_SMTP_HOST": "''", + "EMAIL_SMTP_PASSWORD": "''", + "EMAIL_SMTP_PORT": "587", + "EMAIL_SMTP_STARTTLS": "True", + "EMAIL_SMTP_TIMEOUT_SECONDS": "10", + "EMAIL_SMTP_USER": "''", + "ENABLE_DOCS_IN_PRODUCTION": "False", + "ENVIRONMENT": "", + "FRESH_SIGN_IN_SECONDS": "None", + "FRONTEND_URL": "'http://localhost:3000'", + "GZIP_ENABLED": "True", + "GZIP_MINIMUM_SIZE": "1000", + "KEY_USAGE_RETENTION_DAYS": "90", + "LOGIN_ATTEMPT_WINDOW_SECONDS": "900", + "LOGIN_LOCKOUT_BASE_SECONDS": "300", + "LOGIN_LOCKOUT_MAX_SECONDS": "3600", + "LOGIN_MAX_ATTEMPTS": "5", + "LOG_CONSOLE_ENABLED": "True", + "LOG_DEVELOPMENT_VERBOSE": "True", + "LOG_FILE_BACKUP_COUNT": "5", + "LOG_FILE_ENABLED": "False", + "LOG_FILE_MAX_SIZE": "10485760", + "LOG_FILE_PATH": "'logs/app.log'", + "LOG_FORMAT": "''", + "LOG_LEVEL": "'INFO'", + "LOG_PRODUCTION_OPTIMIZE": "True", + "MAX_SESSIONS_PER_USER": "5", + "OAUTH_GITHUB_CLIENT_ID": "''", + "OAUTH_GITHUB_CLIENT_SECRET": "''", + "OAUTH_GOOGLE_CLIENT_ID": "''", + "OAUTH_GOOGLE_CLIENT_SECRET": "''", + "OAUTH_REDIRECT_BASE_URL": "'http://localhost:8000'", + "OPENAPI_PREFIX": "''", + "OPENAPI_URL": "'/openapi.json'", + "PASSWORD_MIN_LENGTH": "8", + "PASSWORD_REQUIRE_DIGIT": "True", + "PASSWORD_REQUIRE_LOWERCASE": "True", + "PASSWORD_REQUIRE_SPECIAL": "True", + "PASSWORD_REQUIRE_UPPERCASE": "True", + "POSTGRES_ASYNC_PREFIX": "'postgresql+asyncpg://'", + "POSTGRES_DB": "'postgres'", + "POSTGRES_MAX_OVERFLOW": "0", + "POSTGRES_PASSWORD": "'postgres'", + "POSTGRES_POOL_PRE_PING": "True", + "POSTGRES_POOL_RECYCLE": "-1", + "POSTGRES_POOL_SIZE": "20", + "POSTGRES_PORT": "5432", + "POSTGRES_SERVER": "'localhost'", + "POSTGRES_USER": "'postgres'", + "PRODUCTION_SECURITY_VALIDATION_ENABLED": "True", + "RATE_LIMITER_BACKEND": "'redis'", + "RATE_LIMITER_ENABLED": "True", + "RATE_LIMITER_REDIS_CONNECT_TIMEOUT": "5", + "RATE_LIMITER_REDIS_DB": "1", + "RATE_LIMITER_REDIS_HOST": "'localhost'", + "RATE_LIMITER_REDIS_PASSWORD": "None", + "RATE_LIMITER_REDIS_POOL_SIZE": "10", + "RATE_LIMITER_REDIS_PORT": "6379", + "REDOC_URL": "'/redoc'", + "SECRET_KEY": "'insecure-secret-key-change-this'", + "SECURITY_HEADERS_ENABLED": "True", + "SESSION_ABSOLUTE_TIMEOUT_HOURS": "None", + "SESSION_BACKEND": "'redis'", + "SESSION_CLEANUP_INTERVAL_MINUTES": "15", + "SESSION_REDIS_DB": "2", + "SESSION_REDIS_HOST": "'localhost'", + "SESSION_REDIS_PASSWORD": "None", + "SESSION_REDIS_PORT": "6379", + "SESSION_REDIS_URL_OVERRIDE": "None", + "SESSION_SECURE_COOKIES": "True", + "SESSION_TIMEOUT_MINUTES": "30", + "TASKIQ_BROKER_TYPE": "'redis'", + "TASKIQ_DEFAULT_RETRY_COUNT": "3", + "TASKIQ_RABBITMQ_HOST": "'localhost'", + "TASKIQ_RABBITMQ_PASSWORD": "'guest'", + "TASKIQ_RABBITMQ_PORT": "5672", + "TASKIQ_RABBITMQ_USER": "'guest'", + "TASKIQ_RABBITMQ_VHOST": "'/'", + "TASKIQ_REDIS_DB": "3", + "TASKIQ_REDIS_HOST": "'localhost'", + "TASKIQ_REDIS_PASSWORD": "None", + "TASKIQ_REDIS_PORT": "6379", + "TASKIQ_RETRY_DELAY_SECONDS": "0", + "TRUSTED_PROXY_HOPS": "0", + "VERSION": "'0.1.0'" +} \ No newline at end of file diff --git a/backend/tests/unit/infrastructure/config/example_values.json b/backend/tests/unit/infrastructure/config/example_values.json new file mode 100644 index 00000000..d720b61f --- /dev/null +++ b/backend/tests/unit/infrastructure/config/example_values.json @@ -0,0 +1,138 @@ +{ + "ADMIN_BASE_URL": "'/admin'", + "ADMIN_EMAIL": "'admin@example.com'", + "ADMIN_ENABLED": "False", + "ADMIN_NAME": "'Admin User'", + "ADMIN_PASSWORD": "'Change-Me-Now-1!'", + "ADMIN_USERNAME": "'admin'", + "API_CONTACT_EMAIL": "''", + "API_CONTACT_NAME": "''", + "API_CONTACT_URL": "''", + "API_DESCRIPTION": "''", + "API_LICENSE_IDENTIFIER": "''", + "API_LICENSE_NAME": "''", + "API_LICENSE_URL": "''", + "API_PREFIX": "'/api'", + "API_SUMMARY": "''", + "API_TAGS_METADATA": "'[]'", + "API_TERMS_OF_SERVICE": "''", + "API_TITLE": "''", + "API_VERSION": "''", + "APP_DESCRIPTION": "'Modular FastAPI starter'", + "APP_NAME": "'FastAPI Boilerplate'", + "CACHE_BACKEND": "'redis'", + "CACHE_ENABLED": "True", + "CACHE_MEMCACHED_CONNECT_TIMEOUT": "5", + "CACHE_MEMCACHED_HOST": "'localhost'", + "CACHE_MEMCACHED_POOL_SIZE": "10", + "CACHE_MEMCACHED_PORT": "11211", + "CACHE_REDIS_CONNECT_TIMEOUT": "5", + "CACHE_REDIS_DB": "0", + "CACHE_REDIS_HOST": "'redis'", + "CACHE_REDIS_PASSWORD": "''", + "CACHE_REDIS_POOL_SIZE": "10", + "CACHE_REDIS_PORT": "6379", + "CLIENT_CACHE_ENABLED": "True", + "CLIENT_CACHE_MAX_AGE": "60", + "CORS_ALLOW_CREDENTIALS": "True", + "CORS_ALLOW_HEADERS": "'*'", + "CORS_ALLOW_METHODS": "'*'", + "CORS_ENABLED": "True", + "CORS_ORIGINS": "'http://localhost:3000,http://localhost:5173'", + "CREATE_TABLES_ON_STARTUP": "True", + "CSRF_ENABLED": "True", + "DATABASE_URL_OVERRIDE": "None", + "DEBUG": "False", + "DEFAULT_RATE_LIMIT_LIMIT": "100", + "DEFAULT_RATE_LIMIT_PERIOD": "60", + "DEFAULT_TIER_NAME": "'free'", + "DOCS_URL": "'/docs'", + "EMAIL_BACKEND": "'console'", + "EMAIL_FROM": "'no-reply@localhost'", + "EMAIL_FROM_NAME": "''", + "EMAIL_SMTP_HOST": "''", + "EMAIL_SMTP_PASSWORD": "''", + "EMAIL_SMTP_PORT": "587", + "EMAIL_SMTP_STARTTLS": "True", + "EMAIL_SMTP_TIMEOUT_SECONDS": "10", + "EMAIL_SMTP_USER": "''", + "ENABLE_DOCS_IN_PRODUCTION": "False", + "ENVIRONMENT": "", + "FRESH_SIGN_IN_SECONDS": "None", + "FRONTEND_URL": "'http://localhost:3000'", + "GZIP_ENABLED": "True", + "GZIP_MINIMUM_SIZE": "1000", + "KEY_USAGE_RETENTION_DAYS": "90", + "LOGIN_ATTEMPT_WINDOW_SECONDS": "900", + "LOGIN_LOCKOUT_BASE_SECONDS": "300", + "LOGIN_LOCKOUT_MAX_SECONDS": "3600", + "LOGIN_MAX_ATTEMPTS": "5", + "LOG_CONSOLE_ENABLED": "True", + "LOG_DEVELOPMENT_VERBOSE": "True", + "LOG_FILE_BACKUP_COUNT": "5", + "LOG_FILE_ENABLED": "False", + "LOG_FILE_MAX_SIZE": "10485760", + "LOG_FILE_PATH": "'logs/app.log'", + "LOG_FORMAT": "''", + "LOG_LEVEL": "'INFO'", + "LOG_PRODUCTION_OPTIMIZE": "True", + "MAX_SESSIONS_PER_USER": "5", + "OAUTH_GITHUB_CLIENT_ID": "''", + "OAUTH_GITHUB_CLIENT_SECRET": "''", + "OAUTH_GOOGLE_CLIENT_ID": "''", + "OAUTH_GOOGLE_CLIENT_SECRET": "''", + "OAUTH_REDIRECT_BASE_URL": "'http://localhost:8000'", + "OPENAPI_PREFIX": "''", + "OPENAPI_URL": "'/openapi.json'", + "PASSWORD_MIN_LENGTH": "8", + "PASSWORD_REQUIRE_DIGIT": "True", + "PASSWORD_REQUIRE_LOWERCASE": "True", + "PASSWORD_REQUIRE_SPECIAL": "True", + "PASSWORD_REQUIRE_UPPERCASE": "True", + "POSTGRES_ASYNC_PREFIX": "'postgresql+asyncpg://'", + "POSTGRES_DB": "'postgres'", + "POSTGRES_MAX_OVERFLOW": "0", + "POSTGRES_PASSWORD": "'postgres'", + "POSTGRES_POOL_PRE_PING": "True", + "POSTGRES_POOL_RECYCLE": "-1", + "POSTGRES_POOL_SIZE": "20", + "POSTGRES_PORT": "5432", + "POSTGRES_SERVER": "'postgres'", + "POSTGRES_USER": "'postgres'", + "PRODUCTION_SECURITY_VALIDATION_ENABLED": "True", + "RATE_LIMITER_BACKEND": "'redis'", + "RATE_LIMITER_ENABLED": "True", + "RATE_LIMITER_REDIS_CONNECT_TIMEOUT": "5", + "RATE_LIMITER_REDIS_DB": "1", + "RATE_LIMITER_REDIS_HOST": "'redis'", + "RATE_LIMITER_REDIS_PASSWORD": "''", + "RATE_LIMITER_REDIS_POOL_SIZE": "10", + "RATE_LIMITER_REDIS_PORT": "6379", + "REDOC_URL": "'/redoc'", + "SECRET_KEY": "'insecure-secret-key-change-this-in-production'", + "SECURITY_HEADERS_ENABLED": "True", + "SESSION_ABSOLUTE_TIMEOUT_HOURS": "None", + "SESSION_BACKEND": "'redis'", + "SESSION_CLEANUP_INTERVAL_MINUTES": "15", + "SESSION_REDIS_DB": "2", + "SESSION_REDIS_HOST": "'redis'", + "SESSION_REDIS_PASSWORD": "''", + "SESSION_REDIS_PORT": "6379", + "SESSION_REDIS_URL_OVERRIDE": "None", + "SESSION_SECURE_COOKIES": "True", + "SESSION_TIMEOUT_MINUTES": "30", + "TASKIQ_BROKER_TYPE": "'redis'", + "TASKIQ_DEFAULT_RETRY_COUNT": "3", + "TASKIQ_RABBITMQ_HOST": "'localhost'", + "TASKIQ_RABBITMQ_PASSWORD": "'guest'", + "TASKIQ_RABBITMQ_PORT": "5672", + "TASKIQ_RABBITMQ_USER": "'guest'", + "TASKIQ_RABBITMQ_VHOST": "'/'", + "TASKIQ_REDIS_DB": "3", + "TASKIQ_REDIS_HOST": "'redis'", + "TASKIQ_REDIS_PASSWORD": "''", + "TASKIQ_REDIS_PORT": "6379", + "TASKIQ_RETRY_DELAY_SECONDS": "0", + "TRUSTED_PROXY_HOPS": "0", + "VERSION": "'0.1.0'" +} \ No newline at end of file diff --git a/backend/tests/unit/infrastructure/config/test_env_file.py b/backend/tests/unit/infrastructure/config/test_env_file.py index 019c5e7e..38931d2c 100644 --- a/backend/tests/unit/infrastructure/config/test_env_file.py +++ b/backend/tests/unit/infrastructure/config/test_env_file.py @@ -5,23 +5,13 @@ operator command the image runs. """ -import importlib import logging import os import warnings -import pytest - import src.infrastructure.config.base as base -@pytest.fixture -def reloaded(): - """Re-import the module under the test's conditions, and put it back afterwards.""" - yield lambda: importlib.reload(base) - importlib.reload(base) - - def test_with_no_environment_file_nothing_warns(reloaded, monkeypatch, caplog): """Starlette warns about a file it was handed and could not find, so it is handed none.""" monkeypatch.setattr(os.path, "isfile", lambda path: False) @@ -37,10 +27,8 @@ def test_with_no_environment_file_nothing_warns(reloaded, monkeypatch, caplog): assert "settings are read from the environment" in caplog.text -def test_an_environment_file_that_exists_is_the_one_read(reloaded, monkeypatch, tmp_path, caplog): - stored = tmp_path / ".env" - stored.write_text("ENVIRONMENT=local\n") - monkeypatch.setattr(base.os.path, "realpath", lambda path: str(tmp_path / "src" / "infrastructure" / "config" / "base.py")) +def test_an_environment_file_that_exists_is_the_one_read(reloaded, found_file, monkeypatch, caplog): + stored = found_file monkeypatch.delenv("PYTEST_VERSION", raising=False) monkeypatch.delenv("PYTEST_CURRENT_TEST", raising=False) diff --git a/backend/tests/unit/infrastructure/config/test_settings.py b/backend/tests/unit/infrastructure/config/test_settings.py index d736458c..ad265146 100644 --- a/backend/tests/unit/infrastructure/config/test_settings.py +++ b/backend/tests/unit/infrastructure/config/test_settings.py @@ -127,14 +127,6 @@ def test_required_settings_exist(self): assert hasattr(settings, attr), f"Missing required setting: {attr}" assert getattr(settings, attr) is not None, f"Setting {attr} is None" - @patch.dict(os.environ, {"SQLITE_URI": ":memory:"}) - def test_test_database_override(self): - """Test that test database settings work.""" - settings = Settings() - # In test mode, should use in-memory database - if hasattr(settings, "SQLITE_URI"): - assert ":memory:" in settings.SQLITE_URI - class TestCORSSettings: """Credentialed requests reject a wildcard origin, so the default must not be one.""" diff --git a/backend/tests/unit/infrastructure/config/test_settings_build.py b/backend/tests/unit/infrastructure/config/test_settings_build.py new file mode 100644 index 00000000..476aacd7 --- /dev/null +++ b/backend/tests/unit/infrastructure/config/test_settings_build.py @@ -0,0 +1,212 @@ +"""Settings read the environment and the environment file when they're built, not when imported.""" + +from pathlib import Path +from typing import Any + +import pytest +from pydantic import ValidationError +from pydantic_settings import BaseSettings + +import src.infrastructure.config.base as base +import src.infrastructure.config.settings as facade +from src.infrastructure.config.base import CoreSettings, EnvironmentOption, SecuritySettings +from src.infrastructure.config.settings import Settings + + +def test_a_variable_deleted_after_import_falls_back_to_the_default(reloaded, monkeypatch: pytest.MonkeyPatch): + monkeypatch.delenv("SECRET_KEY", raising=False) + default = base.SecuritySettings().SECRET_KEY + monkeypatch.setenv("SECRET_KEY", "set-before-the-import-" + "x" * 32) + reloaded() + + monkeypatch.delenv("SECRET_KEY") + + assert base.SecuritySettings().SECRET_KEY == default + + +def test_the_file_found_is_read_when_the_settings_are_built(reloaded, found_file: Path, monkeypatch: pytest.MonkeyPatch): + found = found_file + monkeypatch.delenv("PYTEST_VERSION", raising=False) + monkeypatch.delenv("PYTEST_CURRENT_TEST", raising=False) + monkeypatch.delenv("APP_NAME", raising=False) + reloaded() + + found.write_text("APP_NAME=Written After The Import\n") + + assert base.AppSettings().APP_NAME == "Written After The Import" + + +def test_no_file_is_read_under_pytest(reloaded, found_file: Path, monkeypatch: pytest.MonkeyPatch): + found = found_file + found.write_text("APP_NAME=Only The File Says So\n") + monkeypatch.setenv("PYTEST_VERSION", "set") + monkeypatch.delenv("APP_NAME", raising=False) + reloaded() + + assert base.EnvSettings.model_config["env_file"] is None + assert base.AppSettings().APP_NAME != "Only The File Says So" + + +def test_the_file_is_read_literally_as_it_always_was(monkeypatch: pytest.MonkeyPatch, tmp_path: Path): + """A secret with `${...}` in it stays as written; a `#` is part of the value; `export` lines and + names in another case aren't the setting.""" + for name in ("SECRET_KEY", "APP_NAME", "APP_DESCRIPTION"): + monkeypatch.delenv(name, raising=False) + stored = tmp_path / ".env" + stored.write_text( + "SECRET_KEY=ab${HOME}cd-long-enough-to-be-a-key-0123456789\n" + "APP_NAME=foo # not a comment\n" + "export APP_DESCRIPTION=exported\n" + "app_description=lower\n" + ) + built = Settings(_env_file=stored) + + assert built.SECRET_KEY == "ab${HOME}cd-long-enough-to-be-a-key-0123456789" + assert built.APP_NAME == "foo # not a comment" + assert built.APP_DESCRIPTION == Settings.model_fields["APP_DESCRIPTION"].default + + +def test_the_environment_wins_over_the_file(monkeypatch: pytest.MonkeyPatch, tmp_path: Path): + stored = tmp_path / ".env" + stored.write_text("APP_NAME=From The File\n") + monkeypatch.setenv("APP_NAME", "From The Environment") + + assert Settings(_env_file=stored).APP_NAME == "From The Environment" + + +def test_a_partial_class_ignores_the_names_other_classes_read(tmp_path: Path): + stored = tmp_path / ".env" + stored.write_text("POSTGRES_USER=elsewhere\n") + + SecuritySettings(_env_file=stored) + + +def test_a_misspelt_name_handed_to_the_constructor_is_refused(): + misspelt: dict[str, Any] = {"SECRET_KEYY": "x"} + + with pytest.raises(ValidationError): + Settings(**misspelt) + + +def test_a_bad_environment_is_reported_without_the_other_settings(monkeypatch: pytest.MonkeyPatch): + monkeypatch.setenv("ENVIRONMENT", "prod") + monkeypatch.setenv("SECRET_KEY", "a-secret-nobody-should-see-0123456789abcdef") + + with pytest.raises(ValidationError) as refused: + CoreSettings() + + assert [error["loc"] for error in refused.value.errors()] == [("ENVIRONMENT",)] + assert "a-secret-nobody-should-see" not in str(refused.value) + assert "a-secret-nobody-should-see" not in str(refused.value.errors()) + + +@pytest.mark.parametrize( + ("environment", "creates"), + [(EnvironmentOption.LOCAL, True), (EnvironmentOption.DEVELOPMENT, True), (EnvironmentOption.PRODUCTION, False)], +) +def test_tables_are_created_on_startup_by_default_where_the_environment_builds_them( + environment: EnvironmentOption, creates: bool, monkeypatch: pytest.MonkeyPatch +): + monkeypatch.delenv("CREATE_TABLES_ON_STARTUP", raising=False) + monkeypatch.setenv("ENVIRONMENT", environment.value) + + assert Settings().CREATE_TABLES_ON_STARTUP is creates + + +def test_tables_follow_the_environment_the_settings_are_built_with(monkeypatch: pytest.MonkeyPatch): + monkeypatch.delenv("CREATE_TABLES_ON_STARTUP", raising=False) + monkeypatch.setenv("ENVIRONMENT", "local") + + assert Settings(ENVIRONMENT=EnvironmentOption.PRODUCTION).CREATE_TABLES_ON_STARTUP is False + + +def test_settings_constructed_without_validation_still_follow_the_process_environment(monkeypatch: pytest.MonkeyPatch): + monkeypatch.setenv("ENVIRONMENT", "production") + + assert Settings.model_construct().CREATE_TABLES_ON_STARTUP is False + + +@pytest.mark.parametrize(("written", "read"), [("true", True), ("TRUE", True), ("1", True), ("false", False), ("0", False)]) +def test_a_flag_reads_the_spellings_it_always_did(written: str, read: bool, monkeypatch: pytest.MonkeyPatch): + monkeypatch.setenv("SECURITY_HEADERS_ENABLED", written) + + assert SecuritySettings().SECURITY_HEADERS_ENABLED is read + + +@pytest.mark.parametrize("written", ["yes", "on", "off", "t", ""]) +def test_a_flag_refuses_a_spelling_it_never_read(written: str, monkeypatch: pytest.MonkeyPatch): + monkeypatch.setenv("SECURITY_HEADERS_ENABLED", written) + + with pytest.raises(ValidationError): + SecuritySettings() + + +@pytest.mark.parametrize(("written", "read"), [("30", 30), (" 30", 30), ("1_000", 1000), ("+5", 5)]) +def test_a_number_reads_what_int_reads(written: str, read: int, monkeypatch: pytest.MonkeyPatch): + monkeypatch.setenv("POSTGRES_POOL_SIZE", written) + + assert CoreSettings().POSTGRES_POOL_SIZE == read + + +@pytest.mark.parametrize("written", ["1.0", "30.5", "thirty"]) +def test_a_number_refuses_what_int_refuses(written: str, monkeypatch: pytest.MonkeyPatch): + monkeypatch.setenv("POSTGRES_POOL_SIZE", written) + + with pytest.raises(ValidationError): + CoreSettings() + + +def test_a_flag_in_the_file_is_held_to_the_same_spellings(monkeypatch: pytest.MonkeyPatch, tmp_path: Path): + monkeypatch.delenv("SECURITY_HEADERS_ENABLED", raising=False) + stored = tmp_path / ".env" + stored.write_text("SECURITY_HEADERS_ENABLED=yes\n") + + with pytest.raises(ValidationError): + SecuritySettings(_env_file=stored) + + +def test_a_class_written_the_old_way_still_composes_and_reads_its_variable(monkeypatch: pytest.MonkeyPatch): + """`config` stays exported, so a project's own class written with it keeps working.""" + + class OldStyle(BaseSettings): + OLD_STYLE_VALUE: str = facade.config("OLD_STYLE_VALUE", default="declared") + + class Composed(OldStyle, CoreSettings): + pass + + monkeypatch.setenv("OLD_STYLE_VALUE", "from the environment") + + assert Composed().OLD_STYLE_VALUE == "from the environment" + + +class _Probe(base.EnvSettings): + PROBE_LIMIT: int | None = None + PROBE_FLAG: bool | None = None + PROBE_IDS: list[int] = [] + + +@pytest.mark.parametrize("written", ["1.0", ""]) +def test_an_optional_number_refuses_what_int_refuses(written: str, monkeypatch: pytest.MonkeyPatch): + monkeypatch.setenv("PROBE_LIMIT", written) + + with pytest.raises(ValidationError): + _Probe() + + +def test_an_optional_flag_is_held_to_the_same_spellings(monkeypatch: pytest.MonkeyPatch): + monkeypatch.setenv("PROBE_FLAG", "yes") + + with pytest.raises(ValidationError): + _Probe() + + +def test_a_list_of_numbers_is_left_to_pydantic(): + with pytest.raises(ValidationError) as refused: + _Probe(PROBE_IDS="[1, 2]") + + assert [error["type"] for error in refused.value.errors()] == ["list_type"] + + +def test_a_string_handed_to_the_constructor_is_held_to_the_same_rule(): + with pytest.raises(ValidationError): + SecuritySettings(SECURITY_HEADERS_ENABLED="yes") diff --git a/backend/tests/unit/infrastructure/config/test_settings_tables.py b/backend/tests/unit/infrastructure/config/test_settings_tables.py new file mode 100644 index 00000000..ed29f05d --- /dev/null +++ b/backend/tests/unit/infrastructure/config/test_settings_tables.py @@ -0,0 +1,38 @@ +"""Every setting has the value it had before settings read the environment at build time. + +The tables were written from the blueprint repo, where every feature is selected, so this file +stays in the blueprint. +""" + +import json +import os +from pathlib import Path +from unittest.mock import patch + +import pytest + +from src.infrastructure.config.settings import Settings + +HERE = Path(__file__).resolve().parent +ENV_EXAMPLE = HERE.parents[3] / ".env.example" +DEFAULTS = json.loads((HERE / "defaults.json").read_text()) +"""Every field's value with nothing set.""" +EXAMPLE_VALUES = json.loads((HERE / "example_values.json").read_text()) +"""Every field's value with `backend/.env.example` as the environment file and nothing else set.""" + + +def test_the_tables_are_every_field(): + assert sorted(DEFAULTS) == sorted(Settings.model_fields) + assert sorted(EXAMPLE_VALUES) == sorted(Settings.model_fields) + + +@pytest.mark.parametrize("name", sorted(DEFAULTS)) +def test_every_default_is_the_one_it_was(name: str): + with patch.dict(os.environ, {}, clear=True): + assert repr(getattr(Settings(), name)) == DEFAULTS[name] + + +@pytest.mark.parametrize("name", sorted(EXAMPLE_VALUES)) +def test_every_value_the_example_gives_is_the_one_it_gave(name: str): + with patch.dict(os.environ, {}, clear=True): + assert repr(getattr(Settings(_env_file=ENV_EXAMPLE), name)) == EXAMPLE_VALUES[name] diff --git a/backend/tests/unit/infrastructure/email/test_senders.py b/backend/tests/unit/infrastructure/email/test_senders.py index 4795369f..76706abe 100644 --- a/backend/tests/unit/infrastructure/email/test_senders.py +++ b/backend/tests/unit/infrastructure/email/test_senders.py @@ -2,8 +2,13 @@ import asyncio import logging +import smtplib +import socket import ssl +import threading +import time import warnings +from collections.abc import Callable from typing import Any import httpx @@ -21,6 +26,12 @@ LINK = "https://app.example.com/reset-password?token=the-signed-token" BODY = f"Someone asked to reset your password. Use this link: {LINK}" +WAIT = 120 +"""Seconds Mailpit gets to come up and to answer each call, on a machine busy with other suites.""" + +ATTEMPT = 5 +"""Seconds one attempt to reach Mailpit gets before the wait tries again.""" + async def _send_the_reset_email(sender: EmailSender) -> None: """One message, as crudauth hands it over.""" @@ -33,6 +44,26 @@ async def _send_the_reset_email(sender: EmailSender) -> None: ) +def _greets(host: str, port: int, timeout: float = ATTEMPT) -> None: + """Return once an SMTP server at `host:port` has greeted and answered a NOOP.""" + with smtplib.SMTP(host, port, timeout=timeout) as server: + server.noop() + + +def _until(check: Callable[[], object], within: float) -> None: + """Call `check` until it returns, retrying a refused or failed connection, and raise its + last error once `within` seconds have passed.""" + deadline = time.monotonic() + within + while True: + try: + check() + return + except (OSError, smtplib.SMTPException, httpx.HTTPError): + if time.monotonic() >= deadline: + raise + time.sleep(0.2) + + @pytest.fixture(scope="module") def mailpit(): """A real SMTP server of this module's own, with an API to read what arrived.""" @@ -44,6 +75,9 @@ def mailpit(): container = MailpitContainer().start() try: + api = container.get_base_api_url() + _until(lambda: _greets(container.get_container_host_ip(), container.get_exposed_smtp_port()), WAIT) + _until(lambda: httpx.get(f"{api}/api/v1/info", timeout=ATTEMPT).raise_for_status(), WAIT) yield container finally: container.stop() @@ -58,16 +92,16 @@ def _smtp_sender(mailpit: MailpitContainer, starttls: bool) -> SmtpSender: user="mailer", password="secret", starttls=starttls, - timeout=10, + timeout=WAIT, ) def _delivered(mailpit: MailpitContainer) -> dict[str, Any]: """The one message Mailpit is holding, with its body.""" api = mailpit.get_base_api_url() - listed = httpx.get(f"{api}/api/v1/messages", timeout=10).json()["messages"] + listed = httpx.get(f"{api}/api/v1/messages", timeout=WAIT).json()["messages"] assert len(listed) == 1, listed - message: dict[str, Any] = httpx.get(f"{api}/api/v1/message/{listed[0]['ID']}", timeout=10).json() + message: dict[str, Any] = httpx.get(f"{api}/api/v1/message/{listed[0]['ID']}", timeout=WAIT).json() return message @@ -100,6 +134,55 @@ async def test_starttls_will_not_talk_to_a_server_it_cannot_verify(mailpit: Mail await _send_the_reset_email(_smtp_sender(mailpit, starttls=True)) +def _serve_smtp_after(delay: float) -> tuple[int, list[bytes], threading.Thread]: + """A port where a minimal SMTP server starts listening only after `delay` seconds, the + commands it receives, and its thread, which ends after one session or 2 idle seconds.""" + with socket.socket() as probe: + probe.bind(("127.0.0.1", 0)) + port: int = probe.getsockname()[1] + received: list[bytes] = [] + + def serve() -> None: + time.sleep(delay) + with socket.create_server(("127.0.0.1", port)) as server: + server.settimeout(2) + try: + connection, _ = server.accept() + except TimeoutError: + return + with connection, connection.makefile("rwb") as stream: + stream.write(b"220 ready\r\n") + stream.flush() + for line in stream: + received.append(line.strip().upper()) + stream.write(b"221 bye\r\n" if line.upper().startswith(b"QUIT") else b"250 ok\r\n") + stream.flush() + + thread = threading.Thread(target=serve, daemon=True) + thread.start() + + return port, received, thread + + +def test_the_wait_returns_once_a_server_that_starts_late_answers_a_noop(): + port, received, thread = _serve_smtp_after(0.5) + + _until(lambda: _greets("127.0.0.1", port), within=10) + thread.join(10) + + assert b"NOOP" in received + + +def test_the_wait_gives_up_with_the_last_error(): + port, _, thread = _serve_smtp_after(2) + + with pytest.raises(ConnectionRefusedError): + _until(lambda: _greets("127.0.0.1", port), within=0.3) + thread.join(10) + + assert not thread.is_alive() + + class _GatedSender(EmailSender): """Delivers only once it is let go, and records what it delivered.""" diff --git a/backend/tests/unit/infrastructure/security/test_production_validator.py b/backend/tests/unit/infrastructure/security/test_production_validator.py index c429be50..435d2f65 100644 --- a/backend/tests/unit/infrastructure/security/test_production_validator.py +++ b/backend/tests/unit/infrastructure/security/test_production_validator.py @@ -610,7 +610,8 @@ def test_the_email_settings_are_left_alone_without_the_accounts_feature(self): def test_the_core_checks_still_run(self): """Dropping features must not drop the checks that hold for every project.""" - validator = ProductionSecurityValidator(cast(Settings, CoreSettings(ENVIRONMENT=EnvironmentOption.PRODUCTION))) + settings = CoreSettings(ENVIRONMENT=EnvironmentOption.PRODUCTION, SECRET_KEY="change-me") + validator = ProductionSecurityValidator(cast(Settings, settings)) errors = validator._validate_critical_security() @@ -638,7 +639,7 @@ def test_every_generated_key_is_accepted(self, shape): The rules do refuse a few generated keys: one hex key in 12.6 million runs through eight consecutive digits, and a ``token_urlsafe`` key walks neighbouring keys over 0.6 of its length at around one in ten million (one - such key in a 10,000,000 sample, none in a second). ``bp env gen-secret`` + such key in a 10,000,000 sample, none in a second). ``fastro env secret`` draws again rather than printing those, and the seed here is fixed so that this sweep states what the rules do instead of drawing a lottery. """ diff --git a/backend/tests/unit/modules/user/test_service.py b/backend/tests/unit/modules/user/test_service.py index 086a81e9..267a3c88 100644 --- a/backend/tests/unit/modules/user/test_service.py +++ b/backend/tests/unit/modules/user/test_service.py @@ -146,6 +146,46 @@ async def test_signup_cannot_write_the_verification_or_oauth_columns(user_servic assert created["oauth_provider"] is None +async def test_what_each_feature_sets_on_a_new_account_is_written_the_later_over_the_earlier( + user_service: UserService, db_session: AsyncSession, monkeypatch +): + """The account's own fields win over any of them, and none sets a column crudauth owns, + as on a provider's first sign-in.""" + given: list[AsyncSession] = [] + written: list[dict[str, Any]] = [] + + async def first(db: AsyncSession) -> dict[str, Any]: + given.append(db) + return { + "first_column": 1, + "shared_column": "first", + "name": "Someone Else", + "is_superuser": True, + "email_verified": True, + "oauth_provider": "google", + } + + async def second(db: AsyncSession) -> dict[str, Any]: + return {"second_column": 2, "shared_column": "second"} + + async def recording(*, db: AsyncSession, object: Any, schema_to_select: Any) -> dict[str, Any]: + written.append(object.model_dump()) + return {"id": 1} + + monkeypatch.setattr(service_module, "NEW_ACCOUNT_FIELDS", (first, second)) + monkeypatch.setattr(crud_users, "create", recording) + + await user_service.create( + UserCreate(name="Owner", username="contributed", email="contributed@example.com", password="Str1ngst!"), db_session + ) + + (row,) = written + assert given == [db_session] + assert (row["first_column"], row["second_column"], row["shared_column"]) == (1, 2, "second") + assert (row["name"], row["username"], row["email"]) == ("Owner", "contributed", "contributed@example.com") + assert (row.get("is_superuser"), row["email_verified"], row["oauth_provider"]) == (None, False, None) + + # ============================================================================= # Which credential was taken decides how a signup answers # ============================================================================= diff --git a/backend/tests/unit/modules/user/test_signup_route.py b/backend/tests/unit/modules/user/test_signup_route.py new file mode 100644 index 00000000..61c679b2 --- /dev/null +++ b/backend/tests/unit/modules/user/test_signup_route.py @@ -0,0 +1,12 @@ +"""The signup route says where other features set what they add to a new account.""" + +from src.interfaces.main import app +from src.wiring import signup + + +def test_the_signup_route_names_the_wiring_a_new_account_takes_other_features_columns_from(): + description = app.openapi()["paths"]["/api/v1/users/"]["post"]["description"] + + assert signup.__file__.endswith("src/wiring/signup.py") + assert "`src/wiring/signup.py`" in description + assert "tier" not in description.lower() diff --git a/backend/tests/unit/scripts/test_baseline.py b/backend/tests/unit/scripts/test_baseline.py new file mode 100644 index 00000000..0a5d362e --- /dev/null +++ b/backend/tests/unit/scripts/test_baseline.py @@ -0,0 +1,273 @@ +"""What the baseline writes, what it refuses, and what it leaves behind. + +The container and alembic are mocked, so the suite needs no Docker: what is checked here is +the script's own reasoning. The revision it writes has to be the baseline rather than any +revision, and ``--check`` has to leave ``migrations/versions/`` exactly as it found it, since +that is the mode `fastro verify` runs in a project it has just generated. +""" + +import os +import subprocess +import sys +from collections.abc import Iterator +from pathlib import Path +from typing import Any + +import pytest + +from scripts import baseline +from src.infrastructure.database.session import Base + +HOST = "127.0.0.1" +PORT = 54321 + +BACKEND = Path(baseline.__file__).resolve().parents[1] + + +class _Container: + """The pieces of a ``PostgresContainer`` the script reads.""" + + username = "baseline-user" + password = "baseline-password" + dbname = "baseline-db" + + def __init__(self, image: str): + self.image = image + + def __enter__(self) -> "_Container": + return self + + def __exit__(self, *exception: Any) -> None: + return None + + def get_container_host_ip(self) -> str: + return HOST + + def get_exposed_port(self, port: int) -> int: + return PORT + + +class _Alembic: + """Alembic as the script calls it: a recorder that writes the revision autogenerate would.""" + + def __init__(self, versions: Path, *, revision: str = "0a1b2c3d4e5f", slug: str | None = None, failing: str | None = None): + self.versions = versions + self.revision = revision + self.slug = slug + self.failing = failing + self.calls: list[tuple[str, ...]] = [] + self.environments: list[dict[str, str]] = [] + + def __call__(self, *arguments: str) -> subprocess.CompletedProcess[str]: + self.calls.append(arguments) + self.environments.append(dict(os.environ)) + if self.failing == arguments[0]: + return subprocess.CompletedProcess(list(arguments), 1, "", f"{arguments[0]} went wrong") + + if arguments[0] == "revision": + slug = self.slug or arguments[arguments.index("-m") + 1] + (self.versions / f"{self.revision}_{slug}.py").write_text(f'revision = "{self.revision}"\n') + + return subprocess.CompletedProcess(list(arguments), 0, "", "") + + +@pytest.fixture +def versions(tmp_path: Path, monkeypatch) -> Path: + directory = tmp_path / "versions" + directory.mkdir() + monkeypatch.setattr(baseline, "VERSIONS", directory) + + return directory + + +@pytest.fixture(autouse=True) +def _restored_environment() -> Iterator[None]: + """The script writes the container's details into the environment, as alembic reads them.""" + before = dict(os.environ) + + yield + + os.environ.clear() + os.environ.update(before) + + +@pytest.fixture +def container(monkeypatch) -> None: + monkeypatch.setattr(baseline, "PostgresContainer", _Container) + + +@pytest.fixture +def alembic(versions, monkeypatch) -> _Alembic: + """Alembic itself is never run: what it would do to the tree is what the script reasons about.""" + recorder = _Alembic(versions) + monkeypatch.setattr(baseline, "alembic", recorder) + + return recorder + + +def _schema_of(declared: dict[str, list[str]]): + async def read(url: str) -> dict[str, list[str]]: + return declared + + return read + + +@pytest.fixture +def matching(monkeypatch) -> None: + """A database the baseline left holding exactly what the models declare.""" + monkeypatch.setattr(baseline, "created_schema", _schema_of(baseline.declared_schema())) + + +def _written(versions: Path) -> dict[str, str]: + return {path.name: path.read_text() for path in versions.glob("*.py")} + + +def test_it_writes_one_revision_named_after_the_baseline(versions, container, matching, alembic, capsys): + code = baseline.main([]) + + assert code == 0, capsys.readouterr() + assert list(_written(versions)) == ["0a1b2c3d4e5f_baseline.py"] + assert "tables" in capsys.readouterr().out + + +def test_it_autogenerates_the_baseline_and_applies_it(versions, container, matching, alembic): + baseline.main([]) + + assert alembic.calls == [("revision", "--autogenerate", "-m", "baseline"), ("upgrade", "head")] + + +def test_check_leaves_the_versions_directory_as_it_found_it(versions, container, matching, alembic): + before = _written(versions) + + code = baseline.main(["--check"]) + + assert code == 0 + assert _written(versions) == before + assert ("revision", "--autogenerate", "-m", "baseline") in alembic.calls + + +def test_the_commands_run_against_the_container(versions, container, matching, alembic): + baseline.main([]) + + environment = alembic.environments[0] + assert environment["POSTGRES_SERVER"] == HOST + assert environment["POSTGRES_PORT"] == str(PORT) + assert environment["POSTGRES_USER"] == _Container.username + assert environment["POSTGRES_PASSWORD"] == _Container.password + assert environment["POSTGRES_DB"] == _Container.dbname + assert environment["DATABASE_URL"] == "", "a configured URL wins over these, and names the real database" + + +def test_a_database_the_models_do_not_declare_is_refused(versions, container, alembic, monkeypatch, capsys): + """The table named here is one no project declares, so it is a mismatch whatever is selected.""" + monkeypatch.setattr(baseline, "created_schema", _schema_of({"alembic_version": [], "nothing_declares_this": []})) + + code = baseline.main(["--check"]) + + printed = capsys.readouterr() + assert code == 1 + assert "while the models declare" in printed.err + assert _written(versions) == {} + + +def test_a_failed_autogenerate_is_reported_with_what_alembic_printed(versions, container, matching, monkeypatch, capsys): + monkeypatch.setattr(baseline, "alembic", _Alembic(versions, failing="revision")) + + code = baseline.main([]) + + printed = capsys.readouterr() + assert code == 1 + assert "revision went wrong" in printed.err + assert _written(versions) == {} + + +def test_a_failed_upgrade_is_withdrawn_under_check(versions, container, matching, monkeypatch, capsys): + monkeypatch.setattr(baseline, "alembic", _Alembic(versions, failing="upgrade")) + + code = baseline.main(["--check"]) + + printed = capsys.readouterr() + assert code == 1 + assert "upgrade went wrong" in printed.err + assert _written(versions) == {} + + +def test_a_revision_that_is_not_the_baseline_is_refused(versions, container, matching, monkeypatch, capsys): + """Alembic names the file after its own slug, and a project's first revision is the baseline.""" + monkeypatch.setattr(baseline, "alembic", _Alembic(versions, slug="add_a_column")) + + code = baseline.main(["--check"]) + + assert code == 1 + assert "is not the baseline" in capsys.readouterr().err + + +def test_a_project_that_already_has_a_history_is_refused(versions, container, matching, alembic, capsys): + (versions / "f5e4d3c2b1a0_add_a_column.py").write_text('revision = "f5e4d3c2b1a0"\n') + before = _written(versions) + + code = baseline.main([]) + + printed = capsys.readouterr() + assert code == 1 + assert "f5e4d3c2b1a0_add_a_column.py" in printed.err + assert _written(versions) == before + + +def test_the_declared_schema_is_the_one_the_models_build(versions): + """The tables are the ones this project's features declare, read rather than listed. + + A project without accounts has no `user`, and one with no features has only alembic's own, + which the script adds because a baseline creates the table alembic records itself in. + """ + declared = baseline.declared_schema() + + assert declared["alembic_version"] == [] + assert set(declared) == set(Base.metadata.tables) | {"alembic_version"} + assert all(indexes == sorted(indexes) for indexes in declared.values()) + + +_COLD_SCHEMA = """ +from scripts.baseline import declared_schema + +print(sorted(name for name in declared_schema() if name != "alembic_version")) +""" + + +def test_the_script_imports_the_models_itself(): + """Only a cold interpreter can tell: in the suite, `tests/conftest.py` has imported the app, + which imports every model, so the metadata is already full whatever the script does. + + A project that declares no models of its own cannot tell an import that did nothing from one + that worked, so it skips rather than passing for the wrong reason. + """ + declared = sorted(Base.metadata.tables) + if not declared: + pytest.skip("this project declares no models, so a missing import looks like a working one") + + result = subprocess.run( + [sys.executable, "-c", _COLD_SCHEMA], + cwd=BACKEND, + env={**os.environ, "PYTHONPATH": str(BACKEND)}, + capture_output=True, + text=True, + timeout=120, + ) + + assert result.returncode == 0, result.stdout + result.stderr + assert result.stdout.strip().splitlines()[-1] == str(declared), "the settings log to stdout before it prints" + + +def test_running_it_as_a_module_takes_the_check_flag(): + """``--check`` is what verify runs, so an argument parser that refuses it is a broken verify.""" + result = subprocess.run( + [sys.executable, "-m", "scripts.baseline", "--help"], + cwd=BACKEND, + capture_output=True, + text=True, + env={**os.environ, "PYTHONPATH": str(BACKEND)}, + timeout=120, + ) + + assert result.returncode == 0, result.stdout + result.stderr + assert "--check" in result.stdout diff --git a/backend/tests/unit/scripts/test_gen_secret.py b/backend/tests/unit/scripts/test_gen_secret.py new file mode 100644 index 00000000..baa4dd44 --- /dev/null +++ b/backend/tests/unit/scripts/test_gen_secret.py @@ -0,0 +1,101 @@ +"""The key the script prints, and why it sometimes draws more than once. + +``SECRET_KEY`` is refused at startup in production when the project's own rules read it as +something a person typed. A generator that printed such a key would send you into that +refusal, so it draws again while the rules refuse what it drew. +""" + +import os +import subprocess +import sys +from pathlib import Path + +import pytest + +from scripts.gen_secret import generate +from src.infrastructure.config.settings import EnvironmentOption, Settings +from src.infrastructure.security.production_validator import ProductionSecurityValidator +from src.infrastructure.security.secret_key import is_weak_secret_key + +BACKEND = Path(__file__).resolve().parents[3] + +REFUSED = "e48102bfe6ac2eac3aa8623456789a6030e4fa7dee3cd173bfb7941f2f819678" +"""A hex key the rules refuse: it runs through eight consecutive digits.""" + + +def _run(*arguments: str) -> subprocess.CompletedProcess[str]: + """Run the script from ``backend/``, with nothing configured but the interpreter.""" + environment = { + "PATH": os.environ.get("PATH", "/usr/bin:/bin"), + "HOME": os.environ.get("HOME", "/tmp"), + "PYTHONPATH": str(BACKEND), + } + + return subprocess.run( + [sys.executable, *arguments], + cwd=BACKEND, + env=environment, + capture_output=True, + text=True, + timeout=60, + ) + + +def test_the_key_it_prints_is_one_the_validator_accepts(): + """The script is what an operator runs to satisfy the validator, so ask the validator.""" + key = generate() + + validator = ProductionSecurityValidator(Settings(SECRET_KEY=key, ENVIRONMENT=EnvironmentOption.PRODUCTION)) + + assert len(key) == 64 + assert not validator._is_insecure_secret_key() + + +def test_a_key_the_rules_refuse_is_drawn_again(monkeypatch): + """One hex key in twelve million runs through eight digits, which production refuses.""" + accepted = "7b1c9d4e2a6f8305b4c7e1d9f2a6b8c30d5e7f91a2b3c4d5e6f708192a3b4c5d" + draws = iter([REFUSED, accepted]) + monkeypatch.setattr("scripts.gen_secret.secrets.token_hex", lambda size: next(draws)) + + assert is_weak_secret_key(REFUSED) + assert generate() == accepted + + +def test_it_gives_up_after_the_draws_it_allows(monkeypatch): + """Drawing for ever would hang; the last draw is printed whatever the rules say.""" + monkeypatch.setattr("scripts.gen_secret.secrets.token_hex", lambda size: REFUSED) + + assert generate() == REFUSED + + +def test_the_byte_count_decides_the_length(): + assert len(generate(16)) == 32 + + +@pytest.mark.parametrize("invocation", [("scripts/gen_secret.py",), ("-m", "scripts.gen_secret")]) +def test_it_runs_the_way_the_documentation_runs_it(invocation: tuple[str, ...]): + """As a file from ``backend/``, and as a module, which is what the blueprint declares.""" + result = _run(*invocation) + + assert result.returncode == 0, result.stderr + assert len(result.stdout.strip()) == 64 + + +@pytest.mark.parametrize("count", ["8", "256", "many"]) +def test_a_byte_count_the_script_will_not_take_is_refused(count: str): + """A short key is one the rules would refuse anyway, and a usage error exits 2.""" + result = _run("scripts/gen_secret.py", "--bytes", count) + + assert result.returncode == 2 + assert result.stdout.strip() == "" + + +def test_it_prints_the_key_and_nothing_else(): + """The documented use pipes it (``| gh secret set SECRET_KEY``), so a log line would go too. + + Importing ``src.infrastructure.security`` configures logging, which writes to stdout. + """ + result = _run("-m", "scripts.gen_secret") + + assert result.stdout.count("\n") == 1 + assert len(result.stdout.strip()) == 64 diff --git a/backend/tests/unit/scripts/test_setup_initial_data.py b/backend/tests/unit/scripts/test_setup_initial_data.py index 5499a6da..4e1c5a62 100644 --- a/backend/tests/unit/scripts/test_setup_initial_data.py +++ b/backend/tests/unit/scripts/test_setup_initial_data.py @@ -42,8 +42,8 @@ async def an_empty_database(test_db_url: str): def _seed(url: str, **extra: str): """Run the script as an operator does, with the superuser settings a seeder needs. - The drill's copy of the project carries no ``.env``, so anything the script reads has - to be in the environment it is handed. + ``.env`` is git-ignored, so a checkout carries none, and anything the script reads has to + be in the environment it is handed. """ return run_script("setup_initial_data", script_environment(url, **ADMIN, **extra)) diff --git a/backend/tests/unit/scripts/test_validate_env.py b/backend/tests/unit/scripts/test_validate_env.py new file mode 100644 index 00000000..af6c8fae --- /dev/null +++ b/backend/tests/unit/scripts/test_validate_env.py @@ -0,0 +1,216 @@ +"""What the environment audit reports, and what it exits with. + +The audit answers one question: what would production refuse about this configuration? +It therefore reads the settings as production whatever ``ENVIRONMENT`` says, so that a +development or staging configuration is held to the same gate, and so that a finding that +names an environment names the one it was checked for. +""" + +import os +import secrets +import subprocess +import sys +from pathlib import Path +from typing import Any + +import pytest +from pydantic import AliasChoices + +from scripts.validate_env import audit, main +from src.infrastructure.config.settings import EnvironmentOption, Settings + +BACKEND = Path(__file__).resolve().parents[3] + +PRODUCTION_SHAPED: dict[str, Any] = { + "ENVIRONMENT": EnvironmentOption.PRODUCTION, + "CREATE_TABLES_ON_STARTUP": False, + "EMAIL_BACKEND": "smtp", + "EMAIL_SMTP_HOST": "smtp.example.com", + "FRONTEND_URL": "https://app.example.com", +} +"""The settings whose defaults describe development rather than the production these stand for.""" + + +def _settings(**overrides: Any) -> Settings: + return Settings(**(PRODUCTION_SHAPED | overrides)) + + +def _audited(monkeypatch, settings: Settings) -> None: + """Answer the script with these settings instead of the ones the environment holds.""" + monkeypatch.setattr("scripts.validate_env.get_settings", lambda: settings) + + +def _accepted_names() -> set[str]: + """Every name this project's settings take, a field's alias choices included. + + `SESSION_REDIS_PASSWORD` accepts `CACHE_REDIS_PASSWORD` as well, so a project with accounts + and no cache still takes that name and reads the session password from it. + """ + accepted = set() + for name, field in Settings.model_fields.items(): + accepted.add(name) + alias = field.validation_alias + if isinstance(alias, str): + accepted.add(alias) + elif isinstance(alias, AliasChoices): + accepted.update(choice for choice in alias.choices if isinstance(choice, str)) + + return accepted + + +def _strong() -> dict[str, Any]: + """A configuration production would accept, less whatever this project has no feature for. + + `Settings` forbids an input no field of its own takes, so a project without the cache, the + limiter or the admin panel refuses their settings rather than ignoring them. + """ + strong = { + "SECRET_KEY": secrets.token_hex(32), + "POSTGRES_PASSWORD": "a-strong-database-password", + "CORS_ORIGINS": "https://app.example.com", + "ADMIN_ENABLED": False, + "DEBUG": False, + "OPENAPI_URL": "", + "CACHE_REDIS_PASSWORD": "redis-password", + "RATE_LIMITER_REDIS_PASSWORD": "redis-password", + "SESSION_SECURE_COOKIES": True, + "SESSION_BACKEND": "redis", + "RATE_LIMITER_BACKEND": "redis", + } + + return {name: value for name, value in strong.items() if name in _accepted_names()} + + +def test_a_clean_configuration_says_so(monkeypatch, capsys): + _audited(monkeypatch, _settings(**_strong())) + + code = main() + + assert code == 0 + assert "No issues found" in capsys.readouterr().out + + +def test_a_weak_configuration_is_refused_and_named(monkeypatch, capsys): + """Settings the validator really refuses come out as critical findings that name them.""" + _audited(monkeypatch, _settings(SECRET_KEY="insecure-secret-key-change-this", POSTGRES_PASSWORD="postgres")) + + code = main() + + printed = capsys.readouterr().out + assert code == 1 + assert "SECRET_KEY" in printed + assert "Database is using default credentials" in printed + + +def test_warnings_are_reported_even_when_something_is_critical(monkeypatch, capsys): + """The warnings used to be computed only when nothing critical was found. + + Both findings are core: the placeholder key is critical and debug mode is a warning, so a + project with no features selected still produces one of each. + """ + _audited(monkeypatch, _settings(SECRET_KEY="insecure-secret-key-change-this", DEBUG=True)) + + code = main() + + printed = capsys.readouterr().out + assert code == 1 + assert "Critical (" in printed + assert "Warnings (" in printed + + +def test_warnings_alone_do_not_fail_the_audit(monkeypatch, capsys): + """A warning is something to look at, not something that would stop a boot. + + Debug mode rather than an unprotected cache: the cache is a feature, and this test runs in + projects that didn't select it. + """ + _audited(monkeypatch, _settings(**(_strong() | {"DEBUG": True}))) + + code = main() + + printed = capsys.readouterr().out + assert code == 0 + assert "Warnings (" in printed + assert "Critical (" not in printed + + +def test_every_finding_names_the_environment_it_is_checked_for(monkeypatch, capsys): + """Audited as production, a finding that names a development environment is a lie. + + The table-creation finding is the one asked for, because it is core: the email backend names + the environment too, but only a project with accounts has anything to email. + """ + _audited(monkeypatch, _settings(ENVIRONMENT=EnvironmentOption.DEVELOPMENT, CREATE_TABLES_ON_STARTUP=True)) + + main() + + printed = capsys.readouterr().out + assert "in production" in printed + assert "in development" not in printed + + +def test_the_audited_settings_carry_the_environment_as_the_app_reads_it(monkeypatch): + """The app factory and the logger read ``ENVIRONMENT.value``, which a plain string has not.""" + handed: list[Settings] = [] + _audited(monkeypatch, _settings(ENVIRONMENT=EnvironmentOption.DEVELOPMENT)) + + class _Validator: + def __init__(self, settings: Settings): + handed.append(settings) + + def audit(self) -> tuple[list[str], list[str]]: + return [], [] + + monkeypatch.setattr("scripts.validate_env.ProductionSecurityValidator", _Validator) + audit() + + assert handed[0].ENVIRONMENT.value == "production" + + +def _run(environment: dict[str, str]) -> subprocess.CompletedProcess[str]: + return subprocess.run( + [sys.executable, "-m", "scripts.validate_env"], + cwd=BACKEND, + env={ + "PATH": os.environ.get("PATH", "/usr/bin:/bin"), + "HOME": os.environ.get("HOME", "/tmp"), + "PYTEST_VERSION": os.environ.get("PYTEST_VERSION", "1"), + **environment, + }, + capture_output=True, + text=True, + timeout=120, + ) + + +@pytest.mark.parametrize(("key", "code"), [("placeholder", 1), ("drawn", 0)]) +def test_it_runs_as_a_module_and_exits_on_what_it_found(key: str, code: int): + """``python -m scripts.validate_env`` is what the blueprint declares as a command. + + The key is drawn here rather than in the parameter list, where it would land in the + test's id: ``pytest -n auto`` refuses a run whose workers collected different ids. + """ + secret = secrets.token_hex(32) if key == "drawn" else "insecure-secret-key-change-this" + environment = { + "PYTHONPATH": str(BACKEND), + "ENVIRONMENT": "development", + "SECRET_KEY": secret, + "POSTGRES_PASSWORD": "a-strong-database-password", + "CORS_ORIGINS": "https://app.example.com", + "ADMIN_ENABLED": "false", + "DEBUG": "false", + "OPENAPI_URL": "", + "CACHE_REDIS_PASSWORD": "redis-password", + "RATE_LIMITER_REDIS_PASSWORD": "redis-password", + "SESSION_SECURE_COOKIES": "true", + "CREATE_TABLES_ON_STARTUP": "false", + "EMAIL_BACKEND": "smtp", + "EMAIL_SMTP_HOST": "smtp.example.com", + "FRONTEND_URL": "https://app.example.com", + "SESSION_BACKEND": "redis", + "RATE_LIMITER_BACKEND": "redis", + } + + result = _run(environment) + + assert result.returncode == code, result.stdout + result.stderr diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py new file mode 100644 index 00000000..98aecbe7 --- /dev/null +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -0,0 +1,2799 @@ +"""The catalog describes this repository. + +`blueprint.toml` is read by fastro, which the repository root installs and the backend doesn't, +so nothing in this file imports it: the rules it checks are transcribed from the catalog spec, +and the facts it checks against are the repository's own files. +""" + +import ast +import functools +import importlib +import ipaddress +import itertools +import keyword +import re +import subprocess +import sys +import time +import tomllib +from collections.abc import Iterable +from importlib.metadata import packages_distributions, requires +from pathlib import Path +from typing import Any + +import pytest +import yaml +from packaging.requirements import Requirement + +from tests.conftest import is_docker_running + +REPO_ROOT = Path(__file__).resolve().parents[3] + +CATALOG = REPO_ROOT / "blueprint.toml" +BACKEND_PYPROJECT = REPO_ROOT / "backend" / "pyproject.toml" + +FEATURE_NAME = re.compile(r"^[a-z][a-z0-9_]*$") +"""Spec 1.2. Written out rather than imported, because the backend's tests don't import fastro.""" + +BLUEPRINT_NAME = re.compile(r"^[a-z][a-z0-9-]*$") + +SET_NAME = re.compile(r"^[a-z][a-z0-9_-]*$") +"""Spec 1.2. A preset or a verify set may carry a hyphen, which a feature name may not.""" + + +@functools.cache +def _catalog() -> dict[str, Any]: + with CATALOG.open("rb") as handle: + return tomllib.load(handle) + + +def test_the_catalog_parses(): + assert _catalog()["blueprint"]["name"] == "fastapi-boilerplate" + + +def test_it_names_itself_the_way_the_spec_allows(): + blueprint = _catalog()["blueprint"] + + assert BLUEPRINT_NAME.match(blueprint["name"]) + assert blueprint["schema"] == 1 + assert blueprint["python_root"] == "backend" + assert blueprint["import_root"] == "src" + + +def test_the_version_is_the_one_the_backend_ships(): + """FR002: a release tag is a blueprint release, so the two versions move together.""" + with BACKEND_PYPROJECT.open("rb") as handle: + backend = tomllib.load(handle) + + assert _catalog()["blueprint"]["version"] == backend["project"]["version"] + + +def test_development_builds_of_the_tool_can_read_it(): + """Spec 1.6: `0.1.0.dev0` sorts below `0.1`, so the lower bound has to name it.""" + assert _catalog()["blueprint"]["requires_fastro"] == ">=0.1.0.dev0,<0.2" + + +def _declared_specifiers(listing: str = "runtime") -> set[str]: + """Every specifier a project could install from this listing: the core's, each feature's, each + `when` block's, and, for the runtime one, each option's.""" + key = "dependencies" if listing == "runtime" else "dev_dependencies" + specifiers = set(_catalog()["blueprint"]["dependencies"][listing]) + for feature in _catalog()["features"].values(): + specifiers.update(feature.get(key, ())) + for block in feature.get("when", ()): + specifiers.update(block.get(key, ())) + for option in feature.get("options", {}).values() if listing == "runtime" else (): + for chosen in option.get("dependencies", {}).values(): + specifiers.update(chosen) + + return specifiers + + +def test_the_dependencies_a_project_could_install_are_the_ones_the_backend_declares(): + """This repo selects every feature, so the union of the declarations is the backend's own list. + + The specifiers are compared, not the distribution names, so a floor that moves in one file + and not the other is caught rather than averaged away. + """ + with BACKEND_PYPROJECT.open("rb") as handle: + backend = tomllib.load(handle) + + assert _declared_specifiers() == set(backend["project"]["dependencies"]) + assert _declared_specifiers("dev") == set(backend["project"]["optional-dependencies"]["dev"]) + + +FASTAPI_THE_APP_NEEDS = { + "get_flat_dependant": ("src/infrastructure/cache/utils.py", "0.140.7"), + "openapi_prefix": ("src/infrastructure/app_factory.py", "0.145.0"), +} +"""Each FastAPI name the app relies on, the file that uses it, and the first release without it.""" + + +def test_every_fastapi_a_project_could_install_is_one_the_app_can_import(): + """A project resolves its dependencies fresh, so the declared range, not the lock, decides which FastAPI it gets.""" + with (REPO_ROOT / "uv.lock").open("rb") as handle: + locked = next(package["version"] for package in tomllib.load(handle)["package"] if package["name"] == "fastapi") + ranges = [Requirement(specifier).specifier for specifier in _declared_specifiers() if _distribution(specifier) == "fastapi"] + + assert ranges + for name, (path, first_without) in FASTAPI_THE_APP_NEEDS.items(): + assert name in (REPO_ROOT / "backend" / path).read_text(), (name, path) + for allowed in ranges: + assert first_without not in allowed, (allowed, name) + for allowed in ranges: + assert "999.0" not in allowed, allowed + assert locked in allowed, (allowed, locked) + + +def _distribution(specifier: str) -> str: + """The distribution a PEP 508 specifier names, without its extras or its version.""" + return re.split(r"[\[<>=!~;]", specifier)[0].strip().lower().replace("_", "-") + + +@functools.cache +def _provided() -> dict[str, frozenset[str]]: + """The modules each installed distribution provides, which is what an import names: `faker` + is imported as `faker`, and `user-agents` as `user_agents`.""" + provided: dict[str, set[str]] = {} + for module, distributions in packages_distributions().items(): + for distribution in distributions: + provided.setdefault(_distribution(distribution), set()).add(module) + + return {name: frozenset(modules) for name, modules in provided.items()} + + +@functools.cache +def _module_imports(path: Path) -> frozenset[str]: + """Every module an absolute import in this file names, dotted as it is written.""" + found: set[str] = set() + for node in ast.walk(ast.parse(path.read_text())): + if isinstance(node, ast.Import): + found.update(alias.name for alias in node.names) + elif isinstance(node, ast.ImportFrom) and node.level == 0 and node.module: + found.add(node.module) + + return frozenset(found) + + +@functools.cache +def _imported(*directories: str, skipping: tuple[str, ...] = ()) -> frozenset[str]: + """Every top-level module imported under these directories of the python root, less the files + named in `skipping`, which are given relative to that root.""" + root = REPO_ROOT / _catalog()["blueprint"]["python_root"] + skipped = {root / name for name in skipping} + + return frozenset( + module.split(".")[0] + for directory in directories + for path in sorted((root / directory).rglob("*.py")) + if path not in skipped + for module in _module_imports(path) + ) + + +@functools.cache +def _imports_outright(path: Path) -> frozenset[str]: + """The top-level modules this file imports with no guard, counted statement by statement. + + One import of a module inside a `try` doesn't excuse another outside it: the unguarded one is + what runs first and what fails, so a module imported both ways is imported outright. + """ + tree = ast.parse(path.read_text()) + guarded = { + id(inner) + for node in ast.walk(tree) + if isinstance(node, ast.Try) + for inner in ast.walk(node) + if isinstance(inner, ast.Import | ast.ImportFrom) + } + + found: set[str] = set() + for node in ast.walk(tree): + if id(node) in guarded: + continue + + if isinstance(node, ast.Import): + found.update(alias.name.split(".")[0] for alias in node.names) + elif isinstance(node, ast.ImportFrom) and node.level == 0 and node.module: + found.add(node.module.split(".")[0]) + + return frozenset(found) + + +@functools.cache +def _importers() -> dict[str, frozenset[str]]: + """Which files under the python root import each top-level module, as repo-relative paths.""" + root = REPO_ROOT / _catalog()["blueprint"]["python_root"] + found: dict[str, set[str]] = {} + for path in sorted(root.rglob("*.py")): + for module in _module_imports(path): + found.setdefault(module.split(".")[0], set()).add(path.relative_to(REPO_ROOT).as_posix()) + + return {module: frozenset(files) for module, files in found.items()} + + +def _declared_distributions(listing: str) -> set[str]: + """The distributions a listing names, the core's and every feature's together.""" + return {_distribution(specifier) for specifier in _declared_specifiers(listing)} + + +INDIRECT_NEEDS = { + "itsdangerous": ("starlette.middleware.sessions", "backend/src/interfaces/admin/auth.py"), + "user-agents": ("crudauth.transports.session.transport", "backend/src/infrastructure/auth/evictions.py"), +} +"""Distributions nothing imports by name, each with the import that needs it and the file that +makes that import. `starlette` doesn't declare `itsdangerous`, and importing +`crudauth.transports.session.transport` runs that package's `__init__`, which imports its +`manager`, which imports `user_agents` inside a `try`. A project without either would refuse +to start the admin panel, or record every session's device as unknown, with nothing naming +what is missing.""" + + +NEEDED_WITHOUT_AN_IMPORT = { + "asyncpg": "the driver `POSTGRES_ASYNC_PREFIX` names, which sqlalchemy loads from the URL", + "greenlet": "what sqlalchemy runs a DBAPI call in, for its asyncio support", +} +"""Core distributions no file imports and no import pulls in: another distribution asks for them, +or a setting names them as a driver. Written down so a project's image carries nothing nobody can +account for.""" + + +def test_every_runtime_dependency_nothing_imports_is_accounted_for(): + """Both ways: a distribution installed and never imported is either needed through something + else, which is worth writing down, or weight in every project's image for no reason.""" + runtime = _declared_distributions("runtime") + imported = {name for name in runtime if _provided().get(name, frozenset()) & set(_importers())} + + assert runtime - imported == set(INDIRECT_NEEDS) | set(NEEDED_WITHOUT_AN_IMPORT) + + +def test_the_two_the_database_needs_are_the_blueprint_s_to_declare(): + """Why neither can be left to sqlalchemy, read from the installed metadata and the settings. + + `asyncpg` is the driver the URL names and sqlalchemy loads; `greenlet` is what sqlalchemy's + asyncio support runs a driver's calls in. Sqlalchemy asks for them only through extras the + backend doesn't declare, and the greenlet one outright on some platforms only, so a project + that installed plain `sqlalchemy` would have neither. + """ + asked = requires("sqlalchemy") or () + base = (REPO_ROOT / "backend/src/infrastructure/config/base.py").read_text() + + assert 'POSTGRES_ASYNC_PREFIX: str = "postgresql+asyncpg://"' in base + assert any(entry.startswith("asyncpg") and entry.endswith('extra == "postgresql-asyncpg"') for entry in asked) + assert any(entry.startswith("greenlet") and entry.endswith('extra == "asyncio"') for entry in asked) + assert "sqlalchemy>=2.0.37" in _catalog()["blueprint"]["dependencies"]["runtime"], "plain, with no extras" + + +@pytest.mark.parametrize( + ("feature", "specifier"), + sorted( + (name, specifier) for name, feature in _catalog()["features"].items() for specifier in feature.get("dependencies", ()) + ), +) +def test_every_feature_dependency_is_one_that_feature_needs(feature: str, specifier: str): + """A dependency parked on the wrong feature is a project that installs it and never uses it, + or selects the feature and finds it missing.""" + name = _distribution(specifier) + owned = [path for path, _ in _declared(_catalog()["features"][feature])] + + if name in INDIRECT_NEEDS: + module, importer = INDIRECT_NEEDS[name] + + assert _under(importer, owned), importer + assert module in _module_imports(REPO_ROOT / importer), module + assert not _provided()[name] & set(_importers()), f"{name} is imported by name now" + + return + + importers = {file for module in _provided()[name] for file in _importers().get(module, ())} + outright = {file for file in importers if _provided()[name] & _imports_outright(REPO_ROOT / file)} + + assert importers, name + assert any(_under(file, owned) for file in outright), sorted(importers) + + +def _needed_by(features: dict[str, Any]) -> dict[str, set[str]]: + """Each declared distribution, with the features that bring it. An option's brings an empty + set: a project selects the feature and still chooses another value, so nothing guarantees it.""" + needed: dict[str, set[str]] = {} + for name, feature in features.items(): + for specifier in feature.get("dependencies", ()): + needed.setdefault(_distribution(specifier), set()).add(name) + for option in feature.get("options", {}).values(): + for specifiers in option.get("dependencies", {}).values(): + for specifier in specifiers: + needed.setdefault(_distribution(specifier), set()) + + return needed + + +def _removed_for(features: dict[str, Any], chosen: set[str]) -> list[str]: + """The owned paths this selection doesn't keep, which is what `_kept_by_the_catalog` leaves out.""" + return [ + path + for name, feature in features.items() + for path, condition in _declared(feature) + if name not in chosen or (condition is not None and not _true(condition, chosen)) + ] + + +def test_no_file_a_project_keeps_imports_a_dependency_it_did_not_select(): + """The other half of moving a dependency off the core, over all 164 selections. + + `fastro new` writes a project's `pyproject.toml` from the declarations (spec 6.3), so a file + kept without the feature that brings a distribution, importing it outright, is a project that + fails at import. Only the files that go with the feature may need it. + """ + features = _catalog()["features"] + needed = _needed_by(features) + + assert needed["sqladmin"] == {"admin"} + assert needed["aiomcache"] == set(), "an option's dependency is never guaranteed" + + for chosen in _selections(): + removed = _removed_for(features, chosen) + for name, owners in needed.items(): + if owners & chosen: + continue + + for module in _provided()[name]: + for file in _importers().get(module, ()): + if not _provided()[name] & _imports_outright(REPO_ROOT / file): + continue + + assert _under(file, removed) or _withheld(file), (sorted(chosen), name, file) + + +@functools.cache +def _project_modules_imported(file: str) -> frozenset[str]: + """The project's own modules this file imports, as repo-relative paths with no suffix. + + A relative import is resolved against the file's package, and each name a `from` import takes + counts as a submodule too, since it may be one. + """ + root = _catalog()["blueprint"]["python_root"] + tops = {path.name for path in (REPO_ROOT / root).iterdir() if path.is_dir()} + package = Path(file).relative_to(root).parts[:-1] + found: set[tuple[str, ...]] = set() + for node in ast.walk(ast.parse((REPO_ROOT / file).read_text())): + if isinstance(node, ast.Import): + found.update(tuple(alias.name.split(".")) for alias in node.names) + elif isinstance(node, ast.ImportFrom): + anchor = package[: len(package) - node.level + 1] if node.level else () + base = anchor + (tuple(node.module.split(".")) if node.module else ()) + found.add(base) + found.update((*base, alias.name) for alias in node.names) + + return frozenset(f"{root}/{'/'.join(parts)}" for parts in found if parts and parts[0] in tops) + + +def test_no_file_a_project_keeps_imports_a_module_the_selection_removed(): + """Over all 164 selections, a kept file never imports the project's own code from a path a + feature left out took with it: that project fails at import, or ships a test that can't. + + The generated wiring is left out here, since fastro writes it for each selection. + """ + features = _catalog()["features"] + generated = {entry["path"] for entry in _entries()} + root = REPO_ROOT / _catalog()["blueprint"]["python_root"] + files = sorted(path.relative_to(REPO_ROOT).as_posix() for path in root.rglob("*.py")) + broken: dict[str, set[str]] = {} + + for chosen in _selections(): + removed = _removed_for(features, chosen) + for file in files: + if file in generated or _withheld(file) or _under(file, removed): + continue + for module in _project_modules_imported(file): + if _under(module, removed) or _under(f"{module}.py", removed): + broken.setdefault(file, set()).add(",".join(sorted(chosen))) + + assert {file: len(selections) for file, selections in broken.items()} == {} + + +@pytest.mark.parametrize( + ("feature", "specifier"), + sorted( + (name, specifier) + for name, feature in _catalog()["features"].items() + for specifier in feature.get("dev_dependencies", ()) + ), +) +def test_every_feature_development_dependency_belongs_to_that_feature(feature: str, specifier: str): + """An extra is never imported by name, so what makes it the feature's is the distribution it + extends: `taskiq[reload]` is the taskiq worker's own `--reload`, and a project with no worker + has nothing to reload. A file of the feature's importing it counts too, for a test-only + dependency that is imported. + """ + name = _distribution(specifier) + runtime = {_distribution(entry) for entry in _catalog()["features"][feature].get("dependencies", ())} + owned = [path for path, _ in _declared(_catalog()["features"][feature])] + importers = {file for module in _provided().get(name, ()) for file in _importers().get(module, ())} + + assert name in runtime or any(_under(file, owned) for file in importers), name + + +@pytest.mark.parametrize( + ("feature", "option", "value", "specifier"), + sorted( + (name, option, value, specifier) + for name, feature in _catalog()["features"].items() + for option, declared in feature.get("options", {}).items() + for value, specifiers in declared.get("dependencies", {}).items() + for specifier in specifiers + ), +) +def test_every_option_dependency_is_one_its_value_needs(feature: str, option: str, value: str, specifier: str): + """Spec 2.5: the value has to be one of the option's choices, and the file that imports the + distribution has to belong to the feature that offers it.""" + declared = _catalog()["features"][feature]["options"][option] + owned = [path for path, _ in _declared(_catalog()["features"][feature])] + importers = {file for module in _provided()[_distribution(specifier)] for file in _importers().get(module, ())} + + assert value in declared["choices"] + assert importers, specifier + assert all(_under(file, owned) for file in importers), sorted(importers) + for file in importers: + assert not _provided()[_distribution(specifier)] & _imports_outright(REPO_ROOT / file), ( + f"{file} imports {specifier} without a guard, and a project that chose another value has it absent" + ) + + +def test_no_runtime_dependency_is_one_only_the_tests_import(): + """A distribution only the tests import is installed in production for nothing. + + `backend/Dockerfile` installs the runtime list with `--no-dev`, so that is the list that + decides the image. A distribution nothing imports at all is left alone here: several are + needed indirectly, through something that doesn't declare them. + """ + runtime = _declared_distributions("runtime") + application = _imported("src", "scripts", "migrations") + tests = _imported("tests") + + only_tested = { + name for name in runtime if _provided().get(name, frozenset()) & tests and not _provided()[name] & application + } + + assert only_tested == set() + + +DEVELOPMENT_SCRIPT = "scripts/baseline.py" +"""The one script a project runs from its development environment rather than from the image.""" + + +def test_no_dependency_the_application_imports_is_declared_for_development_only(): + """The other way round, where `uv export --no-dev` would leave an import with nothing behind it. + + The scripts are read too, because an operator runs them in the image: the first-run guide + seeds a deployment with `docker compose exec api python -m scripts.setup_initial_data`, and + the repairs, the usage prune and the account unlock are all run the same way. `baseline.py` + is the exception, and the only one: it writes a project's first migration against a container + it starts itself, which is a thing to do once, from a checkout. + """ + development = _declared_distributions("dev") - _declared_distributions("runtime") + application = _imported("src", "scripts", "migrations", skipping=(DEVELOPMENT_SCRIPT,)) + + assert {name for name in development if _provided().get(name, frozenset()) & application} == set() + + +def test_the_dependency_readings_find_what_they_claim_to(): + """Both rules report what they found, so a reading that stopped working would pass quietly.""" + assert "fastapi" in _imported("src", "migrations") + assert "pytest" in _imported("tests") + assert _provided()["sqlalchemy"] == frozenset({"sqlalchemy"}) + assert "testcontainers" in _imported("scripts") + assert "testcontainers" not in _imported("scripts", skipping=(DEVELOPMENT_SCRIPT,)) + assert "asyncio" in _imported("scripts", skipping=(DEVELOPMENT_SCRIPT,)), "the other scripts are still read" + + +@pytest.mark.parametrize("entry", sorted(_catalog()["blueprint"]["blueprint_only"])) +def test_every_blueprint_only_path_is_written_the_way_the_spec_reads_them(entry: str): + """Spec 1.1: a trailing slash means the subtree, and without one it is a single file. + + `docs` rather than `docs/` would name one file nobody has, and the whole tree would + reach projects. + """ + assert not entry.startswith("/") + assert ".." not in Path(entry).parts + assert entry.endswith("/") == (REPO_ROOT / entry).is_dir() + + +@pytest.mark.parametrize("entry", sorted(_catalog()["blueprint"]["blueprint_only"])) +def test_every_blueprint_only_path_is_one_this_repo_has(entry: str): + """A path that no longer exists keeps a file out of projects that nobody meant to keep out.""" + assert (REPO_ROOT / entry).exists() + + +def _withheld(path: str) -> bool: + """Whether `blueprint_only` keeps a project from receiving this path (spec 1.1 subtrees).""" + return any( + path == entry.rstrip("/") or (entry.endswith("/") and path.startswith(entry)) + for entry in _catalog()["blueprint"]["blueprint_only"] + ) + + +def _workspace_members() -> list[str]: + with (REPO_ROOT / "pyproject.toml").open("rb") as handle: + return list(tomllib.load(handle)["tool"]["uv"]["workspace"]["members"]) + + +def _root_project_paths() -> list[str]: + """The workspace members and the test paths the root `pyproject.toml` names.""" + root = _root_project() + + return [*root["tool"]["uv"]["workspace"]["members"], *root["tool"]["pytest"]["ini_options"]["testpaths"]] + + +def _unwrapped(pattern: str) -> str: + """A pattern without the one group that wraps all of it, if there is one.""" + depth = 0 + for index, character in enumerate(pattern): + depth += {"(": 1, ")": -1}.get(character, 0) + if depth == 0: + return pattern[1:-1] if pattern.startswith("(") and index == len(pattern) - 1 else pattern + + return pattern + + +def _alternatives(pattern: str) -> list[str]: + """The top-level alternatives of an anchored pattern, outside a group that wraps it whole.""" + body = _unwrapped(pattern.removeprefix("^").removesuffix("$")) + + parts, depth, start = [], 0, 0 + for index, character in enumerate(body): + depth += {"(": 1, "[": 1, ")": -1, "]": -1}.get(character, 0) + if character == "|" and depth == 0: + parts.append(body[start:index]) + start = index + 1 + + return [*parts, body[start:]] + + +def _literal_head(pattern: str) -> str: + """The characters a pattern matches literally before its first special one, unescaped.""" + head = re.match(r"(?:[^\\()\[\]{}|?*+.^$]|\\[./-])*", pattern) + assert head is not None + + return re.sub(r"\\(.)", r"\1", head.group()) + + +def _pattern_heads(pattern: str) -> list[str]: + """The path each alternative of a pre-commit `files:` pattern starts with, through nested ones.""" + alternatives = _alternatives(pattern) + if len(alternatives) > 1: + return [head for alternative in alternatives for head in _pattern_heads(alternative)] + + return [_literal_head(alternatives[0]).rstrip("/")] + + +def _named_paths(patterns: list[str]) -> list[str]: + """The paths the patterns name, refusing one whose head is empty: it would name nothing to check.""" + heads = [head for pattern in patterns for head in _pattern_heads(pattern)] + assert all(heads), patterns + + return heads + + +def _hook_paths() -> list[str]: + """The paths the pre-commit `files:` patterns name, one per alternative.""" + return _named_paths(re.findall(r"^\s*files: (\S+)$", (REPO_ROOT / ".pre-commit-config.yaml").read_text(), re.M)) + + +@pytest.mark.parametrize( + ("pattern", "heads"), + [ + ("^docs/", ["docs"]), + ("^backend/(src|scripts|migrations|tests)/", ["backend"]), + (r"^(blueprint\.toml|fastro\.toml|backend/src/wiring/)", ["blueprint.toml", "fastro.toml", "backend/src/wiring"]), + (r"^(a\.py)|(b/)$", ["a.py", "b"]), + (r"^(a|(b\.py|c/))$", ["a", "b.py", "c"]), + (r"^(a|b)/x", [""]), + ], +) +def test_the_hook_reader_sees_every_path_a_pattern_names(pattern: str, heads: list[str]): + """An alternation names one path per branch, and an escaped dot is part of the name.""" + assert _pattern_heads(pattern) == heads + + +def test_the_hook_reader_refuses_a_pattern_that_names_no_path(): + """A head of `""` is never withheld, so the rules that read it would pass over nothing.""" + with pytest.raises(AssertionError): + _named_paths([r"^(a|b)/x"]) + + +def _readme_references() -> list[str]: + """The files the README's own markup points at, leaving out what it fetches over the network.""" + found = re.findall(r'src(?:set)?="([^"]+)"', (REPO_ROOT / "README.md").read_text()) + + return [reference for reference in found if not reference.startswith("http")] + + +POINTS_AT = { + "pyproject.toml": _root_project_paths, + ".pre-commit-config.yaml": _hook_paths, + "README.md": _readme_references, +} +"""Each root file that names paths, read the way that file spells them.""" + + +@pytest.mark.parametrize("path", sorted(POINTS_AT)) +def test_no_file_a_project_receives_points_at_one_it_does_not(path: str): + """Either the pointer goes or the file does. + + A workspace member a project never receives is a project `uv sync` refuses; a test path is + a pytest run that collects nothing; a lint pattern is a hook over nothing; an image is a + hole where the cover was. The three root files are the blueprint's own, so they are the + ones that go. + """ + withheld = sorted(target for target in POINTS_AT[path]() if _withheld(target)) + + assert not withheld or _withheld(path), (path, withheld) + + +WITHHELD_POINTERS = { + "pyproject.toml": "blueprint/tests", + ".pre-commit-config.yaml": "blueprint.toml", + "README.md": "docs/assets", +} +"""What keeps each of the three out of a project, pinned so a reader of it can't go quiet.""" + + +@pytest.mark.parametrize("path", sorted(POINTS_AT)) +def test_each_file_still_names_the_path_that_keeps_it_out(path: str): + """The reason each file is blueprint-only, rather than the fact of it. + + A format that moved on -- a renamed pre-commit key, an image moved out of `docs/` -- would + leave the rule above with nothing to object to, and the file would ship. The root + `pyproject.toml` is kept out by the blueprint's own tests, which its pytest config runs. + """ + pointed = POINTS_AT[path]() + + assert any(target.startswith(WITHHELD_POINTERS[path]) for target in pointed), pointed + + +ROOT_PYPROJECT = REPO_ROOT / "pyproject.toml" +FASTRO_REPOSITORY = "https://github.com/benavlabs/fastro" +COMMIT = re.compile(r"^[0-9a-f]{40}$") + + +def _root_project() -> dict[str, Any]: + with ROOT_PYPROJECT.open("rb") as handle: + return tomllib.load(handle) + + +def test_the_backend_is_the_workspaces_one_member(): + """The old developer tool's package is gone.""" + assert _workspace_members() == ["backend"] + + +def test_the_repository_root_installs_fastro_for_its_own_checks(): + """fastro checks the blueprint, so the root project, which no project receives, carries it.""" + assert _withheld("pyproject.toml") + assert "fastro" in {_distribution(specifier) for specifier in _root_project()["dependency-groups"]["dev"]} + + +def test_fastro_is_pinned_to_one_commit_of_its_repository(): + """Unreleased, so a commit is the only version a lock can hold steady.""" + source = _root_project()["tool"]["uv"]["sources"]["fastro"] + + assert source.keys() == {"git", "rev"} + assert source["git"] == FASTRO_REPOSITORY + assert COMMIT.match(source["rev"]), source["rev"] + + +def test_no_project_receives_the_fastro_pin(): + """A project gets `backend/pyproject.toml`, and its own checks run fastro through `uvx`.""" + with BACKEND_PYPROJECT.open("rb") as handle: + backend = tomllib.load(handle) + + groups = [ + backend["project"].get("dependencies", []), + *backend["project"].get("optional-dependencies", {}).values(), + *backend.get("dependency-groups", {}).values(), + ] + + assert "fastro" not in {_distribution(specifier) for group in groups for specifier in group} + assert "fastro" not in backend.get("tool", {}).get("uv", {}).get("sources", {}) + + +def _pre_commit_repositories(config: str | None = None) -> list[dict[str, Any]]: + """Each `- repo:` entry of `.pre-commit-config.yaml`, parsed.""" + parsed = yaml.safe_load((REPO_ROOT / ".pre-commit-config.yaml").read_text() if config is None else config) + repositories: list[dict[str, Any]] = parsed["repos"] + + return repositories + + +def _pre_commit_hooks(config: str | None = None) -> list[dict[str, Any]]: + return [hook for repository in _pre_commit_repositories(config) for hook in repository["hooks"]] + + +def test_the_pre_commit_reader_reads_what_yaml_means_not_how_it_is_written(): + hooks = _pre_commit_hooks( + "repos:\n" + " - repo: local\n" + " hooks:\n" + ' - id: "commented" # why\n' + " # a note\n" + " entry: run it # how\n" + "\n" + " stages: [ 'manual' ]\n" + " - id: listed\n" + " stages:\n" + " - manual # first\n" + " - pre-push\n" + " pass_filenames: false\n" + ) + + assert hooks == [ + {"id": "commented", "entry": "run it", "stages": ["manual"]}, + {"id": "listed", "stages": ["manual", "pre-push"], "pass_filenames": False}, + ] + + +def _the_sync_check_hook() -> dict[str, Any]: + hooks = [hook for hook in _pre_commit_hooks() if "fastro sync --check" in hook.get("entry", "")] + assert len(hooks) == 1, hooks + + return hooks[0] + + +SYNC_CHECK_TRIGGERS_BY_NAME = {"blueprint.toml", "fastro.toml", "pyproject.toml", "uv.lock"} +"""The files the guides name as running the sync check; the wiring they name by what it is.""" + + +def _path_spans(text: str) -> set[str]: + """Each code span that reads as a path: no spaces, and a directory or an extension.""" + return {span for span in re.findall(r"`([^`]+)`", text) if re.fullmatch(r"[\w./-]+", span) and re.search(r"[/.]", span)} + + +def _assert_names_the_sync_check_triggers(text: str) -> None: + assert _path_spans(text) == SYNC_CHECK_TRIGGERS_BY_NAME, _path_spans(text) + for path in _path_spans(text): + assert re.search(_the_sync_check_hook()["files"], path), path + + +def test_a_commit_runs_sync_check_on_the_whole_tree(): + """`sync --check` compares every wiring file, so the hook hands it no file names.""" + hook = _the_sync_check_hook() + + assert hook["entry"] == "uv run --no-sync fastro sync --check" + assert hook["language"] == "system" + assert hook["pass_filenames"] is False + + +def test_the_sync_check_hook_runs_at_every_commit(): + """Any key beyond these narrows when it runs: a stage, an exclusion, a file type.""" + assert _the_sync_check_hook().keys() == {"id", "name", "language", "entry", "pass_filenames", "files"} + + +@pytest.mark.parametrize("path", ["blueprint.toml", "fastro.toml", *(entry["path"] for entry in _catalog()["wiring"])]) +def test_a_commit_that_touches_what_sync_compares_runs_sync_check(path: str): + """The catalog, the selection and every file it generates, so a new wiring file can't slip by.""" + assert re.search(_the_sync_check_hook()["files"], path), path + + +@pytest.mark.parametrize("path", ["pyproject.toml", "uv.lock"]) +def test_a_commit_that_moves_the_fastro_pin_runs_sync_check(path: str): + """Another fastro can render the same catalog differently, so the files that pin it count too.""" + assert re.search(_the_sync_check_hook()["files"], path), path + + +def test_a_commit_that_touches_nothing_sync_compares_skips_sync_check(): + for path in ( + "backend/src/modules/user/models.py", + "docs/backend/src/wiring/app.md", + "backend/fastro.toml", + "blueprint.toml.orig", + "backend/pyproject.toml", + "backend/uv.lock", + "uv_lock", + "pyproject_toml", + "fastro_toml", + "blueprint_toml", + ): + assert not re.search(_the_sync_check_hook()["files"], path), path + + +def _hook_repositories() -> dict[str, str]: + """Each hook id in `.pre-commit-config.yaml`, with the repository it comes from.""" + return {hook["id"]: repository["repo"] for repository in _pre_commit_repositories() for hook in repository["hooks"]} + + +def _development_guide_pre_commit_section() -> str: + guide = (REPO_ROOT / "docs" / "user-guide" / "development.md").read_text() + + return guide.split("## Pre-Commit", 1)[1].split("\n\n## ", 1)[0] + + +def _development_guide_hook_rows() -> dict[str, str]: + """The guide's pre-commit table, each row keyed by each hook its first cell names, or by the cell if it names none.""" + rows = re.findall(r"^\| (?!Hook\b|-)(.+?) \| (.+) \|$", _development_guide_pre_commit_section(), re.M) + + named = [ + (name, cells) + for names, cells in rows + for name in [code.split()[0] for code in re.findall(r"`([^`]+)`", names)] or [names] + ] + assert len({name for name, _ in named}) == len(named), named + + return dict(named) + + +def test_the_development_guide_names_every_hook_a_commit_runs(): + assert _hook_repositories() + assert set(_hook_repositories()) <= set(_development_guide_hook_rows()) + + +def test_the_development_guide_names_no_hook_the_config_lacks(): + assert set(_development_guide_hook_rows()) <= set(_hook_repositories()) + + +def test_the_development_guide_says_which_hooks_are_local(): + rows = _development_guide_hook_rows() + local = {hook for hook, repository in _hook_repositories().items() if repository == "local"} + + assert local + assert {hook for hook, cells in rows.items() if cells.startswith("local")} == local + + +def test_the_development_guide_says_which_hooks_run_only_when_asked_for(): + manual = {hook["id"] for hook in _pre_commit_hooks() if hook.get("stages") == ["manual"]} + + assert manual + assert {hook for hook, cells in _development_guide_hook_rows().items() if "manual stage" in cells} == manual + + +def test_the_development_guide_gives_the_command_the_sync_check_hook_runs(): + row = _development_guide_hook_rows()[_the_sync_check_hook()["id"]] + entry = f"`{_the_sync_check_hook()['entry']}`" + + assert entry in row + _assert_names_the_sync_check_triggers(row) + assert "wiring" in row.replace(entry, "") + + +def _hook_shell_line(hook: dict[str, str]) -> str: + """What a hook runs, without the `bash -c` that lets a local hook change directory first.""" + found = re.fullmatch(r"bash -c '(.+)'", hook["entry"]) + + return found[1] if found else hook["entry"] + + +def _ci_runs_command(command: str) -> bool: + """Whether a CI step runs this command, alone or on paths after it.""" + return any(re.fullmatch(rf"(?:uv run --no-sync )?{re.escape(command)}(?: [^-\s]\S*)*", run) for run in _workflow_runs()) + + +def _names_ci(row: str) -> bool: + """Whether a row of the development guide's hook table says what CI runs.""" + return re.search(r"\bCI\b", row) is not None + + +def _ci_runs_hook(hook: dict[str, str]) -> bool: + """Whether a CI step runs a local hook's command, as it is or on every path instead of the ones it names.""" + line = _hook_shell_line(hook) + + return line in _workflow_runs() or _without_trailing_paths(line) in _workflow_runs() + + +def _names_a_path(word: str) -> bool: + return any(mark in word for mark in "/.") and all(char.isalnum() or char in "_./-" for char in word) + + +def _without_trailing_paths(line: str) -> str: + """The line with the space-separated paths it ends in dropped: a word of letters, digits, + ``_``, ``.``, ``/`` and ``-`` that holds a ``/`` or a ``.``. The first word always stays, and so + does a newline the line ends in.""" + body, newline = (line[:-1], "\n") if line.endswith("\n") else (line, "") + words = body.split(" ") + while len(words) > 1 and _names_a_path(words[-1]): + words.pop() + + return " ".join(words) + newline + + +@pytest.mark.parametrize( + ("line", "kept"), + [ + ("uv run --no-sync ruff check src/app.py tests/x.py", "uv run --no-sync ruff check"), + ("cd backend && mypy src/a.py", "cd backend && mypy"), + ("ruff format --check .", "ruff format --check"), + ("mypy src tests", "mypy src tests"), + ("pytest -q", "pytest -q"), + ("x.py", "x.py"), + ("ruff --config=a.toml", "ruff --config=a.toml"), + ("run a/b c/d", "run a/b "), + ("mypy src/ ", "mypy src/ "), + ("run src/a.py tests", "run src/a.py tests"), + ("run ../up", "run"), + ("run tests/unit_2/my-file.py", "run"), + ("x a/b\n", "x\n"), + ], +) +def test_a_hook_line_drops_the_paths_it_ends_in(line: str, kept: str): + assert _without_trailing_paths(line) == kept + + +def test_a_long_line_of_dots_is_read_at_once(): + line = "run" + " .." * 100_000 + " !" + started = time.perf_counter() + + assert _without_trailing_paths(line) == line + assert _without_trailing_paths(line[:-2]) == "run" + assert time.perf_counter() - started < 1 + + +def test_the_hooks_the_development_guide_says_ci_runs_run_what_ci_runs(): + rows = _development_guide_hook_rows() + claimed = [hook for hook in _pre_commit_hooks() if _names_ci(rows[hook["id"]])] + + assert claimed + for hook in claimed: + if "entry" in hook: + assert _ci_runs_hook(hook), hook["id"] + else: + commands = [span for span in re.findall(r"`([^`]+)`", rows[hook["id"]]) if " " in span] + assert any(command.startswith(hook["id"].replace("-", " ")) for command in commands), hook["id"] + for command in commands: + assert _ci_runs_command(command), command + + +def test_the_hooks_the_development_guide_leaves_ci_out_of_are_no_ci_step(): + rows = _development_guide_hook_rows() + unclaimed = [hook for hook in _pre_commit_hooks() if not _names_ci(rows[hook["id"]])] + + assert unclaimed + for hook in unclaimed: + if "entry" in hook: + assert not _ci_runs_hook(hook), hook["id"] + else: + for name in {hook["id"], hook["id"].replace("-", " ")}: + assert not any(re.search(rf"\b{re.escape(name)}\b", run) for run in _workflow_runs()), name + + +def test_the_development_guide_gives_the_command_each_manual_hook_runs_and_where(): + manual = [hook for hook in _pre_commit_hooks() if hook.get("stages") == ["manual"]] + + assert manual + for hook in manual: + found = re.fullmatch(r"cd (\S+) && (.+)", _hook_shell_line(hook)) + assert found, hook["id"] + directory, command = found.groups() + row = _development_guide_hook_rows()[hook["id"]] + assert f"`{command}`" in row, row + assert f"`{directory}/`" in row, row + + +def _development_guide_pre_commit_prose() -> str: + """The development guide's Pre-Commit section, past its hook table.""" + return _development_guide_pre_commit_section().rsplit("\n|", 1)[1].split("\n", 1)[1] + + +def test_some_unit_tests_start_containers_through_testcontainers(): + """The development guide's claim; `blueprint/tests/test_pre_commit.py` runs the hook without Docker to show they skip.""" + unit = REPO_ROOT / "backend" / "tests" / "unit" + + assert "`testcontainers`" in _development_guide_pre_commit_prose() + assert any( + isinstance(node, ast.ImportFrom) and re.fullmatch(r"testcontainers(?:\..+)?", node.module or "") + for path in unit.rglob("*.py") + if path != Path(__file__).resolve() + for node in ast.walk(ast.parse(path.read_text())) + ) + + +def test_docker_counts_as_not_running_when_its_client_cannot_connect(monkeypatch): + monkeypatch.setenv("DOCKER_HOST", "tcp://127.0.0.1:1") + monkeypatch.setattr("testcontainers.core.config.testcontainers_config.tc_properties", {}) + + assert is_docker_running() is False + + +def test_the_project_puts_an_attribute_docstring_under_a_module_level_name(): + """Why the development guide leaves `check-docstring-first` out.""" + documented = [ + path + for path in sorted((REPO_ROOT / "backend").glob("[st]*/**/*.py")) + if any( + isinstance(name, ast.Assign | ast.AnnAssign) + and isinstance(docstring, ast.Expr) + and isinstance(docstring.value, ast.Constant) + and isinstance(docstring.value.value, str) + for name, docstring in itertools.pairwise(ast.parse(path.read_text()).body) + ) + ] + + assert any(path.is_relative_to(REPO_ROOT / "backend" / "src") for path in documented), documented + assert "`check-docstring-first`" in _development_guide_pre_commit_prose() + + +def test_the_hooks_the_development_guide_leaves_out_are_not_in_the_config(): + left_out = {"mdformat", "blacken-docs", "check-docstring-first"} + named = set(re.findall(r"`([\w-]+)`", _development_guide_pre_commit_prose())) + + assert left_out <= named + assert not left_out & set(_hook_repositories()) + assert "ruff-format" in named & set(_hook_repositories()) + + +def test_the_extra_the_development_guide_names_installs_pre_commit(): + prose = _development_guide_pre_commit_prose() + extra = re.search(r"`pre-commit` ships in the `([\w-]+)` extra, so `(uv sync[^`]*)`", prose) + assert extra, prose + + assert {"--all-packages", "--all-extras"} <= set(extra[2].split()) + assert any( + re.match(r"pre-commit(?![\w.-])", requirement) + for member in tomllib.loads((REPO_ROOT / "pyproject.toml").read_text())["tool"]["uv"]["workspace"]["members"] + for requirement in tomllib.loads((REPO_ROOT / member / "pyproject.toml").read_text())["project"] + .get("optional-dependencies", {}) + .get(extra[1], []) + ) + + +def test_each_hook_the_development_guide_runs_by_name_is_in_the_config_at_the_stage_it_gives(): + runs = re.findall(r"pre-commit run (\w[\w-]*)(.*)$", _development_guide_pre_commit_prose(), re.M) + hooks = {hook["id"]: hook for hook in _pre_commit_hooks()} + + assert runs + for hook, flags in runs: + assert hook in hooks, hook + stage = re.search(r"--hook-stage (\w+)", flags) + assert hooks[hook].get("stages", ["pre-commit"]) == [stage[1] if stage else "pre-commit"], hook + + +def test_each_pre_commit_command_the_development_guide_gives_takes_the_flags_it_passes(): + prose = _development_guide_pre_commit_prose() + commands = re.findall(r"^uv run --no-sync pre-commit (\w+)(.*)$", prose, re.M) + + assert commands + for fence in re.findall(r"^```bash\n(.*?)^```$", prose, re.M | re.S): + for line in fence.splitlines(): + assert "pre-commit" not in line or line.startswith("uv run --no-sync pre-commit "), line + for subcommand, arguments in commands: + usage = subprocess.run( + [sys.executable, "-m", "pre_commit", subcommand, "--help"], capture_output=True, text=True, check=False + ) + assert usage.returncode == 0, subcommand + for flag in re.findall(r"(? list[str]: + """Each line every `run:` in the repository's own CI runs, a block's line by line.""" + if workflows is None: + workflows = [workflow.read_text() for workflow in sorted((REPO_ROOT / ".github" / "workflows").glob("*.yml"))] + + return [ + line.strip() + for workflow in workflows + for job in yaml.safe_load(workflow)["jobs"].values() + for step in job.get("steps", []) + for line in str(step.get("run", "")).splitlines() + if line.strip() + ] + + +def test_the_workflow_reader_reads_every_run_and_a_block_line_by_line(): + workflow = ( + "jobs:\n" + " a:\n" + " steps:\n" + " - run: uv sync # first\n" + " - name: named\n" + " run: 'uv run --no-sync pytest'\n" + " - name: block\n" + " run: |\n" + " echo one\n" + "\n" + " if true; then\n" + " echo two\n" + " fi\n" + " b:\n" + " uses: ./.github/workflows/other.yml\n" + ) + + assert _workflow_runs([workflow]) == ["uv sync", "uv run --no-sync pytest", "echo one", "if true; then", "echo two", "fi"] + + +def test_ci_type_checks_the_blueprint_tests_it_runs(): + """A test file nobody type-checks can drift from the code it reads, and only fail when it runs.""" + runs = _workflow_runs() + tested = { + argument.rstrip("/") + for run in runs + if run.startswith("uv run --no-sync pytest ") + for argument in run.split()[4:] + if argument.startswith("blueprint/") + } + checked = [run.split()[4:] for run in runs if run.startswith("uv run --no-sync mypy ")] + + assert tested + for directory in tested: + assert any( + directory == path.rstrip("/") or directory.startswith(path.rstrip("/") + "/") for paths in checked for path in paths + ), directory + + +def _defaults_blocks(workflow: str) -> list[str]: + """Each `defaults:` block of a workflow, at any level, with its value written on the same line or below it.""" + lines = workflow.splitlines() + blocks = [] + for index, line in enumerate(lines): + found = re.match(r"^( *)defaults:(.*)$", line) + if found is None: + continue + + block = [found.group(2)] + for following in lines[index + 1 :]: + if following.strip() and len(following) - len(following.lstrip()) <= len(found.group(1)): + break + block.append(following) + blocks.append("\n".join(block)) + + return blocks + + +@pytest.mark.parametrize( + "workflow", + [ + "defaults:\n run:\n working-directory: backend\njobs:\n", + "jobs:\n lint:\n defaults:\n run:\n shell: bash\n working-directory: backend\n steps:\n", + "jobs:\n lint:\n defaults: {run: {working-directory: backend}}\n", + ], +) +def test_the_defaults_reader_sees_a_working_directory_however_it_is_written(workflow: str): + assert any("working-directory" in block for block in _defaults_blocks(workflow)) + + +def test_the_defaults_reader_stops_at_the_end_of_its_block(): + workflow = "defaults:\n run:\n shell: bash\njobs:\n lint:\n steps:\n - working-directory: backend\n" + + assert not any("working-directory" in block for block in _defaults_blocks(workflow)) + + +SYNC_THAT_KEEPS_THE_DEV_GROUP = {"uv", "sync", "--all-packages", "--all-extras", "--locked", "--python", "3.11"} +"""The words a sync may use and still install the root dev group, where fastro is.""" + + +@pytest.mark.parametrize("command", ["fastro sync --check", "fastro blueprint lint"]) +def test_ci_runs_fastros_checks_where_fastro_is_installed(command: str): + """From the repository root, the project that declares fastro, never after a `cd`, and always gating the job.""" + assert [run for run in _workflow_runs() if command in run] == [f"uv run --no-sync {command}"] + + for workflow in sorted((REPO_ROOT / ".github" / "workflows").glob("*.yml")): + text = workflow.read_text() + steps = [step for step in re.split(r"\n(?= +- )", text) if command in step] + if steps: + assert not any("working-directory" in block for block in _defaults_blocks(text)), workflow.name + for step in steps: + assert set(re.findall(r"^\s*(?:- )?([\w-]+):", step, re.M)) == {"name", "run"}, step + + syncs = re.findall(r"^\s+run: (uv sync\b.*)$", text, re.M) + assert syncs, workflow.name + for sync in syncs: + assert set(sync.split()) <= SYNC_THAT_KEEPS_THE_DEV_GROUP, sync + + +CONTRIBUTING = REPO_ROOT / "CONTRIBUTING.md" + +UV_THAT_WROTE_THE_LOCK = {5: "0.13.8"} +"""The uv release this repository's lock was first written with at each revision, not the first release that writes it.""" + + +def _contributing_syncs() -> list[str]: + """Each sync the guide gives as a command on its own line, not a sync it names inline in prose.""" + return re.findall(r"^\s*(?:\$\s+)?(uv sync\b.*)$", CONTRIBUTING.read_text(), re.M) + + +def _imported_modules(module: str, source: str) -> set[str]: + """Each module a file imports, and each name it imports from one, with relative imports resolved.""" + package = module.split(".")[:-1] + imported: set[str] = set() + for node in ast.walk(ast.parse(source)): + if isinstance(node, ast.Import): + imported.update(alias.name for alias in node.names) + elif isinstance(node, ast.ImportFrom): + anchor = package[: len(package) - node.level + 1] if node.level else [] + base = ".".join([*anchor, *filter(None, [node.module])]) + imported.add(base) + imported.update(f"{base}.{alias.name}" for alias in node.names) + + return imported + + +def test_every_test_that_reads_the_docs_or_imports_a_withheld_test_stays_in_the_blueprint(): + backend = REPO_ROOT / "backend" + files = {".".join(path.relative_to(backend).with_suffix("").parts): path for path in (backend / "tests").rglob("*.py")} + withheld = {module for module, path in files.items() if _withheld(str(path.relative_to(REPO_ROOT)))} + reading = [] + for module, path in sorted(files.items()): + source = path.read_text() + if re.search(r"""(?:["']|\}/|\.\./)docs["'/]""", source) or withheld & _imported_modules(module, source): + reading.append(path) + + assert {f"test_docs_{name}.py" for name in ("imports", "recipes", "scripts", "wiring")} <= {path.name for path in reading} + for path in reading: + assert _withheld(str(path.relative_to(REPO_ROOT))), ( + f"{path.relative_to(REPO_ROOT)} reads the docs, which describe every feature, or imports a blueprint-only test, " + "so it assumes the full repo: list it under [blueprint].blueprint_only in blueprint.toml" + ) + + +def test_the_contributing_guide_is_the_blueprint_s_own(): + assert _withheld("CONTRIBUTING.md") + + +def test_the_sync_the_contributing_guide_gives_installs_fastro(): + """Every sync it gives keeps the root dev group, where fastro is.""" + assert _contributing_syncs() + for sync in _contributing_syncs(): + assert set(sync.split()) <= SYNC_THAT_KEEPS_THE_DEV_GROUP, sync + + +def test_the_readme_s_quickstart_sync_installs_fastro(): + """Every sync the README gives keeps the root dev group, and says it brings fastro in.""" + syncs = re.findall(r"^\s*(?:\$\s+)?(uv sync\b[^#\n]*)(#.*)?$", (REPO_ROOT / "README.md").read_text(), re.M) + + assert syncs + for sync, note in syncs: + assert set(sync.split()) <= SYNC_THAT_KEEPS_THE_DEV_GROUP, sync + assert re.search(r"\bfastro\b", note), note + + +def test_the_contributing_guide_names_the_group_that_pins_fastro(): + groups = [ + group + for group, specifiers in _root_project()["dependency-groups"].items() + if "fastro" in {_distribution(specifier) for specifier in specifiers} + ] + + assert len(groups) == 1, groups + assert f"`{groups[0]}`" in CONTRIBUTING.read_text() + + +def test_the_contributing_guide_names_the_uv_that_wrote_the_lock(): + """A uv older than the one that wrote the lock can write it back at an older revision, so the guide names that release.""" + with (REPO_ROOT / "uv.lock").open("rb") as handle: + revision = tomllib.load(handle)["revision"] + assert revision in UV_THAT_WROTE_THE_LOCK, f"add the uv that wrote lock revision {revision}, and name it in CONTRIBUTING.md" + + text = CONTRIBUTING.read_text() + assert re.search(rf"\brevision\s+{revision}\b", text) + assert set(re.findall(r"\buv\s+(\d+\.\d+\.\d+)", text)) == {UV_THAT_WROTE_THE_LOCK[revision]} + assert re.search(rf"uv\s+{re.escape(UV_THAT_WROTE_THE_LOCK[revision])}\s+or\s+(?:newer|later)\b", text) + + +def _the_guide_s_sync_check_sentence() -> str: + hook = f"`{_the_sync_check_hook()['entry']}`" + sentences = [sentence for sentence in re.split(r"(?<=\.)\s+", CONTRIBUTING.read_text()) if hook in sentence] + assert len(sentences) == 1, sentences + + return sentences[0] + + +def test_the_contributing_guide_names_the_check_a_commit_runs(): + """`blueprint/tests/test_fastro.py::test_plain_sync_regenerates_what_the_check_compares` proves what it does.""" + assert _the_guide_s_sync_check_sentence() + + +def test_the_contributing_guide_names_every_file_that_runs_the_check(): + """The catalog, the selection and the pin by name, and the wiring, each one the hook runs on.""" + sentence = _the_guide_s_sync_check_sentence() + + _assert_names_the_sync_check_triggers(sentence) + assert "wiring" in sentence.split(f"`{_the_sync_check_hook()['entry']}`")[0] + + +def test_the_check_runs_on_no_file_the_contributing_guide_leaves_out(): + """Each trigger is a file the guide names or a wiring file, so a new one fails until the guide names it.""" + named = _path_spans(_the_guide_s_sync_check_sentence()) + wiring = [entry["path"] for entry in _catalog()["wiring"]] + + for alternative in _alternatives(_the_sync_check_hook()["files"]): + assert re.sub(r"\\(.)", r"\1", alternative) in named or any(re.fullmatch(alternative, path) for path in wiring), ( + alternative + ) + + +def test_the_contributing_guide_names_the_command_that_fixes_a_failed_check(): + """`blueprint/tests/test_fastro.py::test_plain_sync_regenerates_what_the_check_compares` proves what it does.""" + assert "`uv run --no-sync fastro sync`" in CONTRIBUTING.read_text() + + +def _literals(module: Path) -> set[str]: + """Every string literal in a module, less the docstrings, which talk about files rather than + reach for them.""" + tree = ast.parse(module.read_text()) + docstrings = { + id(node.body[0].value) + for node in ast.walk(tree) + if isinstance(node, ast.Module | ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef) + and node.body + and isinstance(node.body[0], ast.Expr) + and isinstance(node.body[0].value, ast.Constant) + } + + return { + node.value + for node in ast.walk(tree) + if isinstance(node, ast.Constant) and isinstance(node.value, str) and id(node) not in docstrings + } + + +def test_no_test_a_project_receives_names_a_tree_it_does_not_get(): + """A test that reaches for `docs/` or `blueprint/` is a test no project can run. + + `test_baseline.py` read the migrations guide, a file a project never receives. Only the + subtree entries are compared, because a root file's name is ambiguous: a shipped test naming + `pyproject.toml` means the one under `backend/`. + """ + trees = [entry for entry in _catalog()["blueprint"]["blueprint_only"] if entry.endswith("/")] + reaching = {} + for module in sorted((REPO_ROOT / "backend" / "tests").rglob("*.py")): + relative = module.relative_to(REPO_ROOT).as_posix() + if _withheld(relative): + continue + + named = sorted( + text for text in _literals(module) for tree in trees if text == tree.rstrip("/") or text.startswith(tree) + ) + if named: + reaching[relative] = named + + assert reaching == {} + + +def test_the_things_projects_must_not_receive_are_listed(): + """The catalog and the docs belong to the blueprint only.""" + listed = set(_catalog()["blueprint"]["blueprint_only"]) + + assert {"blueprint/", "blueprint.toml", "fastro.toml", "docs/"} <= listed + assert "backend/tests/unit/test_blueprint_catalog.py" in listed + + +def test_the_docs_reading_tests_stay_in_the_blueprint(): + """They read `docs/`, which projects don't get, so they would fail in one.""" + listed = set(_catalog()["blueprint"]["blueprint_only"]) + + for name in ("test_docs_imports", "test_docs_recipes", "test_docs_scripts", "test_docs_wiring", "test_image_contents"): + assert f"backend/tests/unit/{name}.py" in listed + + +@pytest.mark.parametrize("name", sorted(_catalog()["presets"]) + sorted(_catalog()["verify"]["sets"])) +def test_every_preset_and_verify_set_is_named_the_way_the_spec_allows(name: str): + """Spec 1.2: a name here is lower case and may carry a hyphen, so `accounts-only` reads as one.""" + assert SET_NAME.match(name) + + +def test_every_preset_is_closed_under_what_its_features_require(): + """A preset that names tier_limits without tiers would generate a project that can't import.""" + for name, features in _catalog()["presets"].items(): + assert _closed(features) == set(features), f"{name} is missing what its features require" + + +def test_the_presets_name_features_this_repository_has(): + known = set(_catalog()["features"]) + + for name, features in _catalog()["presets"].items(): + assert set(features) <= known, name + for feature in features: + assert FEATURE_NAME.match(feature) + + +def test_full_is_every_feature(): + assert sorted(_catalog()["presets"]["full"]) == sorted(_catalog()["features"]) + + +ONE_OF_EACH = {"root_routers", "docs_guard", "email_sender", "cache_decorator", "scope_fingerprint"} +"""The points a project may fill once: each renders as a single value with a fallback.""" + + +def _ref(text: str) -> tuple[str, str, str]: + """A spec 1.4 ref, as (module, attribute, local name).""" + body, _, alias = text.partition(" as ") + module, _, attribute = body.partition(":") + + return module, attribute, alias or attribute + + +def _binding(entry: str) -> tuple[str, str, str]: + """What a wiring file under ``src/wiring/`` binds for this ref: (module, attribute, name). + + Spec 2.8: a file under the import root imports relatively, so ``src.a.b:name`` is read + from ``..a.b``. Anything outside it, such as ``scripts.seed``, is imported as written. + """ + module, attribute, alias = _ref(entry) + if module.startswith("src."): + module = ".." + module.removeprefix("src.") + + return module, attribute, alias + + +def _bindings(source: str) -> set[tuple[str, str, str]]: + """Every (module, attribute, local name) the imports in ``source`` bind. + + Read with ``ast`` rather than by matching text: names from one module share a statement, + and a long one wraps over several lines, and neither shape contains the single-name line a + substring check would look for. + """ + bindings: set[tuple[str, str, str]] = set() + for node in ast.parse(source).body: + if isinstance(node, ast.ImportFrom): + module = "." * node.level + (node.module or "") + bindings.update((module, alias.name, alias.asname or alias.name) for alias in node.names) + + return bindings + + +def _defines(module: str, attribute: str) -> bool: + """Whether ``module`` defines ``attribute`` at its top level, read without importing.""" + path = REPO_ROOT / "backend" / Path(*module.split(".")).with_suffix(".py") + if not path.exists(): + return False + + tree = ast.parse(path.read_text()) + for node in tree.body: + if isinstance(node, ast.Assign) and any( + isinstance(target, ast.Name) and target.id == attribute for target in node.targets + ): + return True + if isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name) and node.target.id == attribute: + return True + if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef) and node.name == attribute: + return True + if isinstance(node, ast.ImportFrom | ast.Import) and any( + (alias.asname or alias.name) == attribute for alias in node.names + ): + return True + + return False + + +@pytest.mark.parametrize("name", sorted(_catalog()["points"])) +def test_every_point_is_declared_the_way_the_spec_asks(name: str): + """Spec 2.3: a cardinality, and one line saying what the point collects.""" + point = _catalog()["points"][name] + + assert FEATURE_NAME.match(name) + assert point["cardinality"] in {"many", "one"} + assert point["doc"].strip() == point["doc"] + assert "\n" not in point["doc"] + + +def test_the_points_a_project_may_fill_once_are_the_ones_rendered_as_a_value(): + """A second contribution to one of these is an error, so the set has to be exact.""" + points = _catalog()["points"] + single = {name for name, point in points.items() if point["cardinality"] == "one"} + + assert single == ONE_OF_EACH + + +@pytest.mark.parametrize("entry", _catalog()["core"]["contributes"]["critical_readiness"]) +def test_every_core_contribution_names_something_that_exists(entry: str): + """Spec 1.4: the attribute has to be defined at the module's top level.""" + module, attribute, _ = _ref(entry) + + assert _defines(module, attribute), entry + + +def test_the_import_reader_sees_a_name_that_shares_a_statement(): + """Two names from one module in one statement, whose second name no line contains alone.""" + bindings = _bindings("from ..infrastructure.auth.health import limiter_readiness, sessions_readiness\n") + + assert ("..infrastructure.auth.health", "limiter_readiness", "limiter_readiness") in bindings + assert ("..infrastructure.auth.health", "sessions_readiness", "sessions_readiness") in bindings + + +def test_the_import_reader_sees_a_name_in_a_wrapped_import(): + """An import written over several lines, so no single line holds it.""" + bindings = _bindings("from ..infrastructure.composition import (\n PermissionSource,\n ReadinessCheck,\n)\n") + + assert ("..infrastructure.composition", "ReadinessCheck", "ReadinessCheck") in bindings + + +GENERATED_BY_WIRING = "backend/src/wiring/admin.py" +"""Written by a `[[wiring]]` entry for the admin feature, so no feature's paths declare it.""" + + +def _declared(feature: dict[str, Any]) -> list[tuple[str, str | None]]: + """A feature's declared paths, each with the condition it is kept under, if any.""" + paths: list[tuple[str, str | None]] = [(path.rstrip("/"), None) for path in feature.get("paths", ())] + for block in feature.get("when", ()): + paths.extend((path.rstrip("/"), block["if"]) for path in block.get("paths", ())) + + return paths + + +def _kept_by_the_catalog(features: dict[str, Any], chosen: set[str]) -> set[str]: + return { + path + for name, feature in features.items() + if name in chosen + for path, condition in _declared(feature) + if condition is None or _true(condition, chosen) + } + + +@pytest.mark.parametrize( + ("path", "kept_with"), + [ + ("backend/src/modules/user/admin.py", {"accounts", "admin"}), + ("backend/src/modules/api_keys/tasks.py", {"accounts", "api_keys", "taskiq"}), + ("backend/src/modules/api_keys/service.py", {"accounts", "api_keys"}), + ("backend/src/infrastructure/taskiq/worker.py", {"taskiq"}), + ("backend/src/infrastructure/taskiq/email.py", {"accounts", "taskiq"}), + ("backend/tests/unit/infrastructure/taskiq/test_email.py", {"accounts", "taskiq"}), + ("backend/src/modules/tier/admin.py", {"tiers", "admin"}), + ("backend/tests/unit/modules/tier/test_admin.py", {"tiers", "admin"}), + ("backend/src/modules/role/admin.py", {"rbac", "admin"}), + ("backend/tests/unit/modules/role/test_admin.py", {"rbac", "admin"}), + ("backend/tests/unit/modules/user/test_admin.py", {"accounts", "admin"}), + ("backend/tests/unit/modules/api_keys/test_tasks.py", {"api_keys", "taskiq"}), + ("backend/tests/integration/api_keys_rbac/test_effective_permissions.py", {"api_keys", "rbac"}), + ("backend/tests/integration/api_keys_ratelimit/test_invalid_keys.py", {"api_keys", "ratelimit"}), + ("backend/tests/integration/api_keys_tiers/test_reading_another_account.py", {"api_keys", "tier_limits"}), + ("backend/tests/unit/infrastructure/cache/test_scoped_callers.py", {"cache", "accounts"}), + ("backend/tests/integration/tier_limits/test_cached_listing.py", {"tier_limits", "cache"}), + ], +) +def test_a_file_is_kept_exactly_where_its_features_are(path: str, kept_with: set[str]): + """A file one feature brings into another's package is kept only when every feature it + needs is selected, and leaves when any one of them is missing.""" + features = _catalog()["features"] + declared = {declared for feature in features.values() for declared, _ in _declared(feature)} + + for chosen in _selections(): + kept_paths = _kept_by_the_catalog(features, chosen) + kept = _under(path, kept_paths) and not _under(path, _removed_for(features, chosen)) + assert kept is (kept_with <= chosen), sorted(chosen) + if path in declared: + assert (path in kept_paths) is (kept_with <= chosen), sorted(chosen) + + +def _local_names(point: str, chosen: set[str]) -> list[str]: + return [_ref(entry["ref"])[2] for entry in _contributed(_catalog(), point, chosen)] + + +def test_a_project_with_a_worker_queues_its_mail_and_one_without_hands_it_over(): + """No selection waits for a mail server: the fallback hands the delivery over.""" + fallback = next(slot for entry in _entries() for slot in entry["slots"] if slot.get("point") == "email_sender") + + assert fallback["fallback"] == "HandingOverSender(build_sender())" + for chosen in _selections(): + expected = ["queued_sender"] if {"accounts", "taskiq"} <= chosen else [] + assert _local_names("email_sender", chosen) == expected, sorted(chosen) + + +def test_a_project_with_accounts_wires_the_scope_fingerprint_and_one_without_wires_none(): + """Accounts contributes it, and the cache imports nothing of accounts to read it.""" + fallback = next(slot for entry in _entries() for slot in entry["slots"] if slot.get("point") == "scope_fingerprint") + + assert fallback["fallback"] == "None" + for chosen in _selections(): + expected = ["scope_fingerprint"] if "accounts" in chosen else [] + assert _local_names("scope_fingerprint", chosen) == expected, sorted(chosen) + + +def test_a_project_with_tiers_gives_a_new_account_the_default_tier_and_one_without_sets_nothing(): + for chosen in _selections(): + expected = ["default_tier"] if "tiers" in chosen else [] + assert _local_names("new_account_fields", chosen) == expected, sorted(chosen) + + +def test_a_project_drains_what_it_handed_over_with_the_worker_or_on_its_own(): + """Accounts hands its mail over, and drains it once: in the worker's lifecycle where there is + one, and in the handover's own where there isn't.""" + for chosen in _selections(): + names = _local_names("lifecycles", chosen) + + assert ("taskiq_lifecycle" in names) is ("taskiq" in chosen), sorted(chosen) + assert ("handover_lifecycle" in names) is ("accounts" in chosen and "taskiq" not in chosen), sorted(chosen) + + +def _closed(chosen: Iterable[str]) -> set[str]: + """A selection with everything its features require, and what that requires in turn.""" + features = _catalog()["features"] + selection = set(chosen) + while missing := {required for name in selection for required in features[name].get("requires", ())} - selection: + selection |= missing + + return selection + + +def _selections() -> list[set[str]]: + """Every selection a project could carry: each subset of the features, closed under requires.""" + closed: list[set[str]] = [] + for size in range(len(_catalog()["features"]) + 1): + for combination in itertools.combinations(_catalog()["features"], size): + selection = _closed(combination) + if selection not in closed: + closed.append(selection) + + return closed + + +def test_a_project_can_carry_164_selections(): + """The rules below that run over every selection have that many to run over.""" + assert len(_selections()) == 164 + + +@pytest.mark.parametrize("name", sorted(_catalog()["features"])) +def test_every_feature_is_declared_the_way_the_spec_asks(name: str): + """Spec 2.4: a one-line summary, and the heading the checklist groups it under.""" + feature = _catalog()["features"][name] + + assert FEATURE_NAME.match(name) + assert feature["summary"].strip() == feature["summary"] + assert "\n" not in feature["summary"] + assert feature["group"] in {"Accounts", "Operations"} + + +@pytest.mark.parametrize( + ("name", "condition"), + sorted((name, block["if"]) for name, feature in _catalog()["features"].items() for block in feature.get("when", ())), +) +def test_every_condition_names_a_feature_this_repository_has(name: str, condition: str): + """Spec 1.3: an unknown name is an error rather than something that reads as false.""" + assert condition in _catalog()["features"] + assert condition != name + + +@pytest.mark.parametrize( + "entry", + sorted( + {path for feature in _catalog()["features"].values() for path, _ in _declared(feature)}, + ), +) +def test_every_feature_path_is_one_this_repo_has(entry: str): + """A path that no longer exists leaves a file in projects that nobody meant to keep.""" + assert not entry.startswith("/") + assert ".." not in Path(entry).parts + assert (REPO_ROOT / entry).exists() + + +@pytest.mark.parametrize("name", sorted(_catalog()["features"])) +def test_a_directory_is_spelled_as_a_subtree_and_a_file_is_not(name: str): + """Spec 1.1: `src/modules/user` without the slash would name one file nobody has.""" + for path in _catalog()["features"][name].get("paths", ()): + assert path.endswith("/") == (REPO_ROOT / path).is_dir(), path + + for block in _catalog()["features"][name].get("when", ()): + for path in block.get("paths", ()): + assert path.endswith("/") == (REPO_ROOT / path).is_dir(), path + + +def test_no_path_is_declared_twice(): + """Spec 1.1: two declarations of the identical path are 'owned twice'.""" + declared = [path for feature in _catalog()["features"].values() for path, _ in _declared(feature)] + + assert sorted(declared) == sorted(set(declared)) + + +def test_the_generated_wiring_file_belongs_to_no_feature(): + """It is written by `[[wiring]]`, which leaves it out of a project rather than deleting it.""" + declared = {path for feature in _catalog()["features"].values() for path, _ in _declared(feature)} + + assert GENERATED_BY_WIRING in [entry["path"] for entry in _entries()] + assert GENERATED_BY_WIRING not in declared + + +def test_the_app_the_verification_imports_is_this_project_s_own(): + """Spec 2.2: a dotted module whose first part is `import_root`, and whose file this repository + has. Without it `blueprint verify` skips the app-import check, which is the one that catches a + feature removal that left something importing what went.""" + blueprint = _catalog()["blueprint"] + module = _catalog()["verify"]["app"] + path = REPO_ROOT / blueprint["python_root"] / Path(*module.split(".")).with_suffix(".py") + + assert module.split(".")[0] == blueprint["import_root"] + assert path.is_file(), module + assert _defines(module, "app"), "the check imports the module for its app" + + +def test_the_toolchain_environment_is_what_the_app_needs_to_import(): + """Spec 2.12: names and string values only. They are test values for checking a project + rather than secrets: a memory session store, a memory limiter, the local environment, and a + key that exists only so the settings validate. + """ + declared = _catalog()["checks"]["toolchain"]["env"] + + assert set(declared) == {"ENVIRONMENT", "SECRET_KEY", "SESSION_BACKEND", "RATE_LIMITER_BACKEND"} + for name, value in declared.items(): + assert ENV_VAR.match(name), name + assert isinstance(value, str), name + + assert len(declared["SECRET_KEY"]) >= 32, "the settings refuse a shorter one" + assert declared["SECRET_KEY"] not in ENV_EXAMPLE.read_text(), "not the example's placeholder" + + +def _true(condition: str, chosen: set[str]) -> bool: + """Whether a spec 1.3 condition holds for this selection.""" + tokens = re.findall(r"\(|\)|[^\s()]+", condition) + position = 0 + + def expression() -> bool: + value = conjunction() + nonlocal position + while position < len(tokens) and tokens[position] == "or": + position += 1 + value = conjunction() or value + + return value + + def conjunction() -> bool: + value = negation() + nonlocal position + while position < len(tokens) and tokens[position] == "and": + position += 1 + value = negation() and value + + return value + + def negation() -> bool: + nonlocal position + if tokens[position] == "not": + position += 1 + + return not negation() + + return atom() + + def atom() -> bool: + nonlocal position + token = tokens[position] + position += 1 + if token == "(": + value = expression() + assert tokens[position] == ")", condition + position += 1 + + return value + + if "=" in token: + raise NotImplementedError(f"{token!r} names an option; this test only selects features.") + + return token in chosen + + held = expression() + assert position == len(tokens), condition + + return held + + +def _tables(entries: Any) -> list[dict[str, Any]]: + """Spec 1.5: a contribution is a bare ref or a table, and reads the same either way.""" + return [{"ref": entry} if isinstance(entry, str) else dict(entry) for entry in entries] + + +def _contributed(catalog: dict[str, Any], point: str, chosen: set[str]) -> list[dict[str, Any]]: + """What reaches a point for this selection, in the order spec 2.7 sorts it.""" + collected = [(index, -1, 0, table) for index, table in enumerate(_tables(catalog["core"]["contributes"].get(point, ())))] + + for index, (name, feature) in enumerate(catalog["features"].items()): + if name not in chosen: + continue + + entries = list(feature.get("contributes", {}).get(point, ())) + for block in feature.get("when", ()): + if _true(block["if"], chosen): + entries.extend(block.get("contributes", {}).get(point, ())) + + for position, table in enumerate(_tables(entries)): + if "if" in table and not _true(table["if"], chosen): + continue + + collected.append((table.get("order", (index + 1) * 100 + position), index, position, table)) + + return [table for *_, table in sorted(collected, key=lambda entry: entry[:3])] + + +def _defined(source: str, name: str) -> ast.AST | None: + """The value assigned to ``name``, or the class defined under it.""" + for node in ast.parse(source).body: + if isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name) and node.target.id == name: + return node.value + if isinstance(node, ast.Assign) and any(isinstance(t, ast.Name) and t.id == name for t in node.targets): + return node.value + if isinstance(node, ast.ClassDef) and node.name == name: + return node + + return None + + +def test_every_declared_point_is_contributed_to_or_filled_by_core(): + """A point no feature and no core contribution reaches would render empty for every project.""" + catalog = _catalog() + reached = set(catalog["core"]["contributes"]) + for feature in catalog["features"].values(): + reached.update(feature.get("contributes", {})) + for block in feature.get("when", ()): + reached.update(block.get("contributes", {})) + + assert set(catalog["points"]) == reached + + +def test_every_contribution_names_something_that_exists(): + """Spec 1.4: a ref's attribute has to be defined at the top level of its module.""" + catalog = _catalog() + everything = set(catalog["features"]) + + for point in catalog["points"]: + for entry in _contributed(catalog, point, everything): + if "value" in entry: + continue + + module, attribute, _ = _ref(entry["ref"]) + assert _defines(module, attribute), entry + + +def test_a_point_a_project_fills_once_never_receives_two_contributions(): + """Spec 2.6: a second contribution to a `value` slot is an error rather than a last-wins.""" + catalog = _catalog() + single = {name for name, point in catalog["points"].items() if point["cardinality"] == "one"} + + for chosen in _selections(): + for point in single: + assert len(_contributed(catalog, point, chosen)) <= 1, (point, sorted(chosen)) + + +def test_a_transport_that_is_constructed_says_so(): + """Spec 1.5: `call` is what renders `APIKeyTransport()` rather than the class itself.""" + catalog = _catalog() + everything = set(catalog["features"]) + entry = _contributed(catalog, "extra_transports", everything)[0] + rendered = _defined(_committed("backend/src/wiring/transports.py"), "EXTRA_TRANSPORTS") + + assert entry["call"] is True + assert isinstance(rendered, ast.Tuple) and isinstance(rendered.elts[0], ast.Call) + + +@pytest.mark.parametrize( + "condition", + sorted( + {block["if"] for feature in _catalog()["features"].values() for block in feature.get("when", ())} + | { + entry["if"] + for feature in _catalog()["features"].values() + for entries in feature.get("contributes", {}).values() + for entry in _tables(entries) + if "if" in entry + } + ), +) +def test_every_condition_is_one_this_test_can_evaluate(condition: str): + """An option atom would need a selection to carry option values, which this test doesn't.""" + assert _true(condition, set(_catalog()["features"])) in {True, False} + + +@pytest.mark.parametrize( + ("feature", "option"), + sorted((name, option) for name, feature in _catalog()["features"].items() for option in feature.get("options", {})), +) +def test_every_option_is_declared_the_way_the_spec_asks(feature: str, option: str): + """Spec 2.5: named choices, listed once, with the default among them.""" + declared = _catalog()["features"][feature]["options"][option] + + assert FEATURE_NAME.match(option) + assert declared["choices"] == sorted(set(declared["choices"]), key=declared["choices"].index) + assert all(choice and not re.search(r"[\s()=]", choice) for choice in declared["choices"]) + assert declared["default"] in declared["choices"] + assert all(re.match(r"^[A-Za-z_][A-Za-z0-9_]*$", name) for name in declared.get("env", {})) + + +EXTRA_SERVICES = { + ("cache", "backend"): {"memcached": ["memcached"]}, + ("taskiq", "broker"): {"rabbitmq": ["rabbitmq"]}, +} +"""The service each choice needs on top of what a project already runs, which is redis.""" + + +@pytest.mark.parametrize(("feature", "option"), sorted(EXTRA_SERVICES)) +def test_every_extra_service_an_option_asks_for_belongs_to_one_of_its_choices(feature: str, option: str): + """Spec 2.5: the key is the value that needs the service, so a typo would ask for nothing.""" + declared = _catalog()["features"][feature]["options"][option] + services = declared.get("services", {}) + + assert set(services) <= set(declared["choices"]) + assert services == EXTRA_SERVICES[(feature, option)] + assert declared["default"] not in services + + +OPTION_SOURCES = { + ("cache", "backend"): ("src/infrastructure/cache/initialize.py", "CacheBackend"), + ("taskiq", "broker"): ("src/infrastructure/taskiq/settings.py", "TaskiqBrokerType"), +} +"""Where each option's choices are acted on, and the enum whose members name them.""" + + +@pytest.mark.parametrize(("feature", "option"), sorted(OPTION_SOURCES)) +def test_every_option_offers_the_values_its_feature_acts_on(feature: str, option: str): + """`CacheBackend` also names an in-memory backend that nothing starts, so it isn't offered.""" + module, enum = OPTION_SOURCES[(feature, option)] + acted_on = re.findall(rf"{enum}\.([A-Z_]+)\.value", (REPO_ROOT / "backend" / module).read_text()) + + assert sorted(set(acted_on)) == sorted( + choice.upper() for choice in _catalog()["features"][feature]["options"][option]["choices"] + ) + + +ENV_EXAMPLE = REPO_ROOT / "backend" / ".env.example" + +NOT_A_SETTING = { + "FORWARDED_ALLOW_IPS": "core", +} +"""Variables the example sets that no settings field takes: `FORWARDED_ALLOW_IPS` is read by +uvicorn and written by the deploy templates, never by the app.""" + + +def _alias_names(node: ast.AnnAssign) -> set[str]: + """The names a field accepts besides its own, which is how one feature's setting reads + another's: `SESSION_REDIS_HOST` takes `CACHE_REDIS_HOST` when nothing sets it.""" + names: set[str] = set() + for given in getattr(node.value, "keywords", ()): + if given.arg != "validation_alias": + continue + + if isinstance(given.value, ast.Constant) and isinstance(given.value.value, str): + names.add(given.value.value) + else: + names.update( + argument.value + for argument in getattr(given.value, "args", ()) + if isinstance(argument, ast.Constant) and isinstance(argument.value, str) + ) + + return names + + +@functools.cache +def _settings_fields() -> dict[str, frozenset[str]]: + """Which parts of the project take each setting: `core`, or the features whose contributed + settings classes declare it, counting the names a field accepts as aliases as well.""" + modules: dict[str, list[Path]] = {"core": [REPO_ROOT / "backend/src/infrastructure/config/base.py"]} + for name, feature in _catalog()["features"].items(): + for entry in feature.get("contributes", {}).get("settings", ()): + module, _, _ = _ref(entry if isinstance(entry, str) else entry["ref"]) + modules.setdefault(name, []).append(REPO_ROOT / "backend" / Path(*module.split(".")).with_suffix(".py")) + + declared: dict[str, set[str]] = {} + for owner, paths in modules.items(): + for path in paths: + for node in ast.walk(ast.parse(path.read_text())): + if isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name) and node.target.id.isupper(): + for name in {node.target.id} | _alias_names(node): + declared.setdefault(name, set()).add(owner) + + return {name: frozenset(owners) for name, owners in declared.items()} + + +@functools.cache +def _env_comments() -> dict[str, tuple[str, ...]]: + """Each section's comment lines, less its markers, which name variables as data.""" + lines = ENV_EXAMPLE.read_text().splitlines() + rule = re.compile(r"^# ={10,}$") + headers = [ + index + for index, line in enumerate(lines) + if rule.match(line) and index + 2 < len(lines) and rule.match(lines[index + 2]) + ] + + comments = {} + for position, start in enumerate(headers): + end = headers[position + 1] if position + 1 < len(headers) else len(lines) + comments[lines[start + 1].lstrip("# ").strip()] = tuple( + line for line in lines[start + 3 : end] if line.lstrip().startswith("#") and "@fastro" not in line + ) + + return comments + + +@functools.cache +def _env_sections() -> tuple[tuple[str, str | None, tuple[str, ...]], ...]: + """Each section of the example: its title, the marker directly below its header if it carries + one, and the variables it sets, including the ones it ships commented out, since a reader + uncomments them where they sit.""" + lines = ENV_EXAMPLE.read_text().splitlines() + rule = re.compile(r"^# ={10,}$") + headers = [ + index + for index, line in enumerate(lines) + if rule.match(line) and index + 2 < len(lines) and rule.match(lines[index + 2]) + ] + + sections = [] + for position, start in enumerate(headers): + end = headers[position + 1] if position + 1 < len(headers) else len(lines) + variables = tuple( + found.group(1) for line in lines[start + 3 : end] if (found := re.match(r"^#?\s*([A-Z][A-Z0-9_]*)=", line)) + ) + marker = lines[start + 3] if start + 3 < end and lines[start + 3].startswith("# @fastro ") else None + sections.append((lines[start + 1].lstrip("# ").strip(), marker, variables)) + + return tuple(sections) + + +def _owner_of(variable: str) -> frozenset[str]: + fields = _settings_fields() + if variable in fields: + return fields[variable] + + assert variable in NOT_A_SETTING, f"{variable} is in the example and nothing declares it" + + return frozenset({NOT_A_SETTING[variable]}) + + +def _owners_of(title: str) -> set[str]: + """Every part of the project that takes any of this section's variables.""" + variables = next(found for name, _, found in _env_sections() if name == title) + + return {owner for variable in variables for owner in _owner_of(variable)} + + +def _common_owners_of(title: str) -> set[str]: + """The parts that take *every* variable in the section, which is what a marker can name.""" + variables = next(found for name, _, found in _env_sections() if name == title) + + return set.intersection(*(set(_owner_of(variable)) for variable in variables)) if variables else {"core"} + + +def _marked_feature(title: str) -> str: + marker = next(found for name, found, _ in _env_sections() if name == title) + + return marker.removeprefix("# @fastro if=") if marker else "core" + + +@pytest.mark.parametrize("title", [title for title, _, _ in _env_sections()]) +def test_every_section_of_the_example_belongs_to_one_feature_or_to_the_core(title: str): + """Spec 6.1 keeps or drops a section whole, so a section can hold one feature's variables or + the core's, never both: dropping a mixed one would take `SECRET_KEY` from every project + without accounts. + """ + assert _common_owners_of(title), sorted(_owners_of(title)) + + +@pytest.mark.parametrize("title", [title for title, _, _ in _env_sections()]) +def test_every_section_a_feature_owns_says_which_feature_keeps_it(title: str): + """Spec 6.1: the marker is a line of its own directly below the header's closing rule, and + the section goes when its condition is false. A core section carries none, because a project + keeps it whatever it selected. + """ + common = _common_owners_of(title) + marker = next(found for name, found, _ in _env_sections() if name == title) + + if common == {"core"}: + assert marker is None, title + + return + + assert marker is not None, sorted(common) + assert marker.removeprefix("# @fastro if=") in common - {"core"} + + +@pytest.mark.parametrize("title", [title for title, _, _ in _env_sections()]) +def test_no_section_sends_a_reader_to_a_variable_another_feature_owns(title: str): + """A kept section has to read on its own: a project that selected one feature and not another + would otherwise be told to set something it hasn't got, with nowhere to set it. + + Only variables this section's own feature declares, or the core's, may be named. The + production checklist is the reason this exists: it used to name eight of them. + """ + mine = {_marked_feature(title)} + named = { + word + for line in _env_comments()[title] + for word in re.findall(r"\b[A-Z][A-Z0-9_]{2,}\b", line) + if word in _settings_fields() or word in NOT_A_SETTING + } + + assert {word: sorted(_owner_of(word)) for word in named if not _owner_of(word) & (mine | {"core"})} == {} + + +@functools.cache +def _fields_falling_back_to_another_feature() -> dict[str, frozenset[str]]: + """Fields that read another feature's variable when nothing sets their own, with the features + whose names they borrow. `SESSION_REDIS_HOST` takes `CACHE_REDIS_HOST`, so a project with + accounts and no cache has nothing in its example pointing sessions at Redis.""" + fields: dict[str, set[str]] = {} + for name, feature in _catalog()["features"].items(): + for entry in feature.get("contributes", {}).get("settings", ()): + module, _, _ = _ref(entry if isinstance(entry, str) else entry["ref"]) + path = REPO_ROOT / "backend" / Path(*module.split(".")).with_suffix(".py") + for node in ast.walk(ast.parse(path.read_text())): + if not isinstance(node, ast.AnnAssign) or not isinstance(node.target, ast.Name): + continue + + borrowed = { + owner for alias in _alias_names(node) - {node.target.id} for owner in _owner_of(alias) if owner != name + } + if borrowed: + fields.setdefault(node.target.id, set()).update(borrowed) + + return {name: frozenset(owners) for name, owners in fields.items()} + + +@pytest.mark.parametrize("field", sorted(_fields_falling_back_to_another_feature())) +def test_every_setting_that_borrows_another_features_variable_is_named_in_its_own_section(field: str): + """Otherwise the only line that sets it is the other feature's, and a project without that + feature is left with the default: for the session Redis, `localhost`, which is not the + service name the compose stack publishes. + + The line may be commented out. It is there to be found and uncommented, and a live one would + beat the borrowed value rather than fall back to it. + """ + owners = _owner_of(field) - _fields_falling_back_to_another_feature()[field] + sections = {title: variables for title, _, variables in _env_sections()} + theirs = [title for title in sections if _marked_feature(title) in owners] + + assert theirs, sorted(owners) + assert any(field in sections[title] for title in theirs), ( + f"{field} is set only by {sorted(_fields_falling_back_to_another_feature()[field])}" + ) + + +def test_the_comments_are_read_the_way_they_are_written(): + """The reading above: comments that stopped being found would leave it nothing to object to.""" + comments = _env_comments() + + assert any("SECRET_KEY" in line for line in comments["Production Security Checklist"]) + assert any("CACHE_REDIS_DB" in line for line in comments["Cache Configuration"]) + assert not any("@fastro" in line for section in comments.values() for line in section) + + +def test_no_marker_sits_anywhere_but_under_a_header(): + """A marker further down would speak for the lines after it, which spec 6.1 doesn't read: + the section is what the condition keeps or drops.""" + lines = ENV_EXAMPLE.read_text().splitlines() + marked = [line for line in lines if line.startswith("# @fastro if=")] + under_headers = [marker for _, marker, _ in _env_sections() if marker is not None] + + assert marked == under_headers + assert all(_true(marker.removeprefix("# @fastro if="), set(_catalog()["features"])) for marker in marked) + + +ADMIN_GUIDE = REPO_ROOT / "docs" / "user-guide" / "admin-panel" / "configuration.md" + +QUOTED_EXAMPLE = "The default `.env.example`" +"""Where that guide quotes the example, which is the one place the docs reproduce its values.""" + + +def test_the_guide_quotes_the_example_as_it_ships(): + """A quoted value that drifts from the file is a reader setting up a panel that stays dark, or + serving one they thought was off: the example keeps the admin panel off, as the setting's own + default has since 0.20.0.""" + guide = ADMIN_GUIDE.read_text() + quoted = guide[guide.index(QUOTED_EXAMPLE) :].split("```")[1].removeprefix("env\n") + shipped = dict(line.split("=", 1) for line in ENV_EXAMPLE.read_text().splitlines() if re.match(r"^[A-Z][A-Z0-9_]*=", line)) + + assert "ADMIN_ENABLED=false" in quoted, "the example ships the panel off" + for line in quoted.splitlines(): + name, _, value = line.partition("=") + assert shipped[name] == value, name + + +FIRST_RUN = REPO_ROOT / "docs" / "getting-started" + +NEARBY_LINES = 2 +"""How far from a mention of the panel the flag may be and still be read as part of the same claim.""" + + +@pytest.mark.parametrize("page", sorted(path.name for path in FIRST_RUN.glob("*.md"))) +def test_no_first_run_page_offers_the_admin_panel_without_saying_what_turns_it_on(page: str): + """A new reader follows these pages in order, and `/admin` answers 404 until the flag is set + and both credentials are there. A page that lists it among the things that now work sends + that reader to look for a bug of their own.""" + lines = (FIRST_RUN / page).read_text().splitlines() + unexplained = [ + line + for index, line in enumerate(lines) + if "/admin" in line and "ADMIN_ENABLED" not in "\n".join(lines[max(0, index - NEARBY_LINES) : index + NEARBY_LINES + 1]) + ] + + assert unexplained == [] + + +def test_the_example_is_read_the_way_it_is_written(): + """The reading itself: a parse that found no sections, or missed the commented-out lines, + would leave the rule above with nothing to object to.""" + sections = {title: variables for title, _, variables in _env_sections()} + + assert len(sections) >= 15 + assert "CREATE_TABLES_ON_STARTUP" in sections["Database Configuration"], "a line shipped commented out" + assert _owner_of("SECRET_KEY") == frozenset({"core"}) + assert _owner_of("CACHE_BACKEND") == frozenset({"cache"}) + assert _owner_of("SESSION_REDIS_URL") == frozenset({"accounts"}) + assert _owner_of("CACHE_REDIS_HOST") == frozenset({"accounts", "cache"}), "the session host takes it too" + + +@pytest.mark.parametrize(("feature", "option"), sorted(OPTION_SOURCES)) +def test_every_option_defaults_to_what_the_project_already_ships(feature: str, option: str): + """The question `fastro new` asks pre-picks the value a clone of this repo runs with.""" + declared = _catalog()["features"][feature]["options"][option] + example = (REPO_ROOT / "backend" / ".env.example").read_text() + + for variable in declared["env"]: + assert f"\n{variable}={declared['default']}\n" in example + + +@pytest.mark.parametrize(("feature", "option"), sorted(OPTION_SOURCES)) +def test_every_option_marks_the_line_it_rewrites(feature: str, option: str): + """Spec 6.1: the marker sits on its own line directly above the VAR line it speaks for.""" + declared = _catalog()["features"][feature]["options"][option] + lines = (REPO_ROOT / "backend" / ".env.example").read_text().splitlines() + + for variable in declared["env"]: + marked = [index for index, line in enumerate(lines) if line == f"# @fastro option={feature}.{option}"] + assert len(marked) == 1 + assert lines[marked[0] + 1].startswith(f"{variable}=") + + +SLOT_KINDS = {"tuple", "list", "class", "value", "reexport", "raw", "data"} +"""Spec 2.6. A kind the engine doesn't know would be a slot nothing renders.""" + + +def _entries() -> list[dict[str, Any]]: + return list(_catalog()["wiring"]) + + +def _committed(path: str) -> str: + return (REPO_ROOT / path).read_text() + + +def _annotated(source: str, name: str) -> str | None: + """How the committed file spells this name's annotation.""" + for node in ast.parse(source).body: + if isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name) and node.target.id == name: + return ast.unparse(node.annotation) + + return None + + +@pytest.mark.parametrize("path", [entry["path"] for entry in _entries()]) +def test_every_wiring_file_is_under_the_python_root_and_is_a_file(path: str): + """Spec 2.6: a generated Python file lives under `python_root`, and names one file.""" + blueprint = _catalog()["blueprint"] + + assert path.startswith(blueprint["python_root"] + "/") + assert not path.endswith("/") + assert (REPO_ROOT / path).is_file() + + +@pytest.mark.parametrize( + ("path", "name"), + [(entry["path"], slot["name"]) for entry in _entries() for slot in entry["slots"] if "annotation" in slot], +) +def test_every_annotated_slot_is_annotated_the_way_the_file_annotates_it(path: str, name: str): + """`NAME: ANNOTATION` is what mypy and an IDE read, so the catalog has to spell it the same.""" + slot = next(slot for slot in next(e for e in _entries() if e["path"] == path)["slots"] if slot.get("name") == name) + + assert _annotated(_committed(path), name) == slot["annotation"] + + +@pytest.mark.parametrize( + ("path", "name"), + [(entry["path"], slot["name"]) for entry in _entries() for slot in entry["slots"] if "name" in slot], +) +def test_every_slot_fills_a_name_the_file_defines(path: str, name: str): + assert _defined(_committed(path), name) is not None or name in {alias for _, _, alias in _bindings(_committed(path))} + + +def test_every_declared_point_is_filled_by_exactly_one_slot(): + """One direction: a point no slot collects is a point whose contributions reach nothing.""" + filled = [slot["point"] for entry in _entries() for slot in entry["slots"] if "point" in slot] + + assert sorted(filled) == sorted(_catalog()["points"]) + + +def test_every_slot_collects_a_point_the_catalog_declares(): + """The other direction: a slot naming an undeclared point would collect nothing for ever.""" + declared = set(_catalog()["points"]) + + for entry in _entries(): + for slot in entry["slots"]: + if slot["kind"] == "raw": + assert "point" not in slot and "name" not in slot + continue + + assert slot["point"] in declared, slot + + +@pytest.mark.parametrize( + ("path", "kind"), + [(entry["path"], slot["kind"]) for entry in _entries() for slot in entry["slots"]], +) +def test_every_slot_is_a_kind_the_spec_has(path: str, kind: str): + assert kind in SLOT_KINDS + + +def test_every_point_a_project_fills_once_is_rendered_as_one_value(): + """Spec 2.6: `value`, `class` and `reexport` render one, and each needs its fallback.""" + cardinality = {name: point["cardinality"] for name, point in _catalog()["points"].items()} + + for entry in _entries(): + for slot in entry["slots"]: + if slot["kind"] in {"value", "reexport"}: + assert cardinality[slot["point"]] == "one", slot + assert "fallback" in slot, slot + if slot["kind"] in {"tuple", "list"}: + assert cardinality[slot["point"]] == "many", slot + + +def test_the_file_a_feature_brings_with_it_is_generated_only_for_that_feature(): + """FR003: without admin the file is absent from the project, not emptied.""" + admin = next(entry for entry in _entries() if entry["path"].endswith("wiring/admin.py")) + + assert admin["if"] == "admin" + assert [entry.get("if") for entry in _entries()].count(None) == 13 + + +def test_the_statement_a_raw_slot_carries_is_in_the_file(): + """`settings = Settings()` is what the rest of the project imports, and no point fills it.""" + raw = [slot for entry in _entries() for slot in entry["slots"] if slot["kind"] == "raw"] + committed = _committed("backend/src/wiring/settings.py") + + assert [slot["code"] for slot in raw] == ["settings = Settings()"] + assert "settings = Settings()" in committed + + +def _declared_bindings(catalog: dict[str, Any], entry: dict[str, Any], chosen: set[str]) -> set[tuple[str, str, str]]: + """Every name the catalog says this file binds: its own imports, and what reaches its slots.""" + bindings: set[tuple[str, str, str]] = set() + for line in entry.get("imports", ()): + module, _, names = line.removeprefix("from ").partition(" import ") + bindings.update((module, name, name) for name in names.split(", ")) + + for slot in entry["slots"]: + if slot["kind"] == "raw": + continue + + contributed = _contributed(catalog, slot["point"], chosen) + if contributed and not slot.get("literal"): + bindings.update(_binding(contribution["ref"]) for contribution in contributed if "ref" in contribution) + for line in slot.get("item_imports", ()): + module, _, names = line.removeprefix("from ").partition(" import ") + bindings.update((module, name, name) for name in names.split(", ")) + + if not contributed: + for line in slot.get("fallback_imports", ()): + module, _, names = line.removeprefix("from ").partition(" import ") + bindings.update((module, name, name) for name in names.split(", ")) + if ":" in slot.get("fallback", ""): + bindings.add(_binding(slot["fallback"])) + + bindings.update(_binding(ref) for ref in slot.get("append", ())) + + return bindings + + +@pytest.mark.parametrize("path", [entry["path"] for entry in _entries()]) +def test_the_catalog_accounts_for_every_name_the_file_imports(path: str): + """An import the entry forgets is a NameError in a project nobody has built yet. + + The committed files carry every feature, so with everything selected the names the + catalog brings and the names the file binds are the same set, both ways. + """ + catalog = _catalog() + entry = next(entry for entry in _entries() if entry["path"] == path) + + assert _declared_bindings(catalog, entry, set(catalog["features"])) == _bindings(_committed(path)) + + +def _refs_of(slot: dict[str, Any]) -> list[str]: + """The refs a slot names itself: its fallback, and the bases it always appends.""" + refs = list(slot.get("append", ())) + if ":" in slot.get("fallback", ""): + refs.append(slot["fallback"]) + + return refs + + +def test_every_ref_a_slot_names_itself_exists(): + """A fallback is what a project without the feature gets, so it has to be importable there.""" + named = [(entry["path"], ref) for entry in _entries() for slot in entry["slots"] for ref in _refs_of(slot)] + + assert sorted(ref for _, ref in named) == [ + "pydantic:BaseModel", + "src.infrastructure.config.base:CoreSettings", + "src.infrastructure.uncached:cached", + ] + + for path, ref in named: + module, attribute, _ = _ref(ref) + if module.startswith("src."): + assert _defines(module, attribute), (path, ref) + else: + assert hasattr(importlib.import_module(module), attribute), (path, ref) + + +def test_every_import_a_fallback_needs_names_something_that_exists(): + """Spec 2.6: these lines are emitted only when the fallback is used, so nothing else checks them.""" + lines = [ + (entry["path"], line) for entry in _entries() for slot in entry["slots"] for line in slot.get("fallback_imports", ()) + ] + + assert len(lines) == 2 + + for path, line in lines: + module, _, name = line.removeprefix("from ").partition(" import ") + assert path.startswith("backend/src/wiring/"), path + assert _defines("src." + module.lstrip("."), name), line + + +def test_the_header_every_generated_file_carries_is_fastros_own(): + """Spec 2.12, verbatim: a project's wiring says what wrote it and how to change it.""" + assert _catalog()["wiring_defaults"]["header"] == ( + "Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change\n" + "fastro.toml (or [app] in it, for your own code) and run `fastro sync`." + ) + + +def test_the_header_fits_the_line_length_of_the_files_it_goes_into(): + """Spec 2.8: each line is at most 100 characters, so a docstring passes E501 at 128.""" + for line in _catalog()["wiring_defaults"]["header"].splitlines(): + assert len(line) <= 100, line + + +HAND_WRITTEN = "backend/src/wiring/__init__.py" +"""The one module beside the generated ones that a person writes, and fastro never rewrites.""" + + +def _docstring(source: str) -> str | None: + """The module docstring as it is written, rather than as ``ast`` tidies it up.""" + body = ast.parse(source).body + if body and isinstance(body[0], ast.Expr) and isinstance(body[0].value, ast.Constant): + return str(body[0].value.value) + + return None + + +@pytest.mark.parametrize("path", [entry["path"] for entry in _entries()]) +def test_every_generated_file_carries_its_doc_and_then_the_header(path: str): + """Spec 2.8: the entry's `doc`, a blank line, then the header, each stripped before rendering. + + This is the whole docstring, so a paragraph the file carries and the catalog doesn't is one + `fastro sync` would delete from a project without being asked. + """ + entry = next(declared for declared in _entries() if declared["path"] == path) + header = _catalog()["wiring_defaults"]["header"] + + assert _docstring(_committed(path)) == f"{entry['doc'].strip()}\n\n{header.strip()}\n" + + +def test_the_hand_written_module_says_who_writes_the_ones_beside_it(): + """It is not generated, so it is where the reason lives: once, in the file a person edits.""" + docstring = _docstring(_committed(HAND_WRITTEN)) + + assert HAND_WRITTEN not in [entry["path"] for entry in _entries()] + assert docstring is not None + assert "fastro" in docstring + assert "blueprint.toml" in docstring + assert "imports and literals" in docstring + + +LINE_LENGTH = _catalog()["wiring_defaults"]["line_length"] +"""Spec 2.12: the length spec 2.8 wraps a generated import at, declared rather than assumed.""" + + +def test_the_generated_line_length_is_the_one_ruff_holds_the_project_to(): + """Spec 2.12: an integer from 1 to 320. Declared shorter than ruff's, fastro would wrap an + import ruff is happy with; longer, and `ruff format --check` fails on a file nobody edited. + """ + with BACKEND_PYPROJECT.open("rb") as handle: + backend = tomllib.load(handle) + + assert 1 <= LINE_LENGTH <= 320 + assert LINE_LENGTH == backend["tool"]["ruff"]["line-length"] + + +@pytest.mark.parametrize("path", [entry["path"] for entry in _entries()]) +def test_no_import_in_a_generated_file_is_wrapped_before_it_has_to_be(path: str): + """Spec 2.8: a statement is wrapped only when one line of it would be too long.""" + source = _committed(path) + for node in ast.parse(source).body: + if not isinstance(node, ast.Import | ast.ImportFrom): + continue + + one_line = ast.unparse(node) + wrapped = (node.end_lineno or node.lineno) > node.lineno + assert wrapped == (len(one_line) > LINE_LENGTH), one_line + + +@pytest.mark.parametrize( + ("path", "name"), + [(entry["path"], slot["name"]) for entry in _entries() for slot in entry["slots"] if slot["kind"] in {"tuple", "list"}], +) +def test_a_collection_of_more_than_one_is_written_one_entry_to_a_line(path: str, name: str): + """Spec 2.6: a tuple of two or more is always exploded, and a list always is.""" + slot = next(slot for slot in next(e for e in _entries() if e["path"] == path)["slots"] if slot.get("name") == name) + defined = _defined(_committed(path), name) + + assert isinstance(defined, ast.Tuple | ast.List) + exploded = (defined.end_lineno or defined.lineno) > defined.lineno + + assert exploded == (len(defined.elts) >= (1 if slot["kind"] == "list" else 2)) + + +PROJECT_FILE = REPO_ROOT / "fastro.toml" + +GENERATOR_NAME = re.compile(r"^[a-z][a-z0-9-]*$") +"""Spec 2.9. It becomes the word after `fastro make`, and `fastro make` takes no underscore.""" + +COMMAND_WORD = re.compile(r"^[a-z][a-z0-9-]*$") + +ENV_VAR = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$") +"""Spec 2.5 and 2.12: the name of an environment variable.""" + +PARAM_TYPES = {"int", "str", "bool", "cidr", "choice"} + +PYTHON_TYPES: dict[str, type] = {"int": int, "str": str, "bool": bool, "cidr": str, "choice": str} + + +@functools.cache +def _project() -> dict[str, Any]: + with PROJECT_FILE.open("rb") as handle: + return tomllib.load(handle) + + +def _owned_paths() -> set[str]: + return {path for feature in _catalog()["features"].values() for path, _ in _declared(feature)} + + +@pytest.mark.parametrize("name", sorted(_catalog()["generators"])) +def test_every_generator_is_named_the_way_fastro_make_reads_it(name: str): + assert GENERATOR_NAME.match(name) + assert "register" not in _catalog()["generators"][name] or name == "module" + assert "types" not in _catalog()["generators"][name] or name == "module" + + +@pytest.mark.parametrize("name", sorted(_catalog()["generators"])) +def test_every_generators_templates_are_a_directory_this_repo_has(name: str): + """Spec 2.9: subdirectories when the generator has modes, which is one tree per mode.""" + generator = _catalog()["generators"][name] + templates = REPO_ROOT / generator["templates"] + + assert templates.is_dir() + assert any(child.is_dir() for child in templates.iterdir()) + + +@pytest.mark.parametrize( + ("generator", "param"), + sorted((name, param) for name, declared in _catalog()["generators"].items() for param in declared["params"]), +) +def test_every_param_is_declared_the_way_the_spec_asks(generator: str, param: str): + """Spec 2.9: a type and a default of that type, and the keys each type allows.""" + declared = _catalog()["generators"][generator]["params"][param] + + assert FEATURE_NAME.match(param) + assert declared["type"] in PARAM_TYPES + assert isinstance(declared["default"], PYTHON_TYPES[declared["type"]]) + assert declared["type"] == "bool" or not isinstance(declared["default"], bool), "a bool is an int to isinstance" + assert declared["help"].strip() == declared["help"] + assert ("choices" in declared) == (declared["type"] == "choice") + for key in ("private_only", "max_prefix"): + assert key not in declared or declared["type"] == "cidr" + + +def test_the_subnet_default_is_a_network_with_no_host_bits_set(): + """Spec 2.9: `10.0.0.1/24` is not a network, and the tool would refuse the catalog for it.""" + declared = _catalog()["generators"]["deploy"]["params"]["internal_subnet"] + network = ipaddress.ip_network(declared["default"], strict=True) + + assert str(network) == declared["default"] + assert network.prefixlen >= declared["max_prefix"][f"v{network.version}"], "the default meets its own limit" + + +def test_the_subnet_limit_is_set_for_both_families(): + """Spec 2.9: a table with both `v4` (0 to 32) and `v6` (0 to 128), because one integer can't + carry the two. An IPv6 limit of 8 would accept a `/16`, which is half the address space. + """ + limits = _catalog()["generators"]["deploy"]["params"]["internal_subnet"]["max_prefix"] + + assert set(limits) == {"v4", "v6"} + assert 0 <= limits["v4"] <= 32 + assert 0 <= limits["v6"] <= 128 + + +def test_every_param_the_templates_read_is_a_param_the_catalog_declares(): + """Both ways: an undeclared param is a StrictUndefined crash, a declared one nothing reads is dead.""" + generator = _catalog()["generators"]["deploy"] + templates = REPO_ROOT / generator["templates"] + read = {name for template in templates.rglob("*.j2") for name in re.findall(r"params\.([a-z_]+)", template.read_text())} + + assert read == set(generator["params"]) + + +def _declared_commands() -> list[tuple[str | None, str, dict[str, Any]]]: + """Every declared command: the feature that owns it, or none, with its words and its table. + + A list rather than a table keyed by the words, because two declarations of one command are + what spec 2.9 refuses, and a table would quietly keep the second. + """ + declared: list[tuple[str | None, str, dict[str, Any]]] = [ + (None, words, command) for words, command in _catalog()["commands"].items() + ] + for name, feature in _catalog()["features"].items(): + declared.extend((name, words, command) for words, command in feature.get("commands", {}).items()) + + return declared + + +def _script_of(command: dict[str, Any]) -> str: + return f"{_catalog()['blueprint']['python_root']}/{Path(*command['module'].split('.')).with_suffix('.py')}" + + +def _under(script: str, paths: Iterable[str]) -> bool: + """Spec 1.1: a declaration names the file itself, or a subtree it sits in.""" + return any(script == path or script.startswith(f"{path}/") for path in paths) + + +def _sorted_commands() -> list[tuple[str | None, str, dict[str, Any]]]: + return sorted(_declared_commands(), key=lambda entry: entry[1]) + + +COMMANDS = [pytest.param(words, command, id=words) for _, words, command in _sorted_commands()] + +TOP_LEVEL_COMMANDS = [pytest.param(words, command, id=words) for owner, words, command in _sorted_commands() if owner is None] + +FEATURE_COMMANDS = [ + pytest.param(owner, words, command, id=words) for owner, words, command in _sorted_commands() if owner is not None +] + + +@pytest.mark.parametrize(("words", "command"), COMMANDS) +def test_every_command_is_spelled_the_way_the_spec_reads_it(words: str, command: dict[str, Any]): + """Spec 2.9: the words become the command path, one space apart.""" + assert all(COMMAND_WORD.match(word) for word in words.split(" ")) + assert " " not in words + assert all(part.isidentifier() and not keyword.iskeyword(part) for part in command["module"].split(".")) + assert command["help"].strip() == command["help"] + assert "\n" not in command["help"] + assert command.get("outside_project", "error") in {"error", "token_hex"} + + +@pytest.mark.parametrize(("words", "command"), COMMANDS) +def test_every_command_runs_a_module_this_repo_can_run(words: str, command: dict[str, Any]): + """It is run as `python -m `, which needs the entry point that makes that work.""" + path = REPO_ROOT / _catalog()["blueprint"]["python_root"] / Path(*command["module"].split(".")).with_suffix(".py") + + assert path.is_file(), words + assert '__name__ == "__main__"' in path.read_text() + + +def test_no_two_commands_claim_the_same_words(): + """Spec 2.9: the words are unique across `[commands]` and every feature's. + + fastro refuses the catalog at the second declaration, so a repeat is a catalog no project + can be generated from at all. + """ + claimed = [words for _, words, _ in _declared_commands()] + + assert sorted(claimed) == sorted(set(claimed)) + + +@pytest.mark.parametrize(("words", "command"), TOP_LEVEL_COMMANDS) +def test_every_command_runs_a_script_no_feature_takes_away(words: str, command: dict[str, Any]): + """`[commands]` are always present (spec 2.9), so one naming a feature's script would break. + + `scripts/unlock_account.py` goes with accounts, so it is accounts that declares + `fastro users unlock`: top-level, the command would be there in a project without the + module it runs. + """ + assert not _under(_script_of(command), _owned_paths()), words + + +@pytest.mark.parametrize(("owner", "words", "command"), FEATURE_COMMANDS) +def test_every_feature_command_sits_under_its_features_own_paths(owner: str, words: str, command: dict[str, Any]): + """Spec 2.9: under the feature's own `paths`, not a `when`'s, which a selection still drops.""" + declared = _declared(_catalog()["features"][owner]) + script = _script_of(command) + + assert _under(script, [path for path, condition in declared if condition is None]), words + assert not _under(script, [path for path, condition in declared if condition is not None]), words + + +def test_the_feature_commands_are_every_feature_owned_script_a_project_could_run(): + """Both ways, and against the repository rather than against the catalog's own account. + + A runnable script of a feature's own that nothing declares is a command no project is + offered, and a command for a module its feature doesn't own is one some project is left + without. + """ + python_root = _catalog()["blueprint"]["python_root"] + directory = REPO_ROOT / python_root / "scripts" + runnable = { + f"{python_root}/scripts/{script.name}" + for script in sorted(directory.glob("*.py")) + if _under(f"{python_root}/scripts/{script.name}", _owned_paths()) and '__name__ == "__main__"' in script.read_text() + } + + assert runnable, directory + assert {_script_of(command) for owner, _, command in _declared_commands() if owner is not None} == runnable + + +def test_every_selection_carries_the_commands_whose_module_it_keeps(): + """A feature's command is there only where the feature is (spec 2.4). + + That has to be exactly where the module it runs is still on disk: a command offered by a + project that cannot run it is worse than no command, and one a project could run but is + never offered is work thrown away. + """ + features = _catalog()["features"] + owned = _owned_paths() + + for chosen in _selections(): + kept = _kept_by_the_catalog(features, chosen) + offered = {words for owner, words, _ in _declared_commands() if owner is None or owner in chosen} + runnable = { + words + for _, words, command in _declared_commands() + if not _under(_script_of(command), owned) or _under(_script_of(command), kept) + } + + assert offered == runnable, sorted(chosen) + + +def test_the_blueprint_repo_says_it_is_the_blueprint(): + """Spec 3: `source = true` only in a blueprint repo, where generated files are committed.""" + assert _project()["source"] is True + assert _project()["blueprint"] == {"name": _catalog()["blueprint"]["name"], "version": _catalog()["blueprint"]["version"]} + + +def test_the_blueprint_repo_carries_every_feature(): + """It has to: the committed wiring is the `everything` selection, and the tests cover all nine.""" + assert _project()["features"] == list(_catalog()["features"]) + + +def test_the_blueprint_repo_runs_every_option_at_its_default(): + """Spec 6.1: the `.env.example` lines the options rewrite are the ones this repo ships.""" + declared = { + f"{name}.{option}": option_table["default"] + for name, feature in _catalog()["features"].items() + for option, option_table in feature.get("options", {}).items() + } + + assert _project()["options"] == declared + + +def test_the_project_is_named_the_way_its_python_package_is(): + """`project.name` is what the deploy templates name the compose project after (spec 6.2).""" + with BACKEND_PYPROJECT.open("rb") as handle: + backend = tomllib.load(handle) + + assert _project()["project"]["name"] == backend["project"]["name"] + + +RETIRED_NAME = "fastro".title() + +STILL_CARRYING_THE_RETIRED_NAME = { + "docs/changelog.md": "B9 item 15", + "docs/assets/build-cover.cjs": "B5", + "docs/assets/build-card.cjs": "B5", +} +"""Files left as they are until the item named beside each, which rewrites them.""" + + +def test_no_tracked_file_calls_the_blueprint_by_its_retired_name(): + """FastAPI-boilerplate is the blueprint, fastro the tool and FastroAI the paid blueprint: the + capitalised tool name, standing alone, names nothing. A wordmark that sets AI in its own + `` straight after it still spells FastroAI.""" + alone = re.compile(rf"\b{RETIRED_NAME}\b(?!]*>AI)") + tracked = subprocess.run(["git", "ls-files", "-z"], cwd=REPO_ROOT, capture_output=True, text=True, check=True) + found = [] + carrying = set() + for name in filter(None, tracked.stdout.split("\0")): + path = REPO_ROOT / name + if not path.is_file(): + continue + try: + text = path.read_text(encoding="utf-8") + except UnicodeDecodeError: + continue + hits = [f"{name}:{number}" for number, line in enumerate(text.splitlines(), 1) if alone.search(line)] + if name in STILL_CARRYING_THE_RETIRED_NAME: + carrying |= {name} if hits else set() + else: + found += hits + + assert not found, found + assert carrying == set(STILL_CARRYING_THE_RETIRED_NAME), "drop the exemption of a file that no longer carries it" diff --git a/backend/tests/unit/test_docs_imports.py b/backend/tests/unit/test_docs_imports.py index 5516fb52..22c5104a 100644 --- a/backend/tests/unit/test_docs_imports.py +++ b/backend/tests/unit/test_docs_imports.py @@ -6,8 +6,7 @@ The sweep checks that the module and the name exist, not that a relative import counts the right number of dots: a sample rarely says which file it belongs to. A relative import of a single name, ``.schemas``, is left alone -- which of them it -means depends on the file it sits in, and in a project with features removed the -name can turn unique and resolve to the wrong module. +means depends on the file it sits in. ``ILLUSTRATIVE_MODULES`` lists the modules the guides invent to show how a project of your own would look. @@ -15,16 +14,13 @@ import ast import importlib -import importlib.util import re -import sys from collections.abc import Iterator from pathlib import Path REPO_ROOT = Path(__file__).resolve().parents[3] DOCS_ROOT = REPO_ROOT / "docs" SRC_ROOT = REPO_ROOT / "backend" / "src" -DRILL_PATH = REPO_ROOT / "tools" / "removal_drill.py" PYTHON_BLOCK = re.compile(r"```python\n(.*?)```", re.DOTALL) @@ -33,45 +29,9 @@ "src.modules.reports", "src.modules.user.routes_v2", "src.interfaces.api.v2", - "src.infrastructure.observability", ) -def _manifest(): - """The drill's feature manifest, which says which paths each feature owns.""" - spec = importlib.util.spec_from_file_location("removal_drill_manifest", DRILL_PATH) - assert spec is not None and spec.loader is not None - manifest = importlib.util.module_from_spec(spec) - sys.modules[spec.name] = manifest - spec.loader.exec_module(manifest) - - return manifest - - -def _paths_of_features_left_out() -> tuple[str, ...]: - """The paths owned by the features this project doesn't carry, which its docs still show.""" - manifest = _manifest() - present = { - name - for name, feature in manifest.FEATURES.items() - if (sources := [path for path in feature.paths if path.startswith("backend/src")]) - and all((REPO_ROOT / path).exists() for path in sources) - } - - left_out: list[str] = [] - for name, feature in manifest.FEATURES.items(): - if name not in present: - left_out.extend(feature.paths) - for combination, paths in feature.combination_paths.items(): - if name not in present or combination not in present: - left_out.extend(paths) - - return tuple(left_out) - - -LEFT_OUT_PATHS = _paths_of_features_left_out() - - def _import_statements(block: str) -> Iterator[tuple[ast.ImportFrom, int]]: """Every ``from ... import ...`` in a code block, with the line it starts on.""" lines = block.splitlines() @@ -103,8 +63,7 @@ def _module_path(node: ast.ImportFrom) -> Path | None: An absolute import names its module from ``src``. A relative one names a suffix of at least two parts, resolved when exactly one module, or one package that would - hold it, matches. A package the project doesn't carry at all resolves to nothing, - so a sample for a feature this project removed is left alone. + hold it, matches. """ parts = (node.module or "").split(".") if node.level == 0: @@ -123,7 +82,7 @@ def _module_path(node: ast.ImportFrom) -> Path | None: if existing.exists(): return existing - return candidate.with_suffix(".py") if candidate.parent.is_dir() else None + return candidate.with_suffix(".py") suffix = "/".join(parts) modules = [path for path in SRC_ROOT.rglob(f"{parts[-1]}.py") if str(path).endswith(f"{suffix}.py")] @@ -160,9 +119,6 @@ def _missing(where: str, node: ast.ImportFrom, path: Path) -> list[str]: return [] if not path.exists(): - if LEFT_OUT_PATHS and str(path.relative_to(REPO_ROOT)).startswith(LEFT_OUT_PATHS): - return [] - return [f"{where}: no module {dotted}"] module = importlib.import_module(dotted) @@ -185,11 +141,7 @@ def test_every_documented_project_import_resolves(): def test_the_sweep_reads_the_samples_it_claims_to(): - """An extractor that quietly stopped matching would make the sweep above vacuous. - - Counts what every project carries, the documentation, rather than what the - selected features leave resolvable. - """ + """An extractor that quietly stopped matching would make the sweep above vacuous.""" blocks = [block.group(1) for document in DOCS_ROOT.rglob("*.md") for block in PYTHON_BLOCK.finditer(document.read_text())] statements = [node for block in blocks for node, _ in _import_statements(block)] diff --git a/backend/tests/unit/test_docs_scripts.py b/backend/tests/unit/test_docs_scripts.py index 194b09e9..b1f16e3a 100644 --- a/backend/tests/unit/test_docs_scripts.py +++ b/backend/tests/unit/test_docs_scripts.py @@ -18,6 +18,15 @@ """What a script a reader runs has, which the modules beside them do not.""" +MIGRATIONS = REPO_ROOT / "docs" / "user-guide" / "database" / "migrations.md" +"""The one guide whose manual recipe is a script of its own done by hand.""" + + +def test_the_migrations_guide_names_the_script_that_writes_the_baseline(): + """`scripts/baseline.py` does what that recipe does, and a reader has no way to know it.""" + assert "python -m scripts.baseline" in MIGRATIONS.read_text() + + def _runnable_scripts() -> list[str]: return sorted(path.name for path in SCRIPTS.glob("*.py") if RUNNABLE in path.read_text()) diff --git a/backend/tests/unit/test_docs_settings.py b/backend/tests/unit/test_docs_settings.py new file mode 100644 index 00000000..45d1dc70 --- /dev/null +++ b/backend/tests/unit/test_docs_settings.py @@ -0,0 +1,127 @@ +"""Every settings class the documentation names is one the code has. + +A page that sends a reader to a class that isn't there leaves them grepping for it. A +class a page defines in its own sample, to show how a project's settings would look, is +the page's own; pydantic's ``BaseSettings`` is pydantic's; the changelog names classes as +they were when each release shipped. +""" + +import ast +import importlib +import inspect +import re +from pathlib import Path + +from pydantic_settings import BaseSettings + +REPO_ROOT = Path(__file__).resolve().parents[3] +SRC_ROOT = REPO_ROOT / "backend" / "src" +PAGES = sorted([*(REPO_ROOT / "docs").rglob("*.md"), REPO_ROOT / "README.md"]) +HISTORY = REPO_ROOT / "docs" / "changelog.md" + +SETTINGS_NAME = re.compile(r"\b[A-Z][A-Za-z]*Settings\b") +BACKTICKED_SETTINGS = re.compile(r"`([A-Z][A-Za-z]*Settings)`") +SOURCE_PATH = re.compile(r"`(?:backend/)?(src/[\w/]+\.py)`") +TABLE_ROW = re.compile(r"^\| `([A-Z][A-Za-z]*Settings)` \| (.+) \|$") +BACKTICKED_FIELD = re.compile(r"`([A-Z][A-Z0-9_*]+)`") +DEFINED_IN_A_SAMPLE = re.compile(r"^\s*class ([A-Z][A-Za-z]*Settings)\b", re.MULTILINE) + + +def _classes_in_the_code() -> set[str]: + return { + node.name + for path in SRC_ROOT.rglob("*.py") + for node in ast.walk(ast.parse(path.read_text())) + if isinstance(node, ast.ClassDef) + } + + +def test_every_settings_class_a_page_names_exists(): + known = _classes_in_the_code() | {"BaseSettings"} + missing = [] + for page in PAGES: + if page == HISTORY: + continue + text = page.read_text() + own = set(DEFINED_IN_A_SAMPLE.findall(text)) + for number, line in enumerate(text.splitlines(), 1): + missing += [ + f"{page.relative_to(REPO_ROOT)}:{number}: {name}" + for name in SETTINGS_NAME.findall(line) + if name not in known and name not in own + ] + + assert not missing, "\n".join(missing) + + +def _defined_in(path: Path) -> set[str]: + return {node.name for node in ast.walk(ast.parse(path.read_text())) if isinstance(node, ast.ClassDef)} + + +def test_a_settings_class_named_beside_a_module_is_defined_in_it(): + """A line that sends the reader to a file for a class sends them to the file that defines it.""" + wrong = [] + for page in PAGES: + if page == HISTORY: + continue + for number, line in enumerate(page.read_text().splitlines(), 1): + modules = [REPO_ROOT / "backend" / path for path in SOURCE_PATH.findall(line)] + classes = set(BACKTICKED_SETTINGS.findall(line)) - {"BaseSettings"} + if not modules or not classes: + continue + defined = set().union(*(_defined_in(module) for module in modules if module.exists())) + wrong += [f"{page.relative_to(REPO_ROOT)}:{number}: {name}" for name in sorted(classes - defined)] + + assert not wrong, "\n".join(wrong) + + +def _settings_class(name: str) -> type[BaseSettings]: + for path in SRC_ROOT.rglob("*.py"): + if name in _defined_in(path): + module = ".".join(path.relative_to(SRC_ROOT.parent).with_suffix("").parts) + found = getattr(importlib.import_module(module), name) + assert isinstance(found, type) and issubclass(found, BaseSettings), name + + return found + + raise LookupError(name) + + +def test_every_setting_a_row_of_the_settings_table_names_is_on_that_class(): + page = REPO_ROOT / "docs" / "user-guide" / "configuration" / "settings-classes.md" + rows = [found.groups() for found in map(TABLE_ROW.match, page.read_text().splitlines()) if found] + + assert rows + wrong = [] + for name, covers in rows: + settings_class = _settings_class(name) + wrong += [ + f"{name}: {field}" + for field in BACKTICKED_FIELD.findall(covers) + if "*" not in field + and field not in settings_class.model_fields + and not isinstance(inspect.getattr_static(settings_class, field, None), property) + ] + + assert not wrong, "\n".join(wrong) + + +def _bases(source: str) -> list[str]: + (settings,) = [node for node in ast.walk(ast.parse(source)) if isinstance(node, ast.ClassDef) and node.name == "Settings"] + + return [base.id for base in settings.bases if isinstance(base, ast.Name)] + + +def test_the_settings_page_composes_settings_as_the_wiring_does(): + page = (REPO_ROOT / "docs" / "user-guide" / "configuration" / "settings-classes.md").read_text() + sample = page.split("```python\n# src/wiring/settings.py", 1)[1].split("\n", 1)[1].split("```", 1)[0] + + assert _bases(sample) == _bases((SRC_ROOT / "wiring" / "settings.py").read_text()) + + +def test_the_default_tier_name_is_said_to_be_on_the_class_that_has_it(): + assert "DEFAULT_TIER_NAME" in _settings_class("TierSettings").model_fields + for page in ("docs/user-guide/configuration/settings-classes.md", "docs/user-guide/admin-panel/configuration.md"): + lines = [line for line in (REPO_ROOT / page).read_text().splitlines() if "`DEFAULT_TIER_NAME`" in line] + assert lines, page + assert all("`TierSettings`" in line for line in lines), (page, lines) diff --git a/backend/tests/unit/test_docs_wiring.py b/backend/tests/unit/test_docs_wiring.py index ee5ef6c3..9e38a3ba 100644 --- a/backend/tests/unit/test_docs_wiring.py +++ b/backend/tests/unit/test_docs_wiring.py @@ -7,26 +7,29 @@ """ import re +import tomllib from pathlib import Path -from tests.unit.test_docs_imports import LEFT_OUT_PATHS +from src.modules.tier.settings import TierSettings REPO_ROOT = Path(__file__).resolve().parents[3] WIRING = REPO_ROOT / "backend" / "src" / "wiring" STRUCTURE = REPO_ROOT / "docs" / "user-guide" / "project-structure.md" COMPOSABLE = REPO_ROOT / "docs" / "user-guide" / "composable-features.md" DIAGRAMS = REPO_ROOT / "docs" / "assets" / "build-diagrams.cjs" +CHANGELOG = REPO_ROOT / "docs" / "changelog.md" +ENVIRONMENT = REPO_ROOT / "docs" / "user-guide" / "configuration" / "environment-variables.md" DRAWN_TREE = re.compile(r"```text\n(.*?)```", re.DOTALL) +def _catalog() -> dict: + with (REPO_ROOT / "blueprint.toml").open("rb") as handle: + return tomllib.load(handle) + + def _wiring_modules() -> list[str]: - """The composition root's modules, as a project that carries them has them.""" - return sorted( - path.name - for path in WIRING.glob("*.py") - if path.name != "__init__.py" and f"backend/src/wiring/{path.name}" not in LEFT_OUT_PATHS - ) + return sorted(path.name for path in WIRING.glob("*.py") if path.name != "__init__.py") def _tree_drawing_the_wiring() -> str: @@ -65,11 +68,107 @@ def test_the_diagram_draws_every_module_of_the_composition_root(): assert [name for name in _wiring_modules() if name not in drawn] == [] -def test_the_diagram_names_every_preset_the_drill_runs(): - """A preset added to the matrix and not to the picture is a diagram that has aged.""" - drill = (REPO_ROOT / "tools" / "removal_drill.py").read_text() - presets = re.findall(r'^ "([a-z0-9-]+)": \(', drill, re.M) - drawn = DIAGRAMS.read_text() +def test_the_diagram_names_every_set_verify_sets_declares(): + """A set added to `[verify.sets]` and not to the picture is a diagram that has aged.""" + sets = _catalog()["verify"]["sets"] + drawn = set(re.findall(r">([a-z0-9-]+)", DIAGRAMS.read_text())) + + assert sets + assert [name for name in sets if name not in drawn] == [] + + +def _section(page: Path, heading: str) -> str: + text = page.read_text() + assert heading in text, heading + + return text.split(heading, 1)[1].split("\n## ", 1)[0] + + +def test_the_ci_table_is_every_declared_set_and_names_the_presets_beside_it(): + """CI runs `fastro blueprint verify` once for each set: the declared ones, each preset and `everything`.""" + section = _section(COMPOSABLE, "## Checking that removal still works") + rows = re.findall(r"^\| `([a-z0-9-]+)` \|", section, re.M) + catalog = _catalog() + + assert rows == [*catalog["verify"]["sets"], "everything"] + assert [preset for preset in catalog["presets"] if f"`{preset}`" not in section] == [] + + +def test_the_steps_for_a_removable_feature_declare_it_in_the_catalog_and_verify_it(): + section = _section(COMPOSABLE, "## Writing a feature that can be removed") + + assert "`blueprint.toml`" in section and "`[features.]`" in section + assert "`[[features..when]]`" in section and 'if = ""' in section + assert "`fastro blueprint verify`" in section + assert any(feature.get("when") for feature in _catalog()["features"].values()) + + +def test_the_new_module_steps_declare_its_paths_in_the_catalog(): + steps = STRUCTURE.read_text().split("**Generate a migration**", 1)[0] + + assert "`blueprint.toml`" in steps.rsplit("\n9. ", 1)[1] + assert "`fastro blueprint verify`" in steps.rsplit("\n9. ", 1)[1] + + +def test_the_changelog_names_the_wiring_the_cache_reads_the_scope_fingerprint_from(): + unreleased = CHANGELOG.read_text().split("## Unreleased", 1)[1].split("\n## ", 1)[0] + entry = unreleased.split("**A project with the cache feature and without accounts imports.**", 1)[1].split("\n- **", 1)[0] + wiring = next(module for module in _catalog()["wiring"] if module["path"] == "backend/src/wiring/scope.py") + (slot,) = wiring["slots"] + + assert f"`{slot['name']}`" in entry and f"{slot['name']}:" in (WIRING / "scope.py").read_text() + assert "`src/wiring/scope.py`" in entry + assert slot["fallback"] == "None" and "`None` without accounts" in entry + + +def test_the_changelog_names_the_test_a_project_without_the_cache_no_longer_ships(): + unreleased = CHANGELOG.read_text().split("## Unreleased", 1)[1].split("\n## ", 1)[0] + entry = unreleased.split("**A project with the cache feature and without accounts imports.**", 1)[1].split("\n- **", 1)[0] + path = "tests/integration/tier_limits/test_cached_listing.py" + (block,) = [block for block in _catalog()["features"]["tier_limits"]["when"] if f"backend/{path}" in block["paths"]] + + assert f"`{path}`" in " ".join(entry.split()) + assert block["if"] == "cache" + + +def test_the_composable_features_page_says_the_scope_fingerprint_is_none_without_accounts(): + (row,) = [line for line in COMPOSABLE.read_text().splitlines() if line.startswith("| `scope.py` |")] + wiring = next(module for module in _catalog()["wiring"] if module["path"] == "backend/src/wiring/scope.py") + (slot,) = wiring["slots"] + + assert slot["fallback"] == "None" and "`None` without it" in row + + +def _unreleased_entry(heading: str) -> str: + unreleased = CHANGELOG.read_text().split("## Unreleased", 1)[1].split("\n## ", 1)[0] + + return " ".join(unreleased.split(f"**{heading}**", 1)[1].split("\n- **", 1)[0].split()) + + +def test_the_changelog_names_the_wiring_a_new_account_takes_its_default_tier_from(): + entry = _unreleased_entry("A new account is given the default tier.") + wiring = next(module for module in _catalog()["wiring"] if module["path"] == "backend/src/wiring/signup.py") + (slot,) = wiring["slots"] + + assert f"`{slot['name']}`" in entry and "`src/wiring/signup.py`" in entry + assert _catalog()["features"]["tiers"]["contributes"][slot["point"]] == ["src.modules.tier.hooks:default_tier"] + assert "`DEFAULT_TIER_NAME`" in entry + + +def test_the_environment_page_says_both_signup_paths_take_the_default_tier(): + page = ENVIRONMENT.read_text() + block, after = page.split("```env\nDEFAULT_TIER_NAME=", 1)[1].split("\n```", 1) + paragraph = " ".join(after.strip().split("\n\n", 1)[0].split()) + + assert block == TierSettings.model_fields["DEFAULT_TIER_NAME"].default + assert "signup route" in paragraph and "provider" in paragraph and "deleted" in paragraph + + +def test_the_composable_features_page_says_tiers_sets_the_tier_default_tier_name_names(): + (row,) = [line for line in COMPOSABLE.read_text().splitlines() if line.startswith("| `signup.py` |")] + wiring = next(module for module in _catalog()["wiring"] if module["path"] == "backend/src/wiring/signup.py") + (slot,) = wiring["slots"] - assert presets, "no presets found in the drill" - assert [preset for preset in presets if "-" in preset and preset not in drawn] == [] + assert f"`{slot['name']}`" in row + assert _catalog()["features"]["tiers"]["contributes"][slot["point"]] == ["src.modules.tier.hooks:default_tier"] + assert "DEFAULT_TIER_NAME" in TierSettings.model_fields and "`DEFAULT_TIER_NAME`" in row diff --git a/backend/tests/unit/test_image_contents.py b/backend/tests/unit/test_image_contents.py index 425fa24f..adfe5819 100644 --- a/backend/tests/unit/test_image_contents.py +++ b/backend/tests/unit/test_image_contents.py @@ -12,8 +12,6 @@ import re from pathlib import Path -from tests.unit.test_docs_imports import LEFT_OUT_PATHS - REPO_ROOT = Path(__file__).resolve().parents[3] DOCKERFILE = REPO_ROOT / "backend" / "Dockerfile" DOCS_ROOT = REPO_ROOT / "docs" @@ -47,23 +45,9 @@ def test_alembic_finds_its_configuration_from_the_working_directory_the_stages_u assert "ENV ALEMBIC_CONFIG=/app/alembic.ini" in stage -def _carried_by_this_project(module: str) -> bool: - """Whether this project still has the script, rather than having removed its feature. - - The documentation describes every feature, so a build without one still shows commands - for scripts it no longer carries. - """ - return f"backend/scripts/{module.split('.')[1]}.py" not in LEFT_OUT_PATHS - - def test_every_script_the_docs_run_in_a_container_exists(): """The module name in the documented command has to name a file the image copies.""" - documented = { - module - for page in DOCS_ROOT.rglob("*.md") - for module in RUN_IN_A_CONTAINER.findall(page.read_text()) - if _carried_by_this_project(module) - } + documented = {module for page in DOCS_ROOT.rglob("*.md") for module in RUN_IN_A_CONTAINER.findall(page.read_text())} assert documented, "no documented in-container script run found" assert [module for module in sorted(documented) if not (SCRIPTS / f"{module.split('.')[1]}.py").exists()] == [] diff --git a/backend/tests/unit/test_removal_drill.py b/backend/tests/unit/test_removal_drill.py deleted file mode 100644 index 97ecc211..00000000 --- a/backend/tests/unit/test_removal_drill.py +++ /dev/null @@ -1,258 +0,0 @@ -"""The drill's own manifest: a selection has to pull in everything it needs. - -The drill lives outside the backend package, so it is loaded from its path rather -than imported. -""" - -import ast -import importlib.util -import shutil -import sys -from pathlib import Path - -import pytest - -BACKEND_ROOT = Path(__file__).resolve().parents[2] -DRILL_PATH = BACKEND_ROOT.parent / "tools" / "removal_drill.py" - -_spec = importlib.util.spec_from_file_location("removal_drill", DRILL_PATH) -assert _spec is not None and _spec.loader is not None -drill = importlib.util.module_from_spec(_spec) -sys.modules[_spec.name] = drill -_spec.loader.exec_module(drill) - - -def test_a_selection_pulls_in_what_its_features_need_all_the_way_down(): - """tier_limits needs tiers and ratelimit, and both of those need accounts.""" - assert drill._selected_from(("tier_limits",)) == {"tier_limits", "tiers", "ratelimit", "accounts"} - - -@pytest.mark.parametrize("preset", sorted(drill.PRESETS)) -def test_every_preset_is_closed_under_its_requirements(preset: str): - chosen = drill._selected(preset) - - for feature in chosen: - assert set(drill.REQUIRES.get(feature, ())) <= chosen, feature - - -def test_every_feature_the_wiring_knows_is_in_the_manifest(): - """A feature missing here would never be removed by any preset.""" - assert set(drill.FEATURES) >= set(drill.REQUIRES) - assert set(drill.PRESETS["everything"]) == set(drill.FEATURES) - - -class TestReportingACheck: - """A failing preset has to say what failed: the drill is the only place that output exists.""" - - def test_a_failing_check_prints_what_it_printed(self): - failed = drill.Result( - "tests", - False, - "1 failed, 664 passed", - "FAILED tests/integration/test_x.py::test_y - assert 2 == 1\n1 failed, 664 passed", - ) - - report = drill._report(failed) - - assert "FAIL" in report - assert "tests/integration/test_x.py::test_y" in report - - def test_a_long_failure_prints_its_end_and_says_what_it_dropped(self): - """A ``-q`` run is mostly progress dots; the failure sits at the end of it.""" - printed = "\n".join(f"line {number}" for number in range(100)) - - report = drill._report(drill.Result("tests", False, "line 99", printed)) - - assert "line 99" in report - assert "line 0" not in report - assert "60 earlier lines" in report - - def test_a_build_that_raises_leaves_its_scratch_copy_behind(self, monkeypatch, capsys): - """Whatever the build tripped over is only visible in the copy it got to.""" - - def failing_build(preset: str, scratch: Path) -> Path: - raise RuntimeError("copy failed") - - monkeypatch.setattr(drill, "build", failing_build) - monkeypatch.setattr(sys, "argv", ["removal_drill.py", "core-only"]) - - with pytest.raises(RuntimeError, match="copy failed"): - drill.main() - - printed = capsys.readouterr().out - - assert "scratch copies left in" in printed - - left = Path(printed.split("scratch copies left in ")[1].strip()) - - assert left.exists() - shutil.rmtree(left, ignore_errors=True) - - def test_a_passing_check_prints_its_last_line_only(self): - passed = drill.Result("tests", True, "665 passed", "a long run of dots\n665 passed") - - report = drill._report(passed) - - assert report.strip() == "PASS tests 665 passed" - - -def test_a_scratch_project_never_carries_the_repository_env_file(tmp_path): - """It would point a build at whatever the developer runs locally.""" - source = tmp_path / "source" - (source / "backend").mkdir(parents=True) - (source / ".git").mkdir() - (source / "backend" / ".env").write_text("POSTGRES_PASSWORD=the-developers-own\n") - (source / ".env").write_text("SECRET_KEY=the-developers-own\n") - (source / "backend" / ".env.example").write_text("POSTGRES_PASSWORD=postgres\n") - (source / ".git" / "HEAD").write_text("ref: refs/heads/main\n") - - drill.copy_repository(source, tmp_path / "project") - - copied = sorted(path.relative_to(tmp_path / "project").as_posix() for path in (tmp_path / "project").rglob("*")) - - assert copied == ["backend", "backend/.env.example"] - - -def test_a_scratch_project_is_built_from_the_repository(tmp_path): - """The copy above is the one ``build`` makes, so build it once for real.""" - project = drill.build("core-only", tmp_path) - - assert (project / "backend" / ".env.example").exists() - assert [path for path in project.rglob("*") if path.name == ".env"] == [] - - -def _features_on_disk() -> set[str]: - """The features this project still carries, read from the source paths they own.""" - repository = BACKEND_ROOT.parent - present = set() - for name, feature in drill.FEATURES.items(): - sources = [path for path in feature.paths if path.startswith("backend/src")] - if sources and all((repository / path).exists() for path in sources): - present.add(name) - - return present - - -def _needs(*features: str) -> None: - """Skip where this project no longer carries the sources a preset is built from.""" - missing = sorted(set(features) - _features_on_disk()) - if missing: - pytest.skip(f"this project carries no {', '.join(missing)} to build from") - - -class TestTheTaskModulesAProjectRegisters: - """A task module imports the feature it belongs to and the broker it registers on.""" - - @pytest.mark.parametrize("chosen", [{"accounts", "api_keys"}, {"accounts", "taskiq"}, {"taskiq"}, set()]) - def test_the_usage_prune_is_registered_by_neither_feature_alone(self, chosen: set[str]): - assert "src.modules.api_keys.tasks" not in drill._wiring_tasks(chosen) - - def test_the_usage_prune_is_registered_where_both_features_are_present(self): - assert "src.modules.api_keys.tasks" in drill._wiring_tasks({"accounts", "api_keys", "taskiq"}) - - def test_a_project_with_the_keys_and_no_worker_has_no_task_module(self, tmp_path): - _needs("accounts", "api_keys") - project = drill.build("accounts-api-keys", tmp_path) - - assert (project / "backend/src/modules/api_keys/service.py").exists() - assert not (project / "backend/src/modules/api_keys/tasks.py").exists() - - def test_a_project_with_a_worker_and_no_keys_has_no_task_module(self, tmp_path): - _needs("accounts", "taskiq") - project = drill.build("accounts-cache-taskiq", tmp_path) - - assert (project / "backend/src/infrastructure/taskiq/worker.py").exists() - assert not (project / "backend/src/modules/api_keys").exists() - - -class TestTheSenderAProjectIsWiredTo: - """The request never waits for a mail server, queue or no queue.""" - - def test_a_project_with_a_worker_queues_the_message(self): - wired = drill._wiring_email({"accounts", "taskiq"}) - - assert "EMAIL_SENDER: EmailSender = queued_sender" in wired - - def test_a_project_without_one_hands_the_delivery_over(self): - """crudauth awaits the sender, so a sender that returns is what keeps the answer quick.""" - wired = drill._wiring_email({"accounts"}) - - assert "from ..infrastructure.email.senders import HandingOverSender" in wired - assert "EMAIL_SENDER: EmailSender = HandingOverSender(build_sender())" in wired - - def test_a_project_without_one_drains_at_shutdown(self): - """What was handed over is mail somebody asked for, so a deploy waits for it.""" - wired = drill._wiring_app({"accounts"}) - - assert "from ..infrastructure.handover import lifecycle as handover_lifecycle" in wired - assert "handover_lifecycle" in wired.split("LIFECYCLES")[1] - - def test_a_project_with_a_worker_drains_before_it_closes_the_broker(self): - """The worker's own lifecycle drains, where a message may still be on its way out.""" - wired = drill._wiring_app({"accounts", "taskiq"}) - - assert "handover_lifecycle" not in wired - assert "taskiq_lifecycle" in wired.split("LIFECYCLES")[1] - - -GENERATED_FILES = ( - ("src/wiring/settings.py", "_wiring_settings"), - ("src/wiring/app.py", "_wiring_app"), - ("src/wiring/hooks.py", "_wiring_hooks"), - ("src/wiring/email.py", "_wiring_email"), - ("src/wiring/tasks.py", "_wiring_tasks"), - ("src/wiring/tables.py", "_wiring_tables"), - ("src/wiring/transports.py", "_wiring_transports"), - ("src/wiring/cache.py", "_wiring_cache"), - ("src/wiring/models.py", "_wiring_models"), - ("src/wiring/admin.py", "_wiring_admin"), - ("scripts/seeders.py", "_seeders"), - ("tests/wiring.py", "_tests_wiring"), -) - - -def _without_formatting(source: str) -> tuple[tuple[str, ...], tuple[str, ...]]: - """A module's imports and statements, as trees: no docstring, no comments, no layout.""" - body = ast.parse(source).body - if body and isinstance(body[0], ast.Expr) and isinstance(body[0].value, ast.Constant): - body = body[1:] - - imports = sorted(ast.dump(node) for node in body if isinstance(node, ast.Import | ast.ImportFrom)) - statements = [ast.dump(node) for node in body if not isinstance(node, ast.Import | ast.ImportFrom)] - - return tuple(imports), tuple(statements) - - -def test_the_generator_rebuilds_what_this_project_committed(): - """The drill proves a regenerated project reproduces this one, which needs them equal.""" - present = _features_on_disk() - - assert (BACKEND_ROOT / "src/wiring/admin.py").exists() == ("admin" in present) - - for name, generator in GENERATED_FILES: - committed = BACKEND_ROOT / name - if name == "src/wiring/admin.py" and "admin" not in present: - continue - - assert _without_formatting(getattr(drill, generator)(present)) == _without_formatting(committed.read_text()), name - - -TRACING_RECIPE = BACKEND_ROOT.parent / "docs/user-guide/observability.md" -"""The one guide that asks a reader to install something of their own on the app.""" - - -def test_a_rebuild_leaves_the_composition_root_as_it_is(tmp_path): - """That recipe wires its installer there, where no regeneration reaches it.""" - project = drill.build("core-only", tmp_path) - - rebuilt = project / "backend/src/interfaces/main.py" - - assert rebuilt.read_text() == (BACKEND_ROOT / "src/interfaces/main.py").read_text() - - -def test_the_tracing_recipe_wires_itself_outside_the_generated_wiring(): - """Written into ``INSTALLERS`` instead, it would fail the comparison above.""" - recipe = TRACING_RECIPE.read_text() - - assert "installers=(*INSTALLERS, tracing_install)" in recipe - assert "INSTALLERS: tuple" not in recipe diff --git a/backend/tests/unit/test_tarball_contents.py b/backend/tests/unit/test_tarball_contents.py new file mode 100644 index 00000000..406d0c14 --- /dev/null +++ b/backend/tests/unit/test_tarball_contents.py @@ -0,0 +1,66 @@ +"""What a source tarball carries, which is whatever `git archive` writes. + +GitHub builds a release's tarball the same way, so a path marked `export-ignore` is one a +download doesn't have. What's left out is the blueprint's own: the documentation site and the +issue templates are things to read in this repository, not things a reader builds the project +from. +""" + +import io +import subprocess +import tarfile +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parents[3] + +LEFT_OUT = (".github/ISSUE_TEMPLATE/", "docs/", "zensical.toml") +"""The paths `.gitattributes` keeps out of the tarball.""" + +CARRIED = ("README.md", "backend/Dockerfile", "backend/pyproject.toml", "backend/src/interfaces/main.py") +"""A few a reader could not build the project without, so the archive is read, not assumed. + +The compose file is not among them: `.gitignore` keeps it out, because the deploy generator +writes it.""" + + +def _archived() -> set[str]: + """Every path `git archive` writes for the current commit. + + The attributes are read from the working tree rather than from `HEAD`, so a `.gitattributes` + that isn't committed yet still counts and the answer doesn't wait for the commit. + """ + written = subprocess.run( + ["git", "archive", "--worktree-attributes", "--format=tar", "HEAD"], + cwd=REPO_ROOT, + capture_output=True, + check=True, + ) + with tarfile.open(fileobj=io.BytesIO(written.stdout)) as archive: + return {member.name for member in archive.getmembers()} + + +def test_the_tarball_leaves_out_what_only_this_repository_needs(): + archived = _archived() + + assert {name for name in archived for path in LEFT_OUT if name.startswith(path.rstrip("/"))} == set() + + +def test_the_tarball_carries_what_the_project_is_built_from(): + """The other direction, and the proof that the archive was read at all.""" + archived = _archived() + + assert archived + assert set(CARRIED) <= archived + + +def test_every_path_kept_out_is_one_this_repository_has(): + """A path that moved would be ignored silently, leaving the real one in the tarball.""" + for path in LEFT_OUT: + assert (REPO_ROOT / path).exists(), path + + +def test_the_paths_kept_out_are_the_ones_gitattributes_ignores(): + """Both ways: an entry left behind in `.gitattributes` is one no test reads.""" + rules = [line.split() for line in (REPO_ROOT / ".gitattributes").read_text().splitlines()] + + assert sorted(rule[0] for rule in rules if rule[1:] == ["export-ignore"]) == sorted(LEFT_OUT) diff --git a/backend/tests/wiring.py b/backend/tests/wiring.py index 35b14696..c33cbdd0 100644 --- a/backend/tests/wiring.py +++ b/backend/tests/wiring.py @@ -1,6 +1,7 @@ """Fixture modules of the selected features, loaded by ``tests/conftest.py``. -Written by the generator in `tools/removal_drill.py`, which a test compares this file against. +Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change +fastro.toml (or [app] in it, for your own code) and run `fastro sync`. """ PYTEST_PLUGINS: list[str] = [ diff --git a/blueprint.toml b/blueprint.toml new file mode 100644 index 00000000..7360703c --- /dev/null +++ b/blueprint.toml @@ -0,0 +1,798 @@ +[blueprint] +name = "fastapi-boilerplate" +version = "0.20.0" +schema = 1 +requires_fastro = ">=0.1.0.dev0,<0.2" +python_root = "backend" +overlay = "blueprint/overlay" +import_root = "src" +blueprint_only = [ + ".gitattributes", + ".gitignore", + ".github/", + ".pre-commit-config.yaml", + "CODE_OF_CONDUCT.md", + "CONTRIBUTING.md", + "README.md", + "backend/tests/unit/infrastructure/config/defaults.json", + "backend/tests/unit/infrastructure/config/example_values.json", + "backend/tests/unit/infrastructure/config/test_settings_tables.py", + "backend/tests/unit/test_blueprint_catalog.py", + "backend/tests/unit/test_docs_imports.py", + "backend/tests/unit/test_docs_recipes.py", + "backend/tests/unit/test_docs_scripts.py", + "backend/tests/unit/test_docs_settings.py", + "backend/tests/unit/test_docs_wiring.py", + "backend/tests/unit/test_image_contents.py", + "backend/tests/unit/test_tarball_contents.py", + "blueprint/", + "blueprint.toml", + "docs/", + "fastro.toml", + "pyproject.toml", + "uv.lock", + "zensical.toml", +] + +[blueprint.dependencies] +runtime = [ + "alembic>=1.16.4", + "anyio>=4.15.1", + "asyncpg>=0.30.0", + "crudauth[all]>=0.8.2,<0.9.0", + "fastapi[standard]>=0.115.8,<0.140.7", + "fastcrud>=0.21.0", + "greenlet>=3.1.1", + "pydantic>=2.10.6", + "pydantic-settings>=2.14.2", + "redis>=6.1.0", + "sqlalchemy>=2.0.37", + "starlette>=1.3.1", +] +dev = [ + "mypy>=1.14.1", + "ruff>=0.9.4", + "pytest>=8.3.5", + "pytest-asyncio>=0.25.3", + "pytest-mock>=3.14.0", + "testcontainers[postgres]>=4.10.0", + "pytest-xdist[psutil]>=3.8.0", + "pre-commit>=4.0.0", + "faker>=37.1.0", + "httpx>=0.28.1", + "jinja2>=3.1.6", +] + +[presets] +minimal = ["accounts"] +standard = ["accounts", "rbac", "ratelimit", "tiers", "tier_limits", "admin", "cache"] +full = ["accounts", "rbac", "ratelimit", "tiers", "tier_limits", "api_keys", "admin", "cache", "taskiq"] + +[verify] +app = "src.interfaces.main" + +[verify.sets] +core-only = [] +core-taskiq = ["taskiq"] +accounts-only = ["accounts"] +accounts-rbac = ["accounts", "rbac"] +accounts-admin = ["accounts", "admin"] +accounts-api-keys = ["accounts", "api_keys"] +accounts-rbac-tiers = ["accounts", "rbac", "tiers", "ratelimit"] +accounts-cache-taskiq = ["accounts", "cache", "taskiq"] + +[core.contributes] +critical_readiness = [ + "src.infrastructure.database.health:readiness as database_readiness", + "src.infrastructure.database.health:schema_readiness", +] + +[points.routers] +cardinality = "many" +doc = "A router the API mounts under its version prefix." + +[points.root_routers] +cardinality = "one" +doc = "The routers mounted beside the API rather than under its prefix." + +[points.api_throttle] +cardinality = "many" +doc = "A dependency every throttled route runs before answering." + +[points.lifecycles] +cardinality = "many" +doc = "Startup and shutdown work, started in order and torn down in reverse." + +[points.installers] +cardinality = "many" +doc = "Something that installs itself on the app as the app is built." + +[points.docs_guard] +cardinality = "one" +doc = "The dependency that guards the documentation routes where they are served." + +[points.settings] +cardinality = "many" +doc = "A settings mixin the project's Settings inherits, with the core one last." + +[points.permission_sources] +cardinality = "many" +doc = "Answers which permissions an account holds." + +[points.rate_limit_resolvers] +cardinality = "many" +doc = "Answers the limit for a request, or declines to." + +[points.tier_delete_guards] +cardinality = "many" +doc = "Answers why a tier cannot be deleted yet." + +[points.tier_delete_releases] +cardinality = "many" +doc = "Releases the rows a feature keeps for a tier that is being deleted." + +[points.critical_readiness] +cardinality = "many" +doc = "A dependency a request needs, so readiness answers 503 while it is unreachable." + +[points.informational_readiness] +cardinality = "many" +doc = "A dependency readiness reports on without refusing traffic over it." + +[points.user_model] +cardinality = "many" +doc = "Columns a feature adds to the user model." + +[points.user_schema] +cardinality = "many" +doc = "Fields a feature adds to the user schemas." + +[points.admin_views] +cardinality = "many" +doc = "A model view the admin panel registers." + +[points.email_sender] +cardinality = "one" +doc = "The sender the account emails go out through." + +[points.cache_decorator] +cardinality = "one" +doc = "The decorator a route caches its response with." + +[points.task_modules] +cardinality = "many" +doc = "A module whose background tasks the worker registers." + +[points.table_modules] +cardinality = "many" +doc = "A module outside src/modules that declares tables on the metadata." + +[points.extra_transports] +cardinality = "many" +doc = "An authentication transport registered beside the session one." + +[points.scope_fingerprint] +cardinality = "one" +doc = "What tells a credential that carries a scope apart from its account's others." + +[points.new_account_fields] +cardinality = "many" +doc = "Columns a feature sets on an account as it is created, on every signup path." + +[points.seeders] +cardinality = "many" +doc = "A step the initial-data script runs, in order." + +[points.test_plugins] +cardinality = "many" +doc = "A fixture module pytest loads for the features the project carries." + +[features.accounts] +summary = "Users, sessions, CSRF, login lockout, OAuth" +group = "Accounts" +dependencies = ["user-agents>=2.2.0"] +paths = [ + "backend/scripts/canonicalize_emails.py", + "backend/scripts/create_first_superuser.py", + "backend/scripts/unlock_account.py", + "backend/src/infrastructure/auth/", + "backend/src/modules/user/", + "backend/tests/fixtures/accounts.py", + "backend/tests/integration/accounts/", + "backend/tests/integration/api/v1/users/", + "backend/tests/integration/auth/", + "backend/tests/unit/infrastructure/auth/", + "backend/tests/unit/modules/user/", + "backend/tests/unit/scripts/test_canonicalize_emails.py", + "backend/tests/unit/scripts/test_create_first_superuser.py", + "backend/tests/unit/scripts/test_setup_initial_data.py", + "backend/tests/unit/scripts/test_unlock_account.py", +] + +[features.accounts.contributes] +routers = [ + { ref = "src.modules.user.routes:router as users_router", prefix = "/users", throttled = true, order = 10 }, + { ref = "src.infrastructure.auth.routes:router as auth_router", prefix = "/auth", throttled = false, order = 22 }, +] +root_routers = ["src.infrastructure.auth.routes:root_routers as accounts_root_routers"] +lifecycles = [ + "src.infrastructure.auth.setup:lifecycle as accounts_lifecycle", + { ref = "src.infrastructure.handover:lifecycle as handover_lifecycle", if = "not taskiq", order = 950 }, +] +installers = ["src.infrastructure.auth.install:install as accounts_install"] +docs_guard = ["src.infrastructure.auth.dependencies:get_current_superuser"] +settings = ["src.infrastructure.auth.settings:AccountsSettings"] +critical_readiness = [ + "src.infrastructure.auth.health:limiter_readiness", + "src.infrastructure.auth.health:sessions_readiness", +] +table_modules = [{ value = "src.infrastructure.auth.store" }] +seeders = [{ ref = "scripts.create_first_superuser:create_first_superuser", order = 11 }] +test_plugins = [{ value = "tests.fixtures.accounts" }] +scope_fingerprint = ["src.infrastructure.auth.scope:scope_fingerprint"] + +[features.accounts.commands."users unlock"] +module = "scripts.unlock_account" +help = "Clear the login lockout an account is held in." + +[features.accounts.commands."users canonicalize-emails"] +module = "scripts.canonicalize_emails" +help = "Rewrite the user addresses stored with case or whitespace in them." + +[features.accounts.commands."users create-superuser"] +module = "scripts.create_first_superuser" +help = "Create the first superuser from the admin environment variables." + +[[features.accounts.when]] +if = "admin" +paths = [ + "backend/src/modules/user/admin.py", + "backend/tests/unit/modules/user/test_admin.py", +] +contributes.admin_views = [{ ref = "src.modules.user.admin:UserAdmin", order = 10 }] + +[features.rbac] +summary = "Roles and permissions" +group = "Accounts" +requires = ["accounts"] +paths = [ + "backend/src/modules/role/", + "backend/tests/integration/rbac/", + "backend/tests/unit/modules/role/", +] + +[features.rbac.contributes] +routers = [ + { ref = "src.modules.role.routes:user_roles_router", prefix = "/users", throttled = true, order = 13 }, + { ref = "src.modules.role.routes:permissions_router", prefix = "/permissions", throttled = true, order = 24 }, + { ref = "src.modules.role.routes:router as roles_router", prefix = "/roles", throttled = true, order = 25 }, +] +permission_sources = ["src.modules.role.sources:role_permissions"] +user_model = ["src.modules.role.contrib:UserRoleColumns"] + +[[features.rbac.when]] +if = "admin" +paths = [ + "backend/src/modules/role/admin.py", + "backend/tests/unit/modules/role/test_admin.py", +] +contributes.admin_views = [ + { ref = "src.modules.role.admin:RoleAdmin", order = 12 }, + { ref = "src.modules.role.admin:RolePermissionAdmin", order = 13 }, + { ref = "src.modules.role.admin:UserRoleAdmin", order = 14 }, +] + +[features.ratelimit] +summary = "Per-caller API throttle" +group = "Accounts" +requires = ["accounts"] +paths = [ + "backend/src/infrastructure/ratelimit/", + "backend/tests/integration/ratelimit/", + "backend/tests/unit/infrastructure/ratelimit/", +] + +[features.ratelimit.contributes] +api_throttle = ["src.infrastructure.ratelimit.dependency:api_rate_limit_dependency"] +settings = ["src.infrastructure.ratelimit.settings:RateLimitSettings"] + +[features.tiers] +summary = "User tiers other features key off" +group = "Accounts" +requires = ["accounts"] +paths = [ + "backend/scripts/create_first_tier.py", + "backend/src/modules/tier/", + "backend/tests/fixtures/tiers.py", + "backend/tests/integration/tiers/", + "backend/tests/unit/modules/tier/", +] + +[features.tiers.contributes] +routers = [ + { ref = "src.modules.tier.routes:user_tier_router", prefix = "/users", throttled = true, order = 11 }, + { ref = "src.modules.tier.routes:router as tiers_router", prefix = "/tiers", throttled = true, order = 20 }, +] +settings = ["src.modules.tier.settings:TierSettings"] +user_model = ["src.modules.tier.contrib:UserTierColumns"] +user_schema = ["src.modules.tier.contrib:UserTierFields"] +seeders = [{ ref = "scripts.create_first_tier:create_first_tier", order = 10 }] +test_plugins = [{ value = "tests.fixtures.tiers" }] +new_account_fields = ["src.modules.tier.hooks:default_tier"] + +[features.tiers.commands."tiers create-default"] +module = "scripts.create_first_tier" +help = "Create the default tier DEFAULT_TIER_NAME names, if it isn't there yet." + +[[features.tiers.when]] +if = "admin" +paths = [ + "backend/src/modules/tier/admin.py", + "backend/tests/unit/modules/tier/test_admin.py", +] +contributes.admin_views = [{ ref = "src.modules.tier.admin:TierAdmin", order = 11 }] + +[features.tier_limits] +summary = "Per-tier rate limits" +group = "Accounts" +requires = ["tiers", "ratelimit"] +paths = [ + "backend/src/modules/rate_limit/", + "backend/tests/integration/tier_limits/", + "backend/tests/unit/modules/rate_limit/", +] + +[features.tier_limits.contributes] +routers = [ + { ref = "src.modules.rate_limit.routes:user_rate_limits_router", prefix = "/users", throttled = true, order = 12 }, + { ref = "src.modules.rate_limit.routes:router as rate_limits_router", prefix = "/rate-limits", throttled = true, order = 21 }, +] +rate_limit_resolvers = ["src.modules.rate_limit.hooks:tier_rate_limit"] +tier_delete_guards = ["src.modules.rate_limit.hooks:rate_limits_reference_tier"] +tier_delete_releases = ["src.modules.rate_limit.hooks:release_deleted_rate_limits"] + +[[features.tier_limits.when]] +if = "cache" +paths = [ + "backend/tests/integration/tier_limits/test_cached_listing.py", +] + +[features.api_keys] +summary = "API keys: create, revoke, meter" +group = "Accounts" +requires = ["accounts"] +paths = [ + "backend/scripts/cleanup_api_key_json.py", + "backend/scripts/prune_key_usage.py", + "backend/scripts/revoke_scrypt_api_keys.py", + "backend/src/modules/api_keys/", + "backend/tests/integration/api/v1/api_keys/", + "backend/tests/unit/modules/api_keys/", +] + +[features.api_keys.contributes] +routers = [ + { ref = "src.modules.api_keys.routes:router as api_keys_router", prefix = "/api-keys", throttled = true, order = 23 }, +] +installers = ["src.modules.api_keys.install:install as api_keys_install"] +settings = ["src.modules.api_keys.settings:APIKeySettings"] +extra_transports = [{ ref = "src.modules.api_keys.transport:APIKeyTransport", call = true }] + +[features.api_keys.commands."keys cleanup-json"] +module = "scripts.cleanup_api_key_json" +help = "Repair the API key rows whose JSON columns hold something nothing can read." + +[features.api_keys.commands."keys prune-usage"] +module = "scripts.prune_key_usage" +help = "Delete the API key usage rows past the retention." + +[features.api_keys.commands."keys revoke-scrypt"] +module = "scripts.revoke_scrypt_api_keys" +help = "Name the API keys still stored under a scrypt hash, and revoke them when asked." + +[[features.api_keys.when]] +if = "ratelimit" +paths = [ + "backend/tests/integration/api_keys_ratelimit/", +] + +[[features.api_keys.when]] +if = "rbac" +paths = [ + "backend/tests/integration/api_keys_rbac/", +] + +[[features.api_keys.when]] +if = "taskiq" +paths = [ + "backend/src/modules/api_keys/tasks.py", + "backend/tests/unit/modules/api_keys/test_tasks.py", +] +contributes.task_modules = [{ value = "src.modules.api_keys.tasks", order = 11 }] + +[[features.api_keys.when]] +if = "tier_limits" +paths = [ + "backend/tests/integration/api_keys_tiers/", +] + +[features.admin] +summary = "SQLAdmin panel at /admin" +group = "Operations" +requires = ["accounts"] +dependencies = ["sqladmin>=0.28.0", "itsdangerous>=2.2.0"] +paths = [ + "backend/src/interfaces/admin/", + "backend/tests/unit/interfaces/admin/", +] + +[features.admin.contributes] +installers = ["src.interfaces.admin.initialize:install as admin_install"] +settings = ["src.interfaces.admin.settings:SQLAdminSettings"] + +[features.cache] +summary = "@cache over Redis or Memcached" +group = "Operations" +paths = [ + "backend/src/infrastructure/cache/", + "backend/tests/unit/infrastructure/cache/", +] + +[features.cache.contributes] +lifecycles = ["src.infrastructure.cache.initialize:lifecycle as cache_lifecycle"] +settings = ["src.infrastructure.cache.settings:CacheSettings"] +informational_readiness = ["src.infrastructure.cache.health:readiness as cache_readiness"] +cache_decorator = ["src.infrastructure.cache.decorator:cache as cached"] + +[[features.cache.when]] +if = "accounts" +paths = [ + "backend/tests/unit/infrastructure/cache/test_scoped_callers.py", +] + +[features.cache.options.backend] +choices = ["redis", "memcached"] +default = "redis" +env = { CACHE_BACKEND = "{value}" } +services = { memcached = ["memcached"] } +dependencies = { memcached = ["aiomcache>=0.8.2"] } + +[features.taskiq] +summary = "Background tasks on Redis or RabbitMQ" +group = "Operations" +services = ["worker", "scheduler"] +dependencies = [ + "taskiq>=0.11.20", + "taskiq-redis>=1.1.2", + "taskiq-aio-pika>=0.4.3", + "cryptography>=42.0.0", +] +dev_dependencies = ["taskiq[reload]>=0.11.20"] +paths = [ + "backend/src/infrastructure/taskiq/", + "backend/tests/unit/infrastructure/taskiq/", +] + +[features.taskiq.contributes] +lifecycles = ["src.infrastructure.taskiq.lifecycle:lifecycle as taskiq_lifecycle"] +settings = ["src.infrastructure.taskiq.settings:TaskiqSettings"] +informational_readiness = ["src.infrastructure.taskiq.health:readiness as broker_readiness"] + +[features.taskiq.options.broker] +choices = ["redis", "rabbitmq"] +default = "redis" +env = { TASKIQ_BROKER_TYPE = "{value}" } +services = { rabbitmq = ["rabbitmq"] } + +[[features.taskiq.when]] +if = "accounts" +paths = [ + "backend/src/infrastructure/taskiq/email.py", + "backend/tests/unit/infrastructure/taskiq/test_email.py", +] +contributes.email_sender = ["src.infrastructure.taskiq.email:queued_sender"] +contributes.task_modules = [{ value = "src.infrastructure.taskiq.email", order = 10 }] + + +[checks.toolchain.env] +ENVIRONMENT = "local" +SECRET_KEY = "a-key-only-the-toolchain-checks-run-with" +SESSION_BACKEND = "memory" +RATE_LIMITER_BACKEND = "memory" + +[wiring_defaults] +line_length = 128 +header = """Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change +fastro.toml (or [app] in it, for your own code) and run `fastro sync`.""" + +[[wiring]] +path = "backend/src/wiring/settings.py" +doc = """The project's settings: each selected feature's mixin on top of the core. + +Core comes last, so a feature can override a core default rather than the other way round.""" + +[[wiring.slots]] +kind = "class" +name = "Settings" +point = "settings" +append = ["src.infrastructure.config.base:CoreSettings"] +doc = "The settings of every selected feature, on top of the core." + +[[wiring.slots]] +kind = "raw" +code = "settings = Settings()" + +[[wiring]] +path = "backend/src/wiring/app.py" +doc = "The composition root: what the app mounts, starts and installs." +imports = [ + "from collections.abc import Callable", + "from typing import Any", + "from fastapi import APIRouter, FastAPI", + "from ..infrastructure.composition import Lifecycle, RouterMount", +] + +[[wiring.slots]] +kind = "tuple" +name = "ROUTER_MOUNTS" +point = "routers" +annotation = "tuple[RouterMount, ...]" +item = 'RouterMount({name}, "{prefix}", throttled={throttled})' + +[[wiring.slots]] +kind = "value" +name = "ROOT_ROUTERS" +point = "root_routers" +annotation = "tuple[APIRouter, ...]" +fallback = "()" + +[[wiring.slots]] +kind = "tuple" +name = "API_THROTTLE" +point = "api_throttle" +annotation = "tuple[Any, ...]" +item = "Depends({name})" +item_imports = ["from fastapi import Depends"] + +[[wiring.slots]] +kind = "tuple" +name = "LIFECYCLES" +point = "lifecycles" +annotation = "tuple[Lifecycle, ...]" + +[[wiring.slots]] +kind = "tuple" +name = "INSTALLERS" +point = "installers" +annotation = "tuple[Callable[[FastAPI], None], ...]" + +[[wiring.slots]] +kind = "value" +name = "DOCS_GUARD" +point = "docs_guard" +annotation = "Callable[..., Any] | None" +fallback = "None" + +[[wiring]] +path = "backend/src/wiring/hooks.py" +doc = "The contributions features make to each other's extension points." +imports = [ + "from ..infrastructure.composition import PermissionSource, RateLimitResolver, ReadinessCheck, TierDeleteGuard, TierDeleteRelease", +] + +[[wiring.slots]] +kind = "tuple" +name = "PERMISSION_SOURCES" +point = "permission_sources" +annotation = "tuple[PermissionSource, ...]" + +[[wiring.slots]] +kind = "tuple" +name = "RATE_LIMIT_RESOLVERS" +point = "rate_limit_resolvers" +annotation = "tuple[RateLimitResolver, ...]" + +[[wiring.slots]] +kind = "tuple" +name = "TIER_DELETE_GUARDS" +point = "tier_delete_guards" +annotation = "tuple[TierDeleteGuard, ...]" + +[[wiring.slots]] +kind = "tuple" +name = "TIER_DELETE_RELEASES" +point = "tier_delete_releases" +annotation = "tuple[TierDeleteRelease, ...]" + +[[wiring.slots]] +kind = "tuple" +name = "CRITICAL_READINESS_CHECKS" +point = "critical_readiness" +annotation = "tuple[ReadinessCheck, ...]" + +[[wiring.slots]] +kind = "tuple" +name = "INFORMATIONAL_READINESS_CHECKS" +point = "informational_readiness" +annotation = "tuple[ReadinessCheck, ...]" + +[[wiring]] +path = "backend/src/wiring/models.py" +doc = "Extension points of the user model: what other features add to ``User``." + +[[wiring.slots]] +kind = "class" +name = "UserModelExtensions" +point = "user_model" +doc = "Columns and relationships other features add to ``User``." + +[[wiring.slots]] +kind = "class" +name = "UserSchemaExtensions" +point = "user_schema" +fallback = "pydantic:BaseModel" +doc = "Fields other features add to the user read schemas." + +[[wiring]] +path = "backend/src/wiring/email.py" +doc = """The sender the account emails go out through. + +It is its own module because ``hooks`` reaches features that import the accounts feature back.""" +imports = ["from crudauth import EmailSender"] + +[[wiring.slots]] +kind = "value" +name = "EMAIL_SENDER" +point = "email_sender" +annotation = "EmailSender" +fallback = "HandingOverSender(build_sender())" +fallback_imports = [ + "from ..infrastructure.email.factory import build_sender", + "from ..infrastructure.email.senders import HandingOverSender", +] + +[[wiring]] +path = "backend/src/wiring/cache.py" +doc = "The decorator a route caches its response with." + +[[wiring.slots]] +kind = "reexport" +name = "cached" +point = "cache_decorator" +fallback = "src.infrastructure.uncached:cached" + +[[wiring]] +path = "backend/src/wiring/scope.py" +doc = """What tells a credential that carries a scope apart from its account's others. + +It is its own module, importing none of the other wiring, so that whatever keys what it stores by caller can read it.""" +imports = ["from collections.abc import Callable", "from crudauth import Principal"] + +[[wiring.slots]] +kind = "value" +name = "SCOPE_FINGERPRINT" +point = "scope_fingerprint" +annotation = "Callable[[Principal], str | None] | None" +fallback = "None" + +[[wiring]] +path = "backend/src/wiring/signup.py" +doc = """The columns features set on an account as it is created, on every signup path. + +The account setup reads it, so it is its own module: `wiring/hooks.py` reaches features that import the account setup back.""" +imports = ["from ..infrastructure.composition import NewAccountFields"] + +[[wiring.slots]] +kind = "tuple" +name = "NEW_ACCOUNT_FIELDS" +point = "new_account_fields" +annotation = "tuple[NewAccountFields, ...]" + +[[wiring]] +path = "backend/src/wiring/transports.py" +doc = "The authentication transports this project registers beside the session one." +imports = ["from crudauth import Transport"] + +[[wiring.slots]] +kind = "tuple" +name = "EXTRA_TRANSPORTS" +point = "extra_transports" +annotation = "tuple[Transport, ...]" + +[[wiring]] +path = "backend/src/wiring/tasks.py" +doc = """The modules whose background tasks the worker registers. + +A task the worker reports as unknown drops its message, so a module declaring one belongs in this list.""" + +[[wiring.slots]] +kind = "tuple" +name = "TASK_MODULES" +point = "task_modules" +annotation = "tuple[str, ...]" +literal = true + +[[wiring]] +path = "backend/src/wiring/tables.py" +doc = "Modules outside ``src/modules`` that declare tables on ``Base.metadata``." + +[[wiring.slots]] +kind = "tuple" +name = "TABLE_MODULES" +point = "table_modules" +annotation = "tuple[str, ...]" +literal = true + +[[wiring]] +path = "backend/src/wiring/admin.py" +doc = "The model views the admin panel registers." +if = "admin" + +[[wiring.slots]] +kind = "tuple" +name = "ADMIN_VIEWS" +point = "admin_views" +annotation = "tuple[type, ...]" + +[[wiring]] +path = "backend/scripts/seeders.py" +doc = "The initial-data steps ``scripts/setup_initial_data.py`` runs, in order." +imports = ["from collections.abc import Awaitable, Callable"] + +[[wiring.slots]] +kind = "tuple" +name = "SEEDERS" +point = "seeders" +annotation = "tuple[Callable[[], Awaitable[None]], ...]" + +[[wiring]] +path = "backend/tests/wiring.py" +doc = "Fixture modules of the selected features, loaded by ``tests/conftest.py``." + +[[wiring.slots]] +kind = "list" +name = "PYTEST_PLUGINS" +point = "test_plugins" +annotation = "list[str]" +literal = true + +[generators.deploy] +templates = "blueprint/templates/deploy" +modes = ["local", "prod", "nginx"] + +[generators.deploy.params.api_port] +type = "int" +default = 8000 +help = "Host port to publish the API on." + +[generators.deploy.params.workers] +type = "int" +default = 4 +help = "Number of API workers, for the prod and nginx modes." + +[generators.deploy.params.internal_subnet] +type = "cidr" +default = "172.31.240.0/24" +max_prefix = { v4 = 8, v6 = 48 } +help = "The compose network, and the only peers uvicorn takes forwarded headers from, in nginx mode." + +[commands."env secret"] +module = "scripts.gen_secret" +help = "Print a secret key the project's own rules accept." +outside_project = "token_hex" + +[commands."env validate"] +module = "scripts.validate_env" +help = "Audit this environment the way production would." + +[commands."db baseline"] +module = "scripts.baseline" +help = "Write this project's baseline migration, checked against the models." + +[commands."db tables"] +module = "scripts.create_tables" +help = "Create the tables the models declare, without alembic." + +[commands."db seed"] +module = "scripts.setup_initial_data" +help = "Run the initial-data steps of the selected features, in order." diff --git a/blueprint/overlay/.github/workflows/ci.yml.j2 b/blueprint/overlay/.github/workflows/ci.yml.j2 new file mode 100644 index 00000000..f4818f01 --- /dev/null +++ b/blueprint/overlay/.github/workflows/ci.yml.j2 @@ -0,0 +1,46 @@ +name: CI + +on: [push, pull_request] + +permissions: + contents: read + +jobs: + check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Install uv + uses: astral-sh/setup-uv@v5 + with: + enable-cache: true + cache-dependency-glob: backend/uv.lock + + - name: Set up Python + run: uv python install 3.11 + + - name: Install + run: uv sync --all-extras --locked --project backend --python 3.11 + + - name: Lint + working-directory: backend + run: | + uv run --no-sync ruff check . + uv run --no-sync ruff format --check . + + - name: Types + working-directory: backend + run: uv run --no-sync mypy src scripts migrations tests + + - name: Tests + working-directory: backend + run: uv run --no-sync pytest + env: + ENVIRONMENT: local + SECRET_KEY: a-secret-key-this-run-only-with-32-bytes + + - name: The project matches what it declares + run: | + uvx fastro@{{ fastro.version }} sync --check + uvx fastro@{{ fastro.version }} check diff --git a/blueprint/overlay/.gitignore b/blueprint/overlay/.gitignore new file mode 100644 index 00000000..81525504 --- /dev/null +++ b/blueprint/overlay/.gitignore @@ -0,0 +1,22 @@ +# Python +__pycache__/ +*.py[cod] +*.egg-info/ +.venv/ + +# Tooling caches +.mypy_cache/ +.pytest_cache/ +.ruff_cache/ +.coverage +htmlcov/ + +# Configuration: .env.example is the one that is committed +.env +.env.* +!.env.example + +# Editors +.idea/ +.vscode/ +.DS_Store diff --git a/blueprint/overlay/.pre-commit-config.yaml.j2 b/blueprint/overlay/.pre-commit-config.yaml.j2 new file mode 100644 index 00000000..9cc54f0d --- /dev/null +++ b/blueprint/overlay/.pre-commit-config.yaml.j2 @@ -0,0 +1,46 @@ +default_language_version: + python: python3.11 + +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v6.0.0 + hooks: + - id: end-of-file-fixer + - id: trailing-whitespace + - id: check-yaml + - id: check-case-conflict + - id: check-merge-conflict + - id: check-added-large-files + args: ["--maxkb=750", "--enforce-all"] + - id: detect-private-key + + - repo: https://github.com/asottile/pyupgrade + rev: v3.20.0 + hooks: + - id: pyupgrade + args: [--py311-plus] + name: Upgrade code to Python 3.11+ + + - repo: https://github.com/astral-sh/ruff-pre-commit + rev: v0.15.12 + hooks: + - id: ruff-check + args: [--fix] + - id: ruff-format + + - repo: local + hooks: + - id: mypy + name: Mypy + language: system + entry: bash -c 'cd backend && uv run --no-sync mypy src scripts migrations tests --config-file pyproject.toml' + pass_filenames: false + files: ^backend/(src|scripts|migrations|tests)/ + types: [python] + + - id: wiring + name: The wiring matches fastro.toml + language: system + entry: uvx fastro@{{ fastro.version }} sync --check + pass_filenames: false + files: ^(fastro\.toml|backend/src/wiring/) diff --git a/blueprint/overlay/AGENTS.md b/blueprint/overlay/AGENTS.md new file mode 100644 index 00000000..d64f738b --- /dev/null +++ b/blueprint/overlay/AGENTS.md @@ -0,0 +1,44 @@ +# Working in this project + +A FastAPI backend generated from the FastAPI-boilerplate blueprint by fastro. `backend/` holds +everything that runs. + +## The layers + +- `src/interfaces/`: the app itself, the FastAPI factory and the routers it mounts. +- `src/modules//`: one domain each, as `models.py`, `schemas.py`, `crud.py`, `service.py` + and `routes.py`. A module owns its tables and its rules, and reaches another module through + its service rather than its tables. +- `src/infrastructure/`: what every module uses, such as the settings and the database, plus + whatever each selected feature brought with it. +- `src/wiring/`: generated. It lists what this project selected, so the app imports one name per + extension point instead of asking what exists. + +## Adding code + +Add a domain as a module under `src/modules/`, following an existing one: the names and the file +split are the pattern to copy. Register its router and anything else it contributes under +`[app].contributes` in `fastro.toml`, then run `fastro sync`. + +**Never edit `src/wiring/`.** Those files are written from `blueprint.toml` and `fastro.toml`, and +`fastro sync` overwrites them. To change what is wired, change `[app]` in `fastro.toml` and sync. + +A setting of your own goes on a settings class in the module that reads it, contributed under +`[app].contributes.settings` in `fastro.toml` and picked up by `fastro sync`. Add its variable to +`backend/.env.example` outside the marked sections, which belong to the features that own them. +The files under `src/infrastructure/config/` are the blueprint's: a change there is one +`fastro update` has to merge, so keep your own settings in your module. + +## Before finishing + +From `backend/`: + +```bash +uv run --no-sync ruff check . && uv run --no-sync ruff format --check . +uv run --no-sync mypy src scripts migrations tests +uv run --no-sync pytest +``` + +Then `fastro check --json` from the project root, and read what it reports. A schema change needs a +migration: `uv run --no-sync alembic revision --autogenerate -m "what changed"`, reviewed by hand +before it is applied. diff --git a/blueprint/overlay/CLAUDE.md b/blueprint/overlay/CLAUDE.md new file mode 100644 index 00000000..43c994c2 --- /dev/null +++ b/blueprint/overlay/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/blueprint/overlay/README.md.j2 b/blueprint/overlay/README.md.j2 new file mode 100644 index 00000000..e965771b --- /dev/null +++ b/blueprint/overlay/README.md.j2 @@ -0,0 +1,109 @@ +# {{ project.name }} + +A FastAPI backend, generated from the FastAPI-boilerplate blueprint (`{{ blueprint.name }}` +{{ blueprint.version }}) by fastro {{ fastro.version }}. +{% if features %} +Selected: {{ features | join(", ") }}. +{%- else %} +Nothing optional is selected: this is the core, and `uvx fastro@{{ fastro.version }} add` brings +a feature in. +{%- endif %} + +Every command below runs from this directory: the ones in a subshell step into `backend/` and come +back. `uvx fastro@{{ fastro.version }}` fetches the tool that generated the project, so a checkout +needs nothing installed first. + +## Get it running + +```bash +uv sync --all-extras --project backend +cp backend/.env.example backend/.env +uvx fastro@{{ fastro.version }} env secret # put the key it prints in backend/.env +uvx fastro@{{ fastro.version }} make deploy local # writes the compose files +docker compose up -d +``` + +That stack runs the API{% if has("taskiq") %}, the worker and the scheduler{% endif %} and the data stores it needs, with `backend/src` mounted so a change reloads. Outside production the app builds the schema from the models as it boots, so there is nothing to migrate yet: the API is on , and its docs on `/docs`. +{%- if has("accounts") %} +Create the first superuser from the `ADMIN_*` variables in `backend/.env`: + +```bash +docker compose exec api python -m scripts.setup_initial_data +``` +{%- endif %} +{%- if has("admin") %} + +## The admin panel + +It ships switched off. Set `ADMIN_ENABLED=true` in `backend/.env`, with `ADMIN_USERNAME` and +`ADMIN_PASSWORD` values of your own, and it is served at `/admin`. Without both credentials it +stays unmounted, whatever the flag says. +{%- endif %} + +## Migrations + +When alembic should own the schema instead of the boot-time `create_all`, write the first revision +from the models and start the database empty, because the one that booted already holds the whole +schema and an upgrade against it fails on tables that exist: + +```bash +uvx fastro@{{ fastro.version }} db baseline +docker compose down -v +``` + +Set `CREATE_TABLES_ON_STARTUP=false` in `backend/.env`, then bring the stack back: a container +reads that file as it starts, so an edit needs `up -d` again. + +```bash +docker compose up -d +docker compose exec api alembic upgrade head +``` + +`db baseline` starts a throwaway Postgres of its own, so it runs here rather than in the container, +and leaves the revision in `backend/migrations/versions/` to commit. To keep what is already in the +development database instead of dropping it, run `docker compose exec api alembic stamp head`: the +schema is there, and stamping records it as applied. + +## Running the app on your machine + +The stack publishes Postgres{% if has("accounts") or has("cache") or has("taskiq") %} and Redis{% endif %} on localhost, so the app can run outside it. Point `POSTGRES_SERVER` and every `*_HOST` in `backend/.env` at `localhost`, then: + +```bash +docker compose stop api{% if has("taskiq") %} worker scheduler{% endif %} +docker compose up -d postgres{% if has("accounts") or has("cache") or has("taskiq") %} redis{% endif %} +(cd backend && uv run --no-sync uvicorn src.interfaces.main:app --reload) +``` + +The first line frees the port the stack publishes; without it nothing can bind it. +{%- if has("taskiq") %} + +The worker and the scheduler run the same way, against the broker `TASKIQ_BROKER_TYPE` names: + +```bash +(cd backend && uv run --no-sync taskiq worker src.infrastructure.taskiq.worker:default_broker) +(cd backend && uv run --no-sync taskiq scheduler src.infrastructure.taskiq.scheduler:scheduler) +``` +{%- endif %} + +## Work on it + +```bash +(cd backend && uv run --no-sync ruff check . && uv run --no-sync ruff format --check .) +(cd backend && uv run --no-sync mypy src scripts migrations tests) +(cd backend && uv run --no-sync pytest) +``` + +`AGENTS.md` says where code goes and what not to edit. From this directory, +`uvx fastro@{{ fastro.version }} check` reads the project the way CI does, and +`uvx fastro@{{ fastro.version }} sync --check` tells you whether `src/wiring/` matches +`fastro.toml`. + +## Change what it carries + +```bash +uvx fastro@{{ fastro.version }} features # what is selected, and what else there is +uvx fastro@{{ fastro.version }} add +uvx fastro@{{ fastro.version }} remove +``` + +Either one rewrites `src/wiring/`, the dependencies and `.env.example`, and says what it changed. diff --git a/cli/src/cli/features/_builtins/deploy/templates/local/docker-compose.yml.j2 b/blueprint/templates/deploy/local/docker-compose.yml.j2 similarity index 74% rename from cli/src/cli/features/_builtins/deploy/templates/local/docker-compose.yml.j2 rename to blueprint/templates/deploy/local/docker-compose.yml.j2 index 7f5d74f5..c2e4e5b1 100644 --- a/cli/src/cli/features/_builtins/deploy/templates/local/docker-compose.yml.j2 +++ b/blueprint/templates/deploy/local/docker-compose.yml.j2 @@ -1,40 +1,40 @@ -# Generated by `bp deploy generate local`. +# Generated by `fastro make deploy local`. # Hot-reload dev stack: API + Taskiq worker + Postgres + Redis. # Source is mounted into the container so file changes trigger a reload. -name: {{ project_name }} +name: {{ project.slug }} services: api: build: - context: {{ build_context }} - dockerfile: {{ backend_dockerfile }} + context: . + dockerfile: backend/Dockerfile target: dev env_file: - - {{ env_file }} + - ./backend/.env environment: POSTGRES_SERVER: postgres CACHE_REDIS_HOST: redis RATE_LIMITER_REDIS_HOST: redis TASKIQ_REDIS_HOST: redis volumes: - - {{ backend_context }}/src:/app/src - - {{ backend_context }}/tests:/app/tests + - ./backend/src:/app/src + - ./backend/tests:/app/tests ports: - - "{{ api_port }}:8000" + - "{{ params.api_port }}:8000" depends_on: postgres: condition: service_healthy redis: condition: service_healthy -{% if taskiq %} +{% if "worker" in services %} worker: build: - context: {{ build_context }} - dockerfile: {{ backend_dockerfile }} + context: . + dockerfile: backend/Dockerfile target: dev env_file: - - {{ env_file }} + - ./backend/.env environment: POSTGRES_SERVER: postgres CACHE_REDIS_HOST: redis @@ -45,21 +45,22 @@ services: taskiq worker src.infrastructure.taskiq.worker:default_broker --reload volumes: - - {{ backend_context }}/src:/app/src + - ./backend/src:/app/src depends_on: postgres: condition: service_healthy redis: condition: service_healthy - +{% endif %} +{%- if "scheduler" in services %} # Run exactly one of these: each scheduler fires every schedule it finds. scheduler: build: - context: {{ build_context }} - dockerfile: {{ backend_dockerfile }} + context: . + dockerfile: backend/Dockerfile target: dev env_file: - - {{ env_file }} + - ./backend/.env environment: POSTGRES_SERVER: postgres CACHE_REDIS_HOST: redis @@ -69,7 +70,7 @@ services: command: > taskiq scheduler src.infrastructure.taskiq.scheduler:scheduler volumes: - - {{ backend_context }}/src:/app/src + - ./backend/src:/app/src depends_on: postgres: condition: service_healthy @@ -77,9 +78,9 @@ services: condition: service_healthy {% endif %} postgres: - image: {{ postgres_image }} + image: postgres:16-alpine env_file: - - {{ env_file }} + - ./backend/.env volumes: - postgres-data:/var/lib/postgresql/data ports: @@ -91,7 +92,7 @@ services: retries: 10 redis: - image: {{ redis_image }} + image: redis:7-alpine volumes: - redis-data:/data ports: diff --git a/cli/src/cli/features/_builtins/deploy/templates/nginx/docker-compose.yml.j2 b/blueprint/templates/deploy/nginx/docker-compose.yml.j2 similarity index 82% rename from cli/src/cli/features/_builtins/deploy/templates/nginx/docker-compose.yml.j2 rename to blueprint/templates/deploy/nginx/docker-compose.yml.j2 index b5863e7d..b8873080 100644 --- a/cli/src/cli/features/_builtins/deploy/templates/nginx/docker-compose.yml.j2 +++ b/blueprint/templates/deploy/nginx/docker-compose.yml.j2 @@ -1,9 +1,9 @@ -# Generated by `bp deploy generate nginx`. +# Generated by `fastro make deploy nginx`. # Production stack with an nginx reverse proxy in front of the API. # Public traffic enters on port 80 (and 443 once you wire TLS); the # API container only exposes itself on the internal compose network. -name: {{ project_name }} +name: {{ project.slug }} services: # One-shot, and nothing waits on it: run it and only then restart the rest, so a @@ -11,11 +11,11 @@ services: # docker compose --profile migrate run --rm migrate migrate: build: - context: {{ build_context }} - dockerfile: {{ backend_dockerfile }} + context: . + dockerfile: backend/Dockerfile target: migrate env_file: - - {{ env_file }} + - ./backend/.env environment: POSTGRES_SERVER: postgres CONFIRM_PRODUCTION_MIGRATION: "yes" @@ -27,19 +27,19 @@ services: api: build: - context: {{ build_context }} - dockerfile: {{ backend_dockerfile }} + context: . + dockerfile: backend/Dockerfile target: prod env_file: - - {{ env_file }} + - ./backend/.env environment: POSTGRES_SERVER: postgres CACHE_REDIS_HOST: redis RATE_LIMITER_REDIS_HOST: redis TASKIQ_REDIS_HOST: redis TRUSTED_PROXY_HOPS: "1" - FORWARDED_ALLOW_IPS: "{{ internal_subnet }}" - WORKERS: "{{ workers }}" + FORWARDED_ALLOW_IPS: "{{ params.internal_subnet }}" + WORKERS: "{{ params.workers }}" expose: - "8000" depends_on: @@ -54,14 +54,14 @@ services: retries: 5 start_period: 20s restart: unless-stopped -{% if taskiq %} +{% if "worker" in services %} worker: build: - context: {{ build_context }} - dockerfile: {{ backend_dockerfile }} + context: . + dockerfile: backend/Dockerfile target: prod env_file: - - {{ env_file }} + - ./backend/.env environment: POSTGRES_SERVER: postgres CACHE_REDIS_HOST: redis @@ -75,15 +75,16 @@ services: redis: condition: service_healthy restart: unless-stopped - +{% endif %} +{%- if "scheduler" in services %} # Run exactly one of these: each scheduler fires every schedule it finds. scheduler: build: - context: {{ build_context }} - dockerfile: {{ backend_dockerfile }} + context: . + dockerfile: backend/Dockerfile target: prod env_file: - - {{ env_file }} + - ./backend/.env environment: POSTGRES_SERVER: postgres CACHE_REDIS_HOST: redis @@ -99,7 +100,7 @@ services: restart: unless-stopped {% endif %} nginx: - image: {{ nginx_image }} + image: nginx:1.27-alpine ports: - "80:80" volumes: @@ -109,9 +110,9 @@ services: restart: unless-stopped postgres: - image: {{ postgres_image }} + image: postgres:16-alpine env_file: - - {{ env_file }} + - ./backend/.env volumes: - postgres-data:/var/lib/postgresql/data healthcheck: @@ -122,7 +123,7 @@ services: restart: unless-stopped redis: - image: {{ redis_image }} + image: redis:7-alpine command: ["redis-server", "--appendonly", "yes"] volumes: - redis-data:/data @@ -144,4 +145,4 @@ networks: default: ipam: config: - - subnet: "{{ internal_subnet }}" + - subnet: "{{ params.internal_subnet }}" diff --git a/cli/src/cli/features/_builtins/deploy/templates/nginx/default.conf.j2 b/blueprint/templates/deploy/nginx/nginx/default.conf.j2 similarity index 87% rename from cli/src/cli/features/_builtins/deploy/templates/nginx/default.conf.j2 rename to blueprint/templates/deploy/nginx/nginx/default.conf.j2 index 4c06380a..8873337b 100644 --- a/cli/src/cli/features/_builtins/deploy/templates/nginx/default.conf.j2 +++ b/blueprint/templates/deploy/nginx/nginx/default.conf.j2 @@ -1,7 +1,7 @@ -# Generated by `bp deploy generate nginx`. +# Generated by `fastro make deploy nginx`. # Drop-in nginx vhost in front of the FastAPI app container. -upstream {{ project_name }}_api { +upstream {{ project.slug }}_api { server api:8000; } @@ -27,7 +27,7 @@ server { proxy_read_timeout 300s; location / { - proxy_pass http://{{ project_name }}_api; + proxy_pass http://{{ project.slug }}_api; proxy_redirect off; } } diff --git a/cli/src/cli/features/_builtins/deploy/templates/prod/docker-compose.yml.j2 b/blueprint/templates/deploy/prod/docker-compose.yml.j2 similarity index 81% rename from cli/src/cli/features/_builtins/deploy/templates/prod/docker-compose.yml.j2 rename to blueprint/templates/deploy/prod/docker-compose.yml.j2 index 22bec610..d792a5a8 100644 --- a/cli/src/cli/features/_builtins/deploy/templates/prod/docker-compose.yml.j2 +++ b/blueprint/templates/deploy/prod/docker-compose.yml.j2 @@ -1,9 +1,9 @@ -# Generated by `bp deploy generate prod`. +# Generated by `fastro make deploy prod`. # Production-ish single-host stack: multi-worker API + Taskiq worker # + Postgres + Redis. The API is exposed directly on the host port — # add a reverse proxy (or use the `nginx` mode) before public traffic. -name: {{ project_name }} +name: {{ project.slug }} services: # One-shot, and nothing waits on it: run it and only then restart the rest, so a @@ -11,11 +11,11 @@ services: # docker compose --profile migrate run --rm migrate migrate: build: - context: {{ build_context }} - dockerfile: {{ backend_dockerfile }} + context: . + dockerfile: backend/Dockerfile target: migrate env_file: - - {{ env_file }} + - ./backend/.env environment: POSTGRES_SERVER: postgres CONFIRM_PRODUCTION_MIGRATION: "yes" @@ -27,19 +27,19 @@ services: api: build: - context: {{ build_context }} - dockerfile: {{ backend_dockerfile }} + context: . + dockerfile: backend/Dockerfile target: prod env_file: - - {{ env_file }} + - ./backend/.env environment: POSTGRES_SERVER: postgres CACHE_REDIS_HOST: redis RATE_LIMITER_REDIS_HOST: redis TASKIQ_REDIS_HOST: redis - WORKERS: "{{ workers }}" + WORKERS: "{{ params.workers }}" ports: - - "{{ api_port }}:8000" + - "{{ params.api_port }}:8000" depends_on: postgres: condition: service_healthy @@ -52,14 +52,14 @@ services: retries: 5 start_period: 20s restart: unless-stopped -{% if taskiq %} +{% if "worker" in services %} worker: build: - context: {{ build_context }} - dockerfile: {{ backend_dockerfile }} + context: . + dockerfile: backend/Dockerfile target: prod env_file: - - {{ env_file }} + - ./backend/.env environment: POSTGRES_SERVER: postgres CACHE_REDIS_HOST: redis @@ -73,15 +73,16 @@ services: redis: condition: service_healthy restart: unless-stopped - +{% endif %} +{%- if "scheduler" in services %} # Run exactly one of these: each scheduler fires every schedule it finds. scheduler: build: - context: {{ build_context }} - dockerfile: {{ backend_dockerfile }} + context: . + dockerfile: backend/Dockerfile target: prod env_file: - - {{ env_file }} + - ./backend/.env environment: POSTGRES_SERVER: postgres CACHE_REDIS_HOST: redis @@ -97,9 +98,9 @@ services: restart: unless-stopped {% endif %} postgres: - image: {{ postgres_image }} + image: postgres:16-alpine env_file: - - {{ env_file }} + - ./backend/.env volumes: - postgres-data:/var/lib/postgresql/data healthcheck: @@ -110,7 +111,7 @@ services: restart: unless-stopped redis: - image: {{ redis_image }} + image: redis:7-alpine command: ["redis-server", "--appendonly", "yes"] volumes: - redis-data:/data diff --git a/blueprint/tests/conftest.py b/blueprint/tests/conftest.py new file mode 100644 index 00000000..e13b6c19 --- /dev/null +++ b/blueprint/tests/conftest.py @@ -0,0 +1,42 @@ +import shutil +import subprocess +import sys +from collections.abc import Callable +from pathlib import Path + +import pytest + +REPO_ROOT = Path(__file__).resolve().parents[2] + +FastroRunner = Callable[..., subprocess.CompletedProcess[str]] + + +@pytest.fixture +def tracked_tree(tmp_path: Path) -> Path: + """A copy of every file git tracks or would track, so a test can change it freely.""" + destination = tmp_path / "blueprint" + listed = subprocess.run( + ["git", "ls-files", "-z", "--cached", "--others", "--exclude-standard"], + cwd=REPO_ROOT, + capture_output=True, + text=True, + check=True, + ).stdout + for name in filter(None, listed.split("\0")): + source = REPO_ROOT / name + if source.is_file(): + (destination / name).parent.mkdir(parents=True, exist_ok=True) + shutil.copy2(source, destination / name) + + return destination + + +@pytest.fixture +def fastro() -> FastroRunner: + """Run the fastro the repository root installs, in a directory of the caller's choosing.""" + + def run(*arguments: str, cwd: Path) -> subprocess.CompletedProcess[str]: + command = [sys.executable, "-m", "fastro", *arguments] + return subprocess.run(command, cwd=cwd, capture_output=True, text=True, check=False) + + return run diff --git a/blueprint/tests/retired.py b/blueprint/tests/retired.py new file mode 100644 index 00000000..ef3b8061 --- /dev/null +++ b/blueprint/tests/retired.py @@ -0,0 +1,60 @@ +"""The developer CLI this repository used to ship, and the drill that built the repository +without each feature, as the scans that keep them gone read them. + +Every needle is assembled from pieces, so the files that hold them never match themselves. +""" + +import re +import subprocess +from collections.abc import Iterator +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parents[2] + +OLD_COMMAND = "b" + "p" + +RUNS_OLD_COMMAND = re.compile(rf"\b{OLD_COMMAND} (?:deploy|env)\b|`{OLD_COMMAND}`") +"""A line that runs the old command, or names it in code.""" + +NAMES_OLD_COMMAND = re.compile(rf"{RUNS_OLD_COMMAND.pattern}|\brun {OLD_COMMAND}\b|\b{OLD_COMMAND}(?:<[^>]*>)? CLI\b") +"""A line that runs the old command, names it in code, or calls it a CLI.""" + +SAYS_OLD_COMMAND_EXITS = re.compile(rf"^`{OLD_COMMAND} deploy generate` exits 2 too, in a project made before fastro\.$") +"""The one line a reader sees that names the old command: the fastro page saying it is refused.""" + +OLD_PACKAGE = "c" + "li" + +NAMES_OLD_PACKAGE = re.compile(rf"(? Iterator[tuple[str, str]]: + """Every file git tracks or would add, that reads as UTF-8, by its path from the root, with its text.""" + listed = subprocess.run( + ["git", "ls-files", "-z", "--cached", "--others", "--exclude-standard"], + cwd=REPO_ROOT, + capture_output=True, + text=True, + check=True, + ) + for name in filter(None, listed.stdout.split("\0")): + path = REPO_ROOT / name + if not path.is_file(): + continue + try: + yield name, path.read_text(encoding="utf-8") + except UnicodeDecodeError: + continue + + +def shown_pages() -> Iterator[tuple[str, str]]: + """The Markdown a reader sees: the README and the docs, the changelog's history aside.""" + for name, text in tracked_text(): + if name == "README.md" or (name.startswith("docs/") and name.endswith(".md") and name != "docs/changelog.md"): + yield name, text diff --git a/blueprint/tests/test_deploy_generator.py b/blueprint/tests/test_deploy_generator.py new file mode 100644 index 00000000..5cc2e62e --- /dev/null +++ b/blueprint/tests/test_deploy_generator.py @@ -0,0 +1,29 @@ +"""The catalog's `[generators.deploy]` modes, against the template trees and what `fastro make deploy` offers.""" + +import subprocess +import sys +import tomllib +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parents[2] +GENERATOR = tomllib.loads((REPO_ROOT / "blueprint.toml").read_text())["generators"]["deploy"] + + +def test_the_deploy_modes_are_the_template_trees_and_the_ones_fastro_offers(): + """A mode with no template tree would be offered and then fail; a tree with no mode is dead.""" + templates = REPO_ROOT / GENERATOR["templates"] + offered = subprocess.run( + [sys.executable, "-m", "fastro", "make", "deploy", "--help"], cwd=REPO_ROOT, capture_output=True, text=True + ) + + assert sorted(child.name for child in templates.iterdir() if child.is_dir()) == sorted(GENERATOR["modes"]) + assert f"Modes: {', '.join(GENERATOR['modes'])}" in offered.stdout + + +def test_the_nginx_config_sits_where_the_nginx_compose_file_mounts_it(): + """Files are written relative to the mode's tree, and the compose file mounts ./nginx/default.conf.""" + tree = REPO_ROOT / GENERATOR["templates"] / "nginx" + compose = (tree / "docker-compose.yml.j2").read_text() + + assert (tree / "nginx" / "default.conf.j2").is_file() + assert "./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro" in compose diff --git a/cli/tests/test_deploy_templates.py b/blueprint/tests/test_deploy_templates.py similarity index 61% rename from cli/tests/test_deploy_templates.py rename to blueprint/tests/test_deploy_templates.py index 131b47e6..707c5a35 100644 --- a/cli/tests/test_deploy_templates.py +++ b/blueprint/tests/test_deploy_templates.py @@ -1,40 +1,60 @@ -"""What the generated compose files say about running this app behind a proxy.""" +"""What the generated compose files say about running this app behind a proxy. +The templates are rendered with the generator context of catalog spec 6.2, under +``StrictUndefined``: a template that reaches for anything the tool doesn't pass fails here. +""" + +import tomllib from pathlib import Path +from typing import Any import pytest import yaml -from jinja2 import Environment, FileSystemLoader +from jinja2 import Environment, FileSystemLoader, StrictUndefined + +REPO_ROOT = Path(__file__).resolve().parents[2] + +CATALOG = tomllib.loads((REPO_ROOT / "blueprint.toml").read_text()) + +TEMPLATES = Path(__file__).resolve().parents[1] / "templates" / "deploy" -from cli.features._builtins.deploy.feature import DEFAULT_INTERNAL_SUBNET +INTERNAL_SUBNET = "172.31.240.0/24" +"""The default of the ``internal_subnet`` param.""" -TEMPLATES = Path(__file__).resolve().parents[1] / "src/cli/features/_builtins/deploy/templates" +TASKIQ_SERVICES = ("scheduler", "worker") +"""What the taskiq feature puts in ``services``.""" -CONTEXT = { - "mode": "nginx", - "project_name": "example", - "api_port": 8000, - "workers": 4, - "postgres_image": "postgres:16-alpine", - "redis_image": "redis:7-alpine", - "nginx_image": "nginx:1.27-alpine", - "backend_context": "./backend", - "build_context": ".", - "backend_dockerfile": "backend/Dockerfile", - "env_file": "./backend/.env", - "internal_subnet": DEFAULT_INTERNAL_SUBNET, - "taskiq": True, -} +def _context( + features: tuple[str, ...] = ("accounts", "taskiq"), + services: tuple[str, ...] = TASKIQ_SERVICES, + **params: Any, +) -> dict[str, Any]: + """The spec 6.2 context, as the tool builds it for a generator.""" + return { + "project": {"name": "example", "slug": "example"}, + "blueprint": {"name": CATALOG["blueprint"]["name"], "version": CATALOG["blueprint"]["version"]}, + "fastro": {"version": "0.1.0"}, + "features": list(features), + "options": {}, + "services": sorted(services), + "params": {"api_port": 8000, "workers": 4, "internal_subnet": INTERNAL_SUBNET, **params}, + "has": lambda name: name in features, + } -def _render(template: str, mode: str = "nginx", **overrides) -> str: - environment = Environment(loader=FileSystemLoader(TEMPLATES), keep_trailing_newline=True) - return environment.get_template(template).render({**CONTEXT, "mode": mode, **overrides}) +def _render(template: str, **overrides: Any) -> str: + environment = Environment( + loader=FileSystemLoader(TEMPLATES), + keep_trailing_newline=True, + undefined=StrictUndefined, + ) + return environment.get_template(template).render(_context(**overrides)) -def _compose(mode: str, **overrides) -> dict: - return yaml.safe_load(_render(f"{mode}/docker-compose.yml.j2", mode, **overrides)) + +def _compose(mode: str, **overrides: Any) -> dict: + return yaml.safe_load(_render(f"{mode}/docker-compose.yml.j2", **overrides)) @pytest.mark.parametrize("mode", ["prod", "nginx"]) @@ -62,12 +82,12 @@ def test_forwarded_headers_are_trusted_only_from_the_compose_network(): """With a wildcard, uvicorn reads the leftmost X-Forwarded-For entry, which the client sets.""" compose = _compose("nginx") - assert compose["services"]["api"]["environment"]["FORWARDED_ALLOW_IPS"] == DEFAULT_INTERNAL_SUBNET - assert compose["networks"]["default"]["ipam"]["config"] == [{"subnet": DEFAULT_INTERNAL_SUBNET}] + assert compose["services"]["api"]["environment"]["FORWARDED_ALLOW_IPS"] == INTERNAL_SUBNET + assert compose["networks"]["default"]["ipam"]["config"] == [{"subnet": INTERNAL_SUBNET}] def test_nginx_hides_its_version(): - assert "server_tokens off;" in _render("nginx/default.conf.j2") + assert "server_tokens off;" in _render("nginx/nginx/default.conf.j2") def test_the_local_compose_does_not_claim_a_proxy(): @@ -87,16 +107,16 @@ def test_the_local_compose_publishes_its_databases_to_the_host_only(): def test_nginx_sends_only_the_address_it_saw(): """A client's own X-Forwarded-For must not reach the app as its address.""" - conf = _render("nginx/default.conf.j2") + conf = _render("nginx/nginx/default.conf.j2") assert "proxy_set_header X-Forwarded-For $remote_addr;" in conf assert "$proxy_add_x_forwarded_for" not in conf def test_the_compose_network_quotes_the_subnet(): - rendered = _render("nginx/docker-compose.yml.j2", "nginx") + rendered = _render("nginx/docker-compose.yml.j2") - assert f'- subnet: "{DEFAULT_INTERNAL_SUBNET}"' in rendered + assert f'- subnet: "{INTERNAL_SUBNET}"' in rendered SCHEDULER_COMMAND = "taskiq scheduler src.infrastructure.taskiq.scheduler:scheduler" @@ -113,7 +133,7 @@ def test_a_project_with_taskiq_gets_one_scheduler(mode: str): @pytest.mark.parametrize("mode", ["local", "prod", "nginx"]) def test_a_project_without_taskiq_gets_neither_worker_nor_scheduler(mode: str): - services = _compose(mode, taskiq=False)["services"] + services = _compose(mode, features=("accounts",), services=())["services"] assert "worker" not in services assert "scheduler" not in services @@ -157,3 +177,26 @@ def test_the_database_probe_reads_the_user_inside_the_container(mode: str): probe = " ".join(_compose(mode)["services"]["postgres"]["healthcheck"]["test"]) assert "$${POSTGRES_USER" in probe + + +@pytest.mark.parametrize("mode", ["local", "prod", "nginx"]) +def test_the_compose_project_is_named_after_the_project(mode: str): + """The slug is what compose accepts as a project name, and what the nginx upstream is keyed on.""" + assert _compose(mode)["name"] == "example" + + +def test_the_api_runs_the_workers_the_params_asked_for(): + """``workers`` and ``api_port`` are generator params, so a flag has to reach the template.""" + compose = _compose("prod", workers=7, api_port=9001) + + assert compose["services"]["api"]["environment"]["WORKERS"] == "7" + assert compose["services"]["api"]["ports"] == ["9001:8000"] + + +@pytest.mark.parametrize("mode", ["local", "prod", "nginx"]) +def test_each_background_service_follows_its_own_entry(mode: str): + """The blocks are keyed on ``services``, not on the feature, so one without the other works.""" + services = _compose(mode, services=("worker",))["services"] + + assert "worker" in services + assert "scheduler" not in services diff --git a/blueprint/tests/test_docs_commands.py b/blueprint/tests/test_docs_commands.py new file mode 100644 index 00000000..7050ab56 --- /dev/null +++ b/blueprint/tests/test_docs_commands.py @@ -0,0 +1,228 @@ +"""The commands the README and the docs tell a reader to run are ones the pinned fastro has.""" + +import re +import shlex +import tomllib +from collections.abc import Iterator + +import click +import pytest +import typer.main +from fastro import make as making +from fastro.cli import app +from fastro.engine import blueprint +from fastro.tools import installed_version +from fastro.verify import verify_sets +from retired import OLD_COMMAND, OLD_DRILL, REPO_ROOT, RUNS_OLD_COMMAND, SAYS_OLD_COMMAND_EXITS, shown_pages + + +def _fastro() -> click.Group: + command = typer.main.get_command(app) + assert isinstance(command, click.Group) + + return command + + +FASTRO = _fastro() + +LAUNCHERS = (("uv", "run", "--no-sync"), ("uv", "run"), ("uvx",), ("python", "-m")) + +STOPS = {"|", "&&", "||", ";"} + + +def _code(text: str) -> Iterator[tuple[str, bool]]: + """Every line of every fenced block, a commented-out alternative included, and every inline + code span outside them, each with whether it is a line a reader runs.""" + fenced = False + for line in text.splitlines(): + if line.lstrip().startswith("```"): + fenced = not fenced + elif fenced: + yield re.sub(r"^\s*#\s*(?:or:\s*)?", "", line), True + else: + yield from ((span, False) for span in re.findall(r"`([^`\n]+)`", line)) + + +def _fastro_words(code: str) -> list[str] | None: + """The words after `fastro` when the code runs it, through any launcher; `None` when it doesn't.""" + lexer = shlex.shlex(code.strip().removeprefix("$ "), posix=True, punctuation_chars=True) + lexer.whitespace_split = True + try: + words = list(lexer) + except ValueError: + return None + for index, word in enumerate(words): + if word in STOPS: + words = words[:index] + break + for launcher in LAUNCHERS: + if tuple(words[: len(launcher)]) == launcher: + words = words[len(launcher) :] + break + if not words or words[0].split("@")[0] != "fastro": + return None + + return words[1:] + + +def _commands() -> list[tuple[str, list[str], bool]]: + return [ + (f"{name}: {code.strip()}", words, runs) + for name, text in shown_pages() + for code, runs in _code(text) + if (words := _fastro_words(code)) is not None + ] + + +def _refusal(words: list[str], runs: bool = True) -> str | None: + """Why the pinned fastro would refuse these words, or `None` when it takes them. + + A command named in a sentence, with nothing after it, only has to exist; a line a reader + runs has to parse.""" + command: click.Command = FASTRO + remaining = list(words) + while isinstance(command, click.Group) and remaining and not remaining[0].startswith("-"): + if remaining[0] not in command.commands: + return f"{command.name} has no command {remaining[0]!r}" + command = command.commands[remaining.pop(0)] + if isinstance(command, click.Group) and remaining: + return f"{command.name} takes a command before {remaining[0]!r}" + if command is FASTRO.commands["make"]: + return _make_refusal(remaining, runs) + if not remaining and not runs: + return None + try: + command.make_context(command.name, remaining) + except click.ClickException as refused: + return refused.format_message() + + return None + + +def _make_refusal(words: list[str], runs: bool) -> str | None: + """Why `fastro make` would refuse these words: it reads them itself, against this blueprint's generators.""" + if not words or words[0] == making.HELP: + return None + catalog = blueprint.load("blueprint.toml", (REPO_ROOT / "blueprint.toml").read_text(), installed_version()) + if not runs and len(words) <= 1: + return None if not words or words[0] in catalog.generators else f"make has no generator {words[0]!r}" + try: + making.parse(catalog, words) + except (making.UsageError, making.Refused) as refused: + return str(refused) + + return None + + +def test_no_page_a_reader_sees_runs_the_retired_command(): + """B3 item 2 removes the old developer CLI; every command it ran is a fastro command now.""" + found = [ + f"{name}:{number}" + for name, text in shown_pages() + for number, line in enumerate(text.splitlines(), 1) + if RUNS_OLD_COMMAND.search(line) and not (name == "docs/user-guide/fastro.md" and SAYS_OLD_COMMAND_EXITS.match(line)) + ] + + assert not found, found + + +def test_no_code_block_a_reader_sees_runs_the_drill(): + """A page may still name it in prose, but a block a reader copies runs fastro.""" + found = [ + f"{name}: {code.strip()}" for name, text in shown_pages() for code, runs in _code(text) if runs and OLD_DRILL in code + ] + + assert found == [] + + +def test_the_pages_show_fastro_commands(): + """The rule below has something to read, so a reader that stopped finding commands would show.""" + assert any(words[:2] == ["make", "deploy"] and runs for _, words, runs in _commands()) + + +@pytest.mark.parametrize(("where", "words", "runs"), _commands(), ids=[where for where, _, _ in _commands()]) +def test_every_fastro_command_a_page_shows_is_one_the_pinned_fastro_takes(where: str, words: list[str], runs: bool): + assert _refusal(words, runs) is None, (where, _refusal(words, runs)) + + +FENCE = "`" * 3 + + +@pytest.mark.parametrize( + ("page", "refused"), + [ + (f"{FENCE}bash\nuv run --no-sync fastro make deploy prod --wokers 8\n{FENCE}", True), + ("Run `fastro env gen-secret`.", True), + ("Run `fastro make deploy prodd`.", True), + ("Run `fastro env secret --bytes 8`.", True), + ("Run `fastro make deploy prod --workers many`.", True), + ("Run `fastro make deploy prod extra`.", True), + (f"{FENCE}bash\n# or: uv run --no-sync fastro make deploy prodd\n{FENCE}", True), + (f"{FENCE}bash\nuv run --no-sync fastro make deploy # writes the compose file\n{FENCE}", True), + ("`fastro make deploy` writes it.", False), + ("Run `fastro make deploy --workers 8 prod`.", True), + ("Run `fastro make deploy prod --workers 8`.", False), + ("Run `fastro make deploy local --internal-subnet '*'`.", True), + ("Run `fastro make deploy prod|cat`.", False), + (f"{FENCE}bash\nuv run --no-sync fastro make\n{FENCE}", False), + ("Run `fastro make --help`.", False), + (f"{FENCE}bash\n# or: uv run --no-sync fastro make deploy prod\n{FENCE}", False), + (f"{FENCE}bash\n$ uv run --no-sync fastro env secret --bytes 16 | gh secret set SECRET_KEY\n{FENCE}", False), + ("Run `uv run --no-sync fastro make deploy nginx --internal-subnet=10.89.0.0/24 --dry-run`.", False), + (f"{FENCE}bash\nfastro sync --check # in the blueprint repo\n{FENCE}", False), + ], +) +def test_the_reader_refuses_what_fastro_would(page: str, refused: bool): + read = [(words, runs) for code, runs in _code(page) if (words := _fastro_words(code)) is not None] + + assert len(read) == 1, read + assert (_refusal(*read[0]) is not None) is refused + + +@pytest.mark.parametrize( + ("line", "runs"), + [ + (f"uv run --no-sync {OLD_COMMAND} env validate", True), + (f"the `{OLD_COMMAND}` tool", True), + (f"{OLD_COMMAND}-and-fastro", False), + ("redis-cli ping", False), + ], +) +def test_the_old_command_is_read_where_it_runs(line: str, runs: bool): + assert bool(RUNS_OLD_COMMAND.search(line)) is runs + + +def test_every_root_sync_a_page_shows_installs_the_backend(): + """The root project doesn't depend on the backend, so `--all-packages` is what installs it.""" + root = tomllib.loads((REPO_ROOT / "pyproject.toml").read_text()) + backend = tomllib.loads((REPO_ROOT / "backend" / "pyproject.toml").read_text())["project"]["name"] + groups = root.get("dependency-groups", {}).values() + requirements = [*root["project"].get("dependencies", []), *(requirement for group in groups for requirement in group)] + pages = [*shown_pages(), ("CONTRIBUTING.md", (REPO_ROOT / "CONTRIBUTING.md").read_text())] + syncs = [ + f"{name}: {code.strip()}" for name, text in pages for code, _ in _code(text) if code.strip().startswith("uv sync ") + ] + + assert not [requirement for requirement in requirements if re.match(rf"{re.escape(backend)}(?![\w.-])", requirement)] + assert syncs + assert [sync for sync in syncs if "--all-packages" not in sync.split()] == [] + + +def _verify_sets() -> set[str]: + catalog = blueprint.load("blueprint.toml", (REPO_ROOT / "blueprint.toml").read_text(), installed_version()) + + return set(verify_sets(catalog)) + + +def test_every_set_a_page_verifies_is_one_verify_builds(): + named = [ + (name, word) + for name, text in shown_pages() + for code, runs in _code(text) + if runs and (words := _fastro_words(code)) and words[:2] == ["blueprint", "verify"] + for word in words[2:] + if not word.startswith("-") + ] + + assert named + assert [(name, word) for name, word in named if word not in _verify_sets()] == [] diff --git a/blueprint/tests/test_docs_links.py b/blueprint/tests/test_docs_links.py new file mode 100644 index 00000000..5ac75306 --- /dev/null +++ b/blueprint/tests/test_docs_links.py @@ -0,0 +1,129 @@ +"""Every link between the docs pages lands on a page, and on a heading when it names one. + +zensical builds with `toc` and no custom slugify, so a heading's id is Python-Markdown's default +slug of its text, or the `{#id}` it sets. +""" + +import re +import tomllib +import unicodedata +from collections.abc import Iterator +from pathlib import Path +from typing import Any + +import pytest +from retired import OLD_PACKAGE + +REPO_ROOT = Path(__file__).resolve().parents[2] +DOCS = REPO_ROOT / "docs" +SITE = tomllib.loads((REPO_ROOT / "zensical.toml").read_text())["project"] + +LINK = re.compile(r"!?\[[^\]]*\]\(([^)\s]+)(?:\s+\"[^\"]*\")?\)") + + +def _pages() -> list[Path]: + return sorted(DOCS.rglob("*.md")) + + +def _outside_fences(text: str) -> Iterator[tuple[int, str]]: + fenced = False + for number, line in enumerate(text.splitlines(), 1): + if line.lstrip().startswith("```"): + fenced = not fenced + elif not fenced: + yield number, line + + +def slug(heading: str) -> str: + """Python-Markdown's default `toc` slug of a heading's text.""" + text = re.sub(r"\[([^\]]*)\]\([^)]*\)", r"\1", heading) + text = re.sub(r"[`*]", "", text) + text = unicodedata.normalize("NFKD", text).encode("ascii", "ignore").decode("ascii") + text = re.sub(r"[^\w\s-]", "", text).strip().lower() + + return re.sub(r"[-\s]+", "-", text) + + +def _anchors(page: Path) -> set[str]: + anchors = set() + for _, line in _outside_fences(page.read_text()): + heading = re.match(r"^#{1,6}\s+(.*?)\s*$", line) + if not heading: + continue + given = re.search(r"\{[^}]*#([\w-]+)[^}]*\}\s*$", heading[1]) + anchors.add(given[1] if given else slug(heading[1])) + + return anchors + + +def _links() -> list[tuple[str, str]]: + return [ + (f"{page.relative_to(DOCS)}:{number}", target) + for page in _pages() + for number, line in _outside_fences(page.read_text()) + for target in LINK.findall(re.sub(r"`[^`]*`", "", line)) + if not re.match(r"^[a-z]+:", target) + ] + + +def _resolved(where: str, target: str) -> tuple[Path, str]: + page = DOCS / where.rsplit(":", 1)[0] + path, _, anchor = target.partition("#") + + return ((page.parent / path).resolve() if path else page), anchor + + +def test_the_docs_link_to_one_another(): + """The rule below has links to read.""" + assert len(_links()) > 50 + + +@pytest.mark.parametrize(("where", "target"), _links(), ids=[f"{where} {target}" for where, target in _links()]) +def test_every_relative_link_lands_on_a_file_and_a_heading(where: str, target: str): + path, anchor = _resolved(where, target) + + assert path.is_file(), (where, target) + if anchor and path.suffix == ".md": + assert anchor in _anchors(path), (where, target, sorted(_anchors(path))) + + +def _nav_pages(entries: Any) -> Iterator[str]: + if isinstance(entries, str): + yield entries + elif isinstance(entries, list): + for entry in entries: + yield from _nav_pages(entry) + elif isinstance(entries, dict): + for value in entries.values(): + yield from _nav_pages(value) + + +def test_every_page_is_in_the_nav_and_every_nav_entry_is_a_page(): + listed = sorted(_nav_pages(SITE["nav"])) + + assert sorted(set(listed)) == listed, "a page listed twice" + assert listed == sorted(page.relative_to(DOCS).as_posix() for page in _pages()) + + +def test_every_redirect_leaves_a_page_that_is_gone_for_one_that_is_there(): + redirects = SITE["plugins"]["redirects"]["redirect_maps"] + + assert redirects == {f"{OLD_PACKAGE}/{page}.md": "user-guide/fastro.md" for page in ("index", "commands", "plugins")} + for gone, there in redirects.items(): + assert not (DOCS / gone).exists(), gone + assert (DOCS / there).is_file(), there + + +@pytest.mark.parametrize( + ("heading", "expected"), + [ + ("Authentication & Security", "authentication-security"), + ("Writing the compose files: `fastro make deploy`", "writing-the-compose-files-fastro-make-deploy"), + ("What `fastro make deploy local` Writes", "what-fastro-make-deploy-local-writes"), + ("Neon (Serverless Postgres)", "neon-serverless-postgres"), + ("Generating a Strong `SECRET_KEY`", "generating-a-strong-secret_key"), + ("Café Résumé", "cafe-resume"), + ], +) +def test_the_slug_is_the_one_toc_writes(heading: str, expected: str): + assert slug(heading) == expected diff --git a/blueprint/tests/test_docs_settings.py b/blueprint/tests/test_docs_settings.py new file mode 100644 index 00000000..d13bfc3c --- /dev/null +++ b/blueprint/tests/test_docs_settings.py @@ -0,0 +1,131 @@ +"""The settings pattern the docs show is the one the project's settings use.""" + +import ast +import importlib +import re +import sys +from collections.abc import Iterator +from contextlib import contextmanager +from pathlib import Path +from typing import Any + +import pytest +from retired import REPO_ROOT, shown_pages + +BASE = REPO_ROOT / "backend" / "src" / "infrastructure" / "config" / "base.py" +SETTINGS_PAGE = REPO_ROOT / "docs" / "user-guide" / "configuration" / "settings-classes.md" +BASE_IMPORTS = {"from src.infrastructure.config.base import EnvSettings"} +FENCED_PYTHON = re.compile(r"^\s*```python\n(.*?)^\s*```", re.M | re.S) + + +def _python_blocks() -> list[tuple[str, str]]: + return [(name, block) for name, text in shown_pages() for block in FENCED_PYTHON.findall(text)] + + +def test_the_pages_show_settings_classes(): + """The rules below have code to read.""" + assert any("EnvSettings" in block for _, block in _python_blocks()) + + +def test_no_block_reads_a_setting_through_the_import_time_loader(): + found = [name for name, block in _python_blocks() if re.search(r"=\s*config\(\s*[\"']", block)] + + assert found == [] + + +def test_no_block_derives_a_settings_group_from_basesettings_directly(): + found = [name for name, block in _python_blocks() if re.search(r"^\s*class \w+\(BaseSettings\):", block, re.M)] + + assert found == [] + + +def test_the_base_the_page_names_is_where_it_says(): + defined = {node.name for node in ast.parse(BASE.read_text()).body if isinstance(node, ast.ClassDef)} + + assert "`EnvSettings` in `src/infrastructure/config/base.py`" in SETTINGS_PAGE.read_text() + assert "EnvSettings" in defined + + +@contextmanager +def _backend_importable() -> Iterator[None]: + sys.path.insert(0, str(REPO_ROOT / "backend")) + try: + yield + finally: + sys.path.remove(str(REPO_ROOT / "backend")) + + +def _base() -> Any: + """`src.infrastructure.config.base`, imported from the backend.""" + with _backend_importable(): + return importlib.import_module("src.infrastructure.config.base") + + +def _section(heading: str) -> str: + text = SETTINGS_PAGE.read_text() + assert heading in text, heading + + return text.split(heading, 1)[1].split("\n## ", 1)[0] + + +def test_the_page_s_own_example_reads_a_value_set_after_it_is_defined(monkeypatch: pytest.MonkeyPatch): + block = FENCED_PYTHON.findall(_section("### Basic Custom Group"))[0] + example = block.split("\nclass Settings(", 1)[0] + scope: dict[str, Any] = {} + with _backend_importable(): + exec(compile(example, "settings-classes.md", "exec"), scope) + + assert "from src.infrastructure.config.base import EnvSettings" in example + assert scope["StorageSettings"].__mro__[1] is _base().EnvSettings + + monkeypatch.setenv("STORAGE_BACKEND", "s3") + + assert scope["StorageSettings"]().STORAGE_BACKEND == "s3" + + +def test_the_validator_the_page_shows_is_the_one_the_database_settings_use(): + anatomy = _section("## Anatomy of a Settings Group") + database = next( + node for node in ast.parse(BASE.read_text()).body if isinstance(node, ast.ClassDef) and node.name == "DatabaseSettings" + ) + before = [ + method.name + for method in database.body + if isinstance(method, ast.FunctionDef) + and any("model_validator(mode='before')" in ast.unparse(decorator) for decorator in method.decorator_list) + ] + + assert before == ["_tables_follow_the_environment"] + assert '@model_validator(mode="before")' in anatomy and "def _tables_follow_the_environment" in anatomy + + +def test_the_file_reads_the_way_the_page_says(monkeypatch: pytest.MonkeyPatch, tmp_path: Path): + key_points = _section("## Anatomy of a Settings Group") + stored = tmp_path / ".env" + stored.write_text("APP_NAME=ab${HOME}cd # kept\n") + monkeypatch.delenv("APP_NAME", raising=False) + + assert "no `${...}` expansion" in key_points and "a `#` is part of the value" in key_points + assert _base().AppSettings(_env_file=stored).APP_NAME == "ab${HOME}cd # kept" + + +def test_every_block_that_imports_the_base_takes_it_from_where_the_mixins_do(): + imports = [line.strip() for _, block in _python_blocks() for line in block.splitlines() if "import EnvSettings" in line] + + assert imports + assert [line for line in imports if line.split("#", 1)[0].strip() not in BASE_IMPORTS] == [] + + +def test_a_flag_and_a_number_read_the_way_the_page_says(monkeypatch: pytest.MonkeyPatch): + key_points = _section("## Anatomy of a Settings Group") + + class Probe(_base().EnvSettings): # type: ignore[misc,name-defined] + DOC_FLAG: bool = False + DOC_COUNT: int = 0 + + assert "`true`, `false`, `1` or `0`" in key_points and "`int()`" in key_points + for name, written in (("DOC_FLAG", "yes"), ("DOC_COUNT", "1.0")): + monkeypatch.setenv(name, written) + with pytest.raises(ValueError): + Probe() + monkeypatch.delenv(name) diff --git a/blueprint/tests/test_fastro.py b/blueprint/tests/test_fastro.py new file mode 100644 index 00000000..e6e5ec34 --- /dev/null +++ b/blueprint/tests/test_fastro.py @@ -0,0 +1,23 @@ +"""What the fastro the repository root installs gives the people who work on the blueprint.""" + +import tomllib +from pathlib import Path + +from conftest import FastroRunner + +REPO_ROOT = Path(__file__).resolve().parents[2] + + +def test_plain_sync_regenerates_what_the_check_compares(tracked_tree: Path, fastro: FastroRunner): + """CONTRIBUTING.md sends a failed `fastro sync --check` to `fastro sync`.""" + tree = tracked_tree + wiring = tree / tomllib.loads((tree / "blueprint.toml").read_text())["wiring"][0]["path"] + generated = wiring.read_text() + wiring.write_text(generated + "\nedited = True\n") + + assert fastro("sync", "--check", cwd=tree).returncode == 1 + + synced = fastro("sync", cwd=tree) + + assert synced.returncode == 0, synced.stderr + assert fastro("sync", "--check", cwd=tree).returncode == 0 diff --git a/blueprint/tests/test_fastro_page.py b/blueprint/tests/test_fastro_page.py new file mode 100644 index 00000000..866a0672 --- /dev/null +++ b/blueprint/tests/test_fastro_page.py @@ -0,0 +1,424 @@ +"""What the fastro page states about fastro's commands and the compose files they write. + +The files are rendered through `fastro make deploy ` in this repository, from the catalog's +`[generators.deploy]`, so a template fastro doesn't see because git doesn't track it is missing here. +""" + +import hashlib +import importlib.util +import re +import subprocess +import sys +import tomllib +from pathlib import Path +from typing import Any + +import click +import pytest +import typer.main +import yaml +from fastro.cli import app +from jinja2 import Environment, FileSystemLoader, StrictUndefined +from retired import OLD_COMMAND + +REPO_ROOT = Path(__file__).resolve().parents[2] +PAGE = REPO_ROOT / "docs" / "user-guide" / "fastro.md" +PRODUCTION = REPO_ROOT / "docs" / "user-guide" / "production.md" +CATALOG = tomllib.loads((REPO_ROOT / "blueprint.toml").read_text()) +GENERATOR = CATALOG["generators"]["deploy"] +MODES = GENERATOR["modes"] + +FASTRO = typer.main.get_command(app) +MAKE_DEPLOY = "## Writing the compose files: `fastro make deploy`" +ENV = "## Preparing the environment: `fastro env`" +PROJECT_TOML = 'features = []\nblueprint = { name = "fastapi-boilerplate", version = "0.20.0" }\n\n[project]\nname = "my-app"\n' + + +def _fastro(*args: str, cwd: Path = REPO_ROOT) -> subprocess.CompletedProcess[str]: + return subprocess.run( + [sys.executable, "-m", "fastro", *args], cwd=cwd, capture_output=True, text=True, stdin=subprocess.DEVNULL + ) + + +def _made(mode: str, out: Path, *flags: str) -> dict[str, str]: + """What `fastro make deploy ` writes into ``out``, by path.""" + run = _fastro("make", "deploy", mode, "--output-dir", str(out), "--force", *flags) + assert run.returncode == 0, run.stdout + run.stderr + + return {path.relative_to(out).as_posix(): path.read_text() for path in sorted(out.rglob("*")) if path.is_file()} + + +def _compose(mode: str, out: Path, *flags: str) -> dict[str, Any]: + return dict(yaml.safe_load(_made(mode, out, *flags)["docker-compose.yml"])) + + +def _command(*words: str) -> click.Command: + command: click.Command = FASTRO + for word in words: + assert isinstance(command, click.Group) + command = command.commands[word] + + return command + + +def _section(heading: str) -> str: + text = PAGE.read_text() + assert heading in text, heading + + return " ".join(text.split(heading, 1)[1].split("\n## ", 1)[0].split()) + + +def _rows() -> list[list[str]]: + """The body rows of the tables under `fastro make deploy`, as their cells.""" + text = PAGE.read_text().split(MAKE_DEPLOY, 1)[1].split("\n## ", 1)[0] + rows = [line for line in text.splitlines() if line.startswith("|") and not re.fullmatch(r"\|[-| ]+\|", line)] + headers = ("| Mode |", "| Option |") + + return [[cell.strip() for cell in row.strip("|").split("|")] for row in rows if not row.startswith(headers)] + + +def _ticked(cell: str) -> list[str]: + return re.findall(r"`([^`]+)`", cell) + + +def _mode_rows() -> dict[str, list[str]]: + return {_ticked(row[0])[0]: row for row in _rows() if not row[0].startswith("`-")} + + +def _option_rows() -> dict[str, list[str]]: + return {_ticked(row[0])[0]: row for row in _rows() if row[0].startswith("`-")} + + +def _help_flags() -> list[list[str]]: + """The flags of each option `fastro make deploy --help` lists, one option per entry.""" + run = _fastro("make", "deploy", "--help") + assert run.returncode == 0, run.stdout + run.stderr + options = run.stdout.split("Options:", 1)[1].splitlines() + + return [re.findall(r"--?[a-z][a-z-]*", line.split(" ")[1]) for line in options if line.startswith(" -")] + + +def test_the_page_names_the_modes_the_catalog_declares(): + assert sorted(_mode_rows()) == sorted(MODES) + + +@pytest.mark.parametrize("mode", MODES) +def test_each_mode_writes_the_files_and_the_stack_its_row_names(mode: str, tmp_path: Path): + row = _mode_rows()[mode] + written = _made(mode, tmp_path) + services = yaml.safe_load(written["docker-compose.yml"])["services"] + stage = re.search(r"`(\w+)` stage", row[1]) + port = re.search(r"\bport (\d+)\b", row[1]) + published = services.get("nginx", {}).get("ports", []) + + assert sorted(written) == sorted(_ticked(row[2])) + assert stage, row + assert services["api"]["build"]["target"] == stage[1] + assert ("`migrate`" in row[1]) == ("migrate" in services) + assert ("Postgres" in row[1]) == ("postgres" in services) + assert ("Redis" in row[1]) == ("redis" in services) + assert (f"{port[1]}:{port[1]}" in published) if port else not published + + +@pytest.mark.parametrize("mode", MODES) +def test_each_file_names_the_command_that_wrote_it_and_the_project_is_the_slug(mode: str, tmp_path: Path): + written = _made(mode, tmp_path) + project = tomllib.loads((REPO_ROOT / "fastro.toml").read_text())["project"]["name"] + section = _section(MAKE_DEPLOY) + headers = {text.splitlines()[0] for text in written.values()} + + assert headers == {f"# Generated by `fastro make deploy {mode}`."} + assert yaml.safe_load(written["docker-compose.yml"])["name"] == project.lower() == "fastapi-boilerplate" + assert "a header naming the command that wrote it" in section + assert "named after the project's slug, `fastapi-boilerplate` here" in section + + +def _rendered_directly(mode: str, services: list[str]) -> dict[str, Any]: + """A mode's compose file rendered with jinja under fastro's settings, for a project named "My App" whose + selection brings ``services``. Only the names the templates read are in the context.""" + environment = Environment( + loader=FileSystemLoader(REPO_ROOT / GENERATOR["templates"]), keep_trailing_newline=True, undefined=StrictUndefined + ) + context = { + "project": {"name": "My App", "slug": "my-app"}, + "services": services, + "params": {name: param["default"] for name, param in GENERATOR["params"].items()}, + } + + return dict(yaml.safe_load(environment.get_template(f"{mode}/docker-compose.yml.j2").render(context))) + + +@pytest.mark.parametrize("mode", MODES) +def test_the_compose_project_is_the_slug_not_the_name(mode: str): + assert _rendered_directly(mode, [])["name"] == "my-app" + + +LEGACY = { + "local/docker-compose.yml": "0b8f3746c257de3fb36564f72e7786ff2863b00e636c40dde6cd368c7d94b706", + "prod/docker-compose.yml": "b315b3bfa74e2d7ffb70890bb4d44766bbc176e85412238871cbdefb5520a854", + "nginx/docker-compose.yml": "7f7f158f9c83d01279f6c8ce67e0f798236d07cbf9a0eda2317c5bf007471afa", + "nginx/nginx/default.conf": "dec9a1f2b30190a783d34d1b9336de8a0666b603fb453ae33acce7f75952f161", +} +"""The sha256 of what fastro a07bbc1's legacy deploy command wrote for each mode, with the default params, past +the header line and with the project name written as ``{project}``.""" + + +def _past_the_header_and_name(text: str) -> str: + return re.sub(r"(?i)fastapi-boilerplate", "{project}", "".join(text.splitlines(keepends=True)[1:])) + + +@pytest.mark.parametrize("mode", MODES) +def test_apart_from_the_header_and_name_the_files_are_what_the_legacy_command_wrote(mode: str, tmp_path: Path): + written = _made(mode, tmp_path) + digests = { + f"{mode}/{path}": hashlib.sha256(_past_the_header_and_name(text).encode()).hexdigest() for path, text in written.items() + } + + assert digests == {path: digest for path, digest in LEGACY.items() if path.startswith(f"{mode}/")} + assert "Apart from the header and the project name, the files are byte for byte" in _section(MAKE_DEPLOY) + + +@pytest.mark.parametrize("mode", MODES) +def test_a_project_with_taskiq_gets_a_worker_and_one_scheduler_in_every_mode(mode: str, tmp_path: Path): + with_taskiq = _compose(mode, tmp_path)["services"] + + assert "taskiq feature also gets a `worker` and one `scheduler` in every mode" in _section(MAKE_DEPLOY) + assert sorted(CATALOG["features"]["taskiq"]["services"]) == ["scheduler", "worker"] + assert {"worker", "scheduler"} <= set(with_taskiq) + assert with_taskiq["scheduler"].get("deploy", {}).get("replicas", 1) == 1 + assert not {"worker", "scheduler"} & set(_rendered_directly(mode, [])["services"]) + + +def test_the_options_and_their_defaults_are_the_ones_fastro_has(): + stated = _option_rows() + listed = {flags[-1] if flags[-1].startswith("--") else flags[0]: flags for flags in _help_flags()} + defaults = {f"--{name.replace('_', '-')}": param["default"] for name, param in GENERATOR["params"].items()} + + assert sorted(stated) == sorted(listed) + for flag, row in stated.items(): + assert sorted(_ticked(row[0])) == sorted(listed[flag]), flag + if flag in defaults: + assert row[1] == f"`{defaults[flag]}`", flag + elif flag == "--output-dir": + assert row[1] == "the repository root" + else: + assert row[1] == "", flag + + +def test_the_subnet_limits_are_the_catalogs(): + limits = GENERATOR["params"]["internal_subnet"]["max_prefix"] + + assert f"`/{limits['v4']}` or smaller for IPv4, and `/{limits['v6']}` or smaller for IPv6" in _section(MAKE_DEPLOY) + assert f"`/{limits['v4']}` (IPv4) or `/{limits['v6']}` (IPv6)" in PRODUCTION.read_text() + + +@pytest.mark.parametrize("mode", MODES) +@pytest.mark.parametrize( + ("subnet", "refused"), + [ + ("172.31.240.1/24", True), + ("*", True), + ("10.0.0.0/7", True), + ("fd00::/47", True), + ("10.0.0.0/8", False), + ("fd00::/48", False), + ], +) +def test_every_mode_checks_the_subnet_and_refuses_what_the_pages_name(mode: str, subnet: str, refused: bool, tmp_path: Path): + run = _fastro("make", "deploy", mode, "--internal-subnet", subnet, "--output-dir", str(tmp_path), "--dry-run") + section = _section(MAKE_DEPLOY) + + assert run.returncode == (2 if refused else 0), run.stdout + run.stderr + assert "Every value is checked in every mode" in section and "exits 2 before any file is written" in section + assert "`local` and `prod` always use the default network" in section + + +def test_the_nginx_subnet_is_the_network_and_the_peers_uvicorn_trusts(tmp_path: Path): + subnet = "10.89.0.0/24" + compose = _compose("nginx", tmp_path, "--internal-subnet", subnet) + networks = [config["subnet"] for network in compose["networks"].values() for config in network["ipam"]["config"]] + environment = compose["services"]["api"]["environment"] + trusted = ( + environment["FORWARDED_ALLOW_IPS"] + if isinstance(environment, dict) + else dict(entry.split("=", 1) for entry in environment)["FORWARDED_ALLOW_IPS"] + ) + section = _section(MAKE_DEPLOY) + + assert networks == [subnet] + assert trusted == subnet + assert "`FORWARDED_ALLOW_IPS`" in section and "compose network's subnet" in section + + +def _modes_named(cell: str) -> set[str]: + named = re.search(r"for ((?:`\w+`(?: and )?)+)$", cell) + + return set(_ticked(named[1])) if named else set(MODES) + + +@pytest.mark.parametrize("mode", MODES) +def test_the_port_and_the_workers_reach_the_modes_their_rows_name(mode: str, tmp_path: Path): + rows = _option_rows() + written = _made(mode, tmp_path, "--api-port", "9123", "--workers", "7") + api = yaml.safe_load(written["docker-compose.yml"])["services"]["api"] + environment = api.get("environment", {}) + + if mode in _modes_named(rows["--api-port"][2]): + assert api["ports"] == ["9123:8000"] + else: + assert "ports" not in api + assert "9123" not in "".join(written.values()) + if mode in _modes_named(rows["--workers"][2]): + assert environment["WORKERS"] == "7" + else: + assert "WORKERS" not in environment + + +def test_make_prints_a_line_per_file_and_keeps_a_changed_one_without_a_terminal(tmp_path: Path): + target = tmp_path / "docker-compose.yml" + shown = str(target) + section = _section(MAKE_DEPLOY) + + first = _fastro("make", "deploy", "local", "--output-dir", str(tmp_path)) + again = _fastro("make", "deploy", "local", "--output-dir", str(tmp_path)) + target.write_text("edited by hand\n") + kept = _fastro("make", "deploy", "local", "--output-dir", str(tmp_path)) + left = target.read_text() + dry = _fastro("make", "deploy", "local", "--output-dir", str(tmp_path), "--dry-run") + generated = _made("local", tmp_path / "fresh")["docker-compose.yml"] + size = len(generated.encode()) + replaced = {} + for flag in ("--force", "-f", "--yes", "-y"): + target.write_text("edited by hand\n") + replaced[flag] = (_fastro("make", "deploy", "local", "--output-dir", str(tmp_path), flag).stdout, target.read_text()) + + assert (first.returncode, first.stdout.splitlines()) == (0, [f"wrote {shown}"]) + assert (again.returncode, again.stdout.splitlines()) == (0, [f"unchanged {shown}"]) + assert kept.returncode == 0 and kept.stdout.startswith(f"kept {shown}") + assert left == "edited by hand\n" + assert dry.stdout.startswith(f"would write {shown} ({size} bytes)") + assert replaced == dict.fromkeys(("--force", "-f", "--yes", "-y"), (f"wrote {shown}\n", generated)) + assert "or with `--force` or `--yes`" in section + assert all(f"`{line} X`" in section for line in ("wrote", "unchanged", "kept")) + assert "`would write X (N bytes)`" in section + assert "with no terminal to ask on, it is kept and named, and the exit is still 0" in section + + +@pytest.mark.parametrize("command", [["fastro", "make", "deploy", "local"], [OLD_COMMAND, "deploy", "generate", "local"]]) +def test_make_in_a_project_exits_2(command: list[str], tmp_path: Path): + """fastro's own command in a project fastro created; the old one in a project made before fastro, with no + ``fastro.toml``.""" + if command[0] == "fastro": + (tmp_path / "fastro.toml").write_text(PROJECT_TOML) + else: + (tmp_path / "backend").mkdir() + run = subprocess.run( + [str(Path(sys.executable).parent / command[0]), *command[1:]], cwd=tmp_path, capture_output=True, text=True + ) + section = _section(MAKE_DEPLOY) + + assert run.returncode == 2, run.stdout + run.stderr + assert not (tmp_path / "docker-compose.yml").exists() + assert "In a project fastro created it exits 2" in section + assert f"`{OLD_COMMAND} deploy generate` exits 2 too, in a project made before fastro" in section + + +def test_the_secret_size_is_the_one_fastro_takes(): + size = next(param for param in _command("env", "secret").params if param.name == "bytes_") + assert isinstance(size.type, click.IntRange) + section = _section(ENV) + + assert f"from `{size.type.min}` to `{size.type.max}`, `{size.default}` by default" in section + assert f"so {2 * size.default} hex characters" in section + + +def test_the_built_in_secret_prints_a_token_outside_a_project(tmp_path: Path): + run = _fastro("env", "secret", cwd=tmp_path) + + assert run.returncode == 0 + assert re.fullmatch(r"[0-9a-f]{64}\n", run.stdout) + assert "It is built in, so it prints a token anywhere" in _section(ENV) + + +@pytest.mark.parametrize("project", [False, True]) +def test_validate_outside_this_repository_exits_2_saying_why(project: bool, tmp_path: Path): + if project: + (tmp_path / "fastro.toml").write_text(PROJECT_TOML) + run = _fastro("env", "validate", cwd=tmp_path) + section = _section(ENV) + + assert run.returncode == 2 + assert run.stderr.strip() + assert "Anywhere else it exits 2 and says why" in section + assert "outside a project, and in a project fastro created, for now" in section + + +def test_every_command_the_page_heads_a_section_with_is_one_fastro_has(tmp_path: Path): + headed = re.findall(r"^#+ .*?`fastro ([a-z ]+)`", PAGE.read_text(), re.M) + + assert headed + for words in headed: + run = _fastro(*words.split(), "--help", cwd=tmp_path) + assert run.returncode == 0, (words, run.stdout + run.stderr) + + +def test_the_env_commands_run_the_scripts_the_page_names(): + section = _section(ENV) + + for words in ("env secret", "env validate"): + module = CATALOG["commands"][words]["module"] + assert f"`{module}`" in section + assert (REPO_ROOT / "backend" / f"{module.replace('.', '/')}.py").is_file() + + +@pytest.mark.parametrize(("found", "code"), [((["critical"], ["warning"]), 1), (([], ["warning"]), 0)]) +def test_validate_exits_and_reports_the_way_the_page_says( + found: tuple[list[str], list[str]], code: int, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +): + monkeypatch.syspath_prepend(str(REPO_ROOT / "backend")) + spec = importlib.util.spec_from_file_location("validate_env", REPO_ROOT / "backend" / "scripts" / "validate_env.py") + assert spec and spec.loader + script = importlib.util.module_from_spec(spec) + spec.loader.exec_module(script) + monkeypatch.setattr(script, "audit", lambda: found) + + exited = script.main() + printed = capsys.readouterr().out + section = _section(ENV) + + assert exited == code + assert "exits 1 when anything is critical and 0 otherwise" in section + assert "critical findings first" in section + if found[0]: + assert printed.index("Critical") < printed.index("Warnings") + + +BLUEPRINT_REPO = "## In the blueprint repository: `fastro sync` and `fastro blueprint`" + + +def test_the_wiring_the_page_names_is_where_sync_writes(): + named = re.search(r"`\[\[wiring\]\]` tables list, most of them under `([^`]+)`", _section(BLUEPRINT_REPO)) + assert named + paths = [wiring["path"] for wiring in CATALOG["wiring"]] + + assert (REPO_ROOT / named[1]).is_dir() + assert 2 * sum(path.startswith(named[1]) for path in paths) > len(paths) + + +def test_the_root_dev_group_installs_fastro(): + root = tomllib.loads((REPO_ROOT / "pyproject.toml").read_text()) + dev = [re.split(r"[\s<>=!~\[;@]", specifier, maxsplit=1)[0] for specifier in root["dependency-groups"]["dev"]] + + assert "fastro" in dev + assert "The root dev group installs it" in _section("# Generating and updating projects with fastro") + + +def test_the_changelog_says_what_make_deploy_changed(tmp_path: Path): + unreleased = (REPO_ROOT / "docs" / "changelog.md").read_text().split("## Unreleased", 1)[1].split("\n## ", 1)[0] + heading = "**`fastro make deploy` renders this repository's `[generators.deploy]`.**" + entry = " ".join(unreleased.split(heading, 1)[1].split("\n- **", 1)[0].split()) + name = _compose("local", tmp_path)["name"] + + assert f"the project's slug, `{name}`" in entry + assert "`fastro make deploy `" in entry + assert "a bad one exits 2" in entry and "`fastro env validate` exits 2" in entry diff --git a/blueprint/tests/test_observability_recipe.py b/blueprint/tests/test_observability_recipe.py new file mode 100644 index 00000000..1c2a28e1 --- /dev/null +++ b/blueprint/tests/test_observability_recipe.py @@ -0,0 +1,183 @@ +"""The observability guide's tracing recipe, followed in a copy of the repository.""" + +import ast +import re +import tomllib +from pathlib import Path + +import pytest +from conftest import FastroRunner + +REPO_ROOT = Path(__file__).resolve().parents[2] +RECIPE = REPO_ROOT / "docs" / "user-guide" / "observability.md" + + +def _blocks(language: str) -> list[str]: + return [str(block) for block in re.findall(rf"^```{language}\n(.*?)^```$", RECIPE.read_text(), re.M | re.S)] + + +def _block(language: str) -> str: + blocks = _blocks(language) + assert len(blocks) == 1, f"expected one {language} block in the recipe, found {len(blocks)}" + + return blocks[0] + + +def _python_block_defining(name: str) -> str: + for block in _blocks("python"): + if any(isinstance(node, ast.FunctionDef) and node.name == name for node in ast.parse(block).body): + return block + raise AssertionError(f"no python block in the recipe defines {name}()") + + +def _installers_slot() -> tuple[str, str]: + """The wiring file whose slot holds the installers point, and that slot's name.""" + catalog = tomllib.loads((REPO_ROOT / "blueprint.toml").read_text()) + return next( + (wiring["path"], slot["name"]) + for wiring in catalog["wiring"] + for slot in wiring.get("slots", []) + if slot.get("point") == "installers" + ) + + +def test_the_recipe_registers_its_installer_through_fastro_toml_and_a_sync(tracked_tree: Path, fastro: FastroRunner): + project = tracked_tree + wiring_file, slot = _installers_slot() + registration = _block("toml") + reference = re.search(r'installers = \["([\w.]+):(\w+) as (\w+)"\]', registration) + assert reference, registration + module, function, alias = reference.groups() + (project / "backend" / f"{module.replace('.', '/')}.py").write_text(_python_block_defining(function)) + with (project / "fastro.toml").open("a") as handle: + handle.write(f"\n{registration}") + wiring_path = project / wiring_file + + synced = fastro("sync", cwd=project) + wiring = wiring_path.read_text() + + assert synced.returncode == 0, synced.stdout + synced.stderr + assert f"from ..{module.removeprefix('src.')} import {function} as {alias}" in wiring + installers = re.search(rf"^{slot}\b.*?= \(\n(.*?)^\)", wiring, re.M | re.S) + assert installers, wiring + assert installers[1].splitlines()[-1].strip() == f"{alias},", installers[1] + recipe = RECIPE.read_text() + assert {f"`{alias}`", f"`{slot}`", f"`{wiring_file.removeprefix('backend/')}`", "`fastro sync --check`"} <= set( + re.findall(r"`[^`\n]+`", recipe) + ) + assert re.search(rf"^\| [^|]*\| `{re.escape(wiring_file)}` \|$", recipe, re.M) + assert re.search(r"^\| [^|]*\| `fastro.toml`, under `\[app.contributes\]` \|$", recipe, re.M) + assert fastro("sync", "--check", cwd=project).returncode == 0 + assert any("fastro sync" in block.splitlines() for block in _blocks("bash")) + + wiring_path.write_text(wiring.replace(f" {alias},\n", "")) + assert fastro("sync", "--check", cwd=project).returncode == 1 + assert fastro("sync", cwd=project).returncode == 0 + assert wiring_path.read_text() == wiring + + +def test_the_registered_module_is_the_one_the_recipe_writes(): + registration = _block("toml") + module = re.search(r'installers = \["([\w.]+):', registration) + assert module, registration + path = f"backend/{module[1].replace('.', '/')}.py" + + assert f"`{path.removeprefix('backend/')}`" in RECIPE.read_text() + assert re.search(rf'^paths = \["{re.escape(path)}"\]$', registration, re.M), registration + + +def test_the_installer_configures_tracing_before_it_instruments_the_app(): + """Registered as an installer, `install` is all the app calls, so it has to configure Logfire itself.""" + module = ast.parse(_python_block_defining("install")) + install = next(node for node in module.body if isinstance(node, ast.FunctionDef) and node.name == "install") + calls = [ast.unparse(node.func) for node in ast.walk(install) if isinstance(node, ast.Call)] + + assert any(isinstance(node, ast.FunctionDef) and node.name == "configure_tracing" for node in module.body) + assert calls.index("configure_tracing") < calls.index("logfire.instrument_fastapi"), calls + + +@pytest.mark.parametrize("arguments", [("sync",), ("sync", "--check")]) +def test_the_pinned_fastro_cannot_sync_a_project_yet(tracked_tree: Path, fastro: FastroRunner, arguments: tuple[str, ...]): + """The recipe's hand-edit fallback is there only while this holds; when it fails, delete that sentence.""" + config = tracked_tree / "fastro.toml" + config.write_text(re.sub(r"^source = true\n", "", config.read_text(), flags=re.M)) + + synced = fastro(*arguments, cwd=tracked_tree) + + assert f"`fastro {' '.join(arguments)}`" in RECIPE.read_text() + assert synced.returncode != 0 + assert "fastro sync in a project isn't here yet" in synced.stdout + synced.stderr, ( + "the pinned fastro syncs projects now: drop the main.py fallback sentence from observability.md" + ) + + +def test_the_hand_edit_fallback_names_the_lines_main_py_has_and_the_recipe_registers(tracked_tree: Path): + recipe = RECIPE.read_text() + reference = re.search(r'installers = \["([\w.]+):(\w+) as (\w+)"\]', _block("toml")) + assert reference, recipe + module, function, alias = reference.groups() + importing = f"from ..{module.removeprefix('src.')} import {function} as {alias}" + passed, replaced = re.findall(r"`(installers=[^`]+,)`", recipe) + main = tracked_tree / "backend" / "src" / "interfaces" / "main.py" + source = main.read_text() + + assert f"`{importing}`" in recipe + assert f"`{main.relative_to(tracked_tree / 'backend')}`" in recipe + assert "`fastro sync`" in recipe and "project-mode sync" in recipe + assert source.count(f" {passed}\n") == 1, passed + assert replaced == f"installers=(*INSTALLERS, {alias}),", replaced + edited = f"{importing}\n{source.replace(f' {passed}', f' {replaced}')}" + ast.parse(edited) + + +def test_the_worker_note_names_the_worker_module_and_a_call_configure_tracing_takes(): + recipe = RECIPE.read_text() + command = re.search(r"`taskiq worker (src(?:\.\w+)+):(\w+)`", recipe) + assert command, recipe + worker = REPO_ROOT / "backend" / f"{command[1].replace('.', '/')}.py" + tree = ast.parse(worker.read_text()) + bound = { + target.id + for node in tree.body + if isinstance(node, ast.Assign) + for target in node.targets + if isinstance(target, ast.Name) + } + bound |= {alias.asname or alias.name for node in tree.body if isinstance(node, ast.ImportFrom) for alias in node.names} + imported = {node.module for node in ast.walk(tree) if isinstance(node, ast.ImportFrom)} + imported |= {alias.name for node in ast.walk(tree) if isinstance(node, ast.Import) for alias in node.names} + call = re.search(r"`(configure_tracing\([^`]*\))`", recipe) + assert call, recipe + configure = next( + node + for node in ast.parse(_python_block_defining("configure_tracing")).body + if isinstance(node, ast.FunctionDef) and node.name == "configure_tracing" + ) + given = ast.parse(call[1], mode="eval").body + assert isinstance(given, ast.Call) + + assert command[2] in bound + assert f"`{worker.relative_to(REPO_ROOT / 'backend')}`" in recipe + assert not any(module and module.endswith("interfaces.main") for module in imported) + assert {keyword.arg for keyword in given.keywords} <= {argument.arg for argument in configure.args.args} + assert given.keywords + defaults = dict( + zip([argument.arg for argument in configure.args.args][-len(configure.args.defaults) :], configure.args.defaults) + ) + for keyword in given.keywords: + assert ast.literal_eval(keyword.value) != ast.literal_eval(defaults[keyword.arg]), keyword.arg + + +def test_the_feature_section_names_the_tables_a_feature_is_declared_with(): + """A project's own code is `[app]`; a feature lives in the blueprint's catalog, with these tables.""" + section = RECIPE.read_text().split("## If you turn this into a feature", 1)[1].split("\n## ", 1)[0] + catalog = tomllib.loads((REPO_ROOT / "blueprint.toml").read_text()) + feature = re.search(r"`\[features\.(\w+)\]`", section) + assert feature, section + name = feature[1] + + assert "`blueprint.toml`" in section and "`[app]`" in section + assert "`paths`" in section and f"`[features.{name}.contributes]`" in section + assert any( + "paths" in declared and "installers" in declared.get("contributes", {}) for declared in catalog["features"].values() + ) diff --git a/blueprint/tests/test_overlay.py b/blueprint/tests/test_overlay.py new file mode 100644 index 00000000..66a5a7f9 --- /dev/null +++ b/blueprint/tests/test_overlay.py @@ -0,0 +1,317 @@ +"""What the overlay puts in a project, and what it is allowed to say. + +Spec 2.1: the overlay's tree is copied into projects, and a `*.j2` file is rendered with the +spec 6.2 context and loses the suffix. So every path here lands in a project beside the files +core copies, and every name a template reads has to be one the tool passes. +""" + +import re +import tomllib +from pathlib import Path +from typing import Any + +import pytest +import yaml +from jinja2 import Environment, FileSystemLoader, StrictUndefined, meta + +REPO_ROOT = Path(__file__).resolve().parents[2] + +CATALOG = tomllib.loads((REPO_ROOT / "blueprint.toml").read_text()) + +OVERLAY = REPO_ROOT / CATALOG["blueprint"]["overlay"] + +CONTEXT_NAMES = {"project", "blueprint", "fastro", "features", "options", "services", "params", "has"} +"""Spec 6.2, in full. A template reaching for anything else fails under `StrictUndefined`.""" + +BUILT_IN_COMMANDS = {"add", "check", "eject", "features", "init", "make", "new", "remove", "sync", "update"} +"""fastro's own verbs, which take arguments of their own: `fastro add admin` names a feature, not +a command. Anything else after `fastro` has to be a command the catalog declares, and +`make ` has to name one it has.""" + +A_FASTRO_COMMAND = re.compile(r"\bfastro(?:@(?:\{\{[^}]*\}\}|[^\s{]+))? ((?:[a-z][a-z0-9-]*)(?: [a-z][a-z0-9-]*)?)") +"""A command, however it is run: `fastro sync`, or `uvx fastro@{{ fastro.version }} sync`, or +`uvx fastro@0.1.0 sync`. Without the pin in the pattern every pinned command goes unread, and +with a pin that takes any non-space text, the template's own `{{ fastro.version }}` reads as one, leaving `fastro` as +the command.""" + +A_CODE_SPAN = re.compile(r"`([^`\n]+)`|```[a-z]*\n(.*?)```", re.DOTALL) +"""Only what is written as code is read as a command: prose says "generated by fastro from +blueprint.toml", and `fastro from` is not a command anybody runs. Each span is read on its own, +or two of them in one sentence would read as one command.""" + + +def _context(features: tuple[str, ...] = (), **options: str) -> dict[str, Any]: + """The spec 6.2 context, as the tool builds it for the overlay: no generator params.""" + return { + "project": {"name": "Example App", "slug": "example-app"}, + "blueprint": {"name": CATALOG["blueprint"]["name"], "version": CATALOG["blueprint"]["version"]}, + "fastro": {"version": "0.1.0"}, + "features": list(features), + "options": dict(options), + "services": [], + "params": {}, + "has": lambda name: name in features, + } + + +def _files() -> list[Path]: + return sorted(path for path in OVERLAY.rglob("*") if path.is_file()) + + +def _declared_commands() -> set[str]: + """Every command the catalog declares, the features' own included.""" + words = set(CATALOG.get("commands", {})) + for feature in CATALOG["features"].values(): + words.update(feature.get("commands", {})) + + return words + + +def _landing(path: Path) -> Path: + """Where an overlay file lands in a project: a `*.j2` is rendered and loses the suffix.""" + relative = path.relative_to(OVERLAY) + + return relative.with_suffix("") if relative.suffix == ".j2" else relative + + +def _received() -> set[str]: + """Paths a project receives besides the overlay's: the repository's own files that aren't + withheld, and every `[[wiring]]` path, which the tool writes whether or not this repository + has the file yet.""" + written = {entry["path"] for entry in CATALOG["wiring"]} + + return written | { + path.relative_to(REPO_ROOT).as_posix() + for path in REPO_ROOT.rglob("*") + if path.is_file() and not _withheld(path.relative_to(REPO_ROOT).as_posix()) + } + + +def _withheld(path: str) -> bool: + return any( + path == entry.rstrip("/") or (entry.endswith("/") and path.startswith(entry)) + for entry in CATALOG["blueprint"]["blueprint_only"] + ) + + +def test_the_overlay_is_where_the_catalog_says(): + assert OVERLAY.is_dir() + assert _files(), OVERLAY + + +@pytest.mark.parametrize("path", [str(path.relative_to(OVERLAY)) for path in _files()]) +def test_no_overlay_file_lands_on_a_file_a_project_already_receives(path: str): + """Spec 1.27: two files at one path is refused, and a `[[wiring]]` path counts as taken even + where this repository has no file yet. The overlay's `.gitignore` is the project's, which is + why this repository's own is `blueprint_only`.""" + landing = _landing(OVERLAY / path).as_posix() + + assert landing not in _received(), landing + + +def test_no_two_overlay_files_land_on_one_path(): + """Spec 1.27: `x` and `x.j2` in the overlay would both land on `x`, and nothing says which + of the two a project gets.""" + landings = [_landing(path).as_posix() for path in _files()] + + assert sorted(landings) == sorted(set(landings)) + + +@pytest.mark.parametrize("path", [str(path.relative_to(OVERLAY)) for path in _files() if path.suffix == ".j2"]) +def test_every_template_reads_only_what_the_tool_passes(path: str): + """Spec 6.2: the context is fixed, so a template that asks for anything else renders nothing.""" + loader = FileSystemLoader(OVERLAY) + environment = Environment(loader=loader, undefined=StrictUndefined, keep_trailing_newline=True) + source = loader.get_source(environment, path)[0] + + assert meta.find_undeclared_variables(environment.parse(source)) <= CONTEXT_NAMES + + +@pytest.mark.parametrize("path", [str(path.relative_to(OVERLAY)) for path in _files() if path.suffix == ".j2"]) +def test_every_template_renders_for_a_project_with_no_features(path: str): + """Core only is the harshest selection: every feature's lines have to be behind a condition.""" + environment = Environment(loader=FileSystemLoader(OVERLAY), undefined=StrictUndefined, keep_trailing_newline=True) + + assert environment.get_template(path).render(_context()).strip() + + +@pytest.mark.parametrize("path", [str(path.relative_to(OVERLAY)) for path in _files()]) +def test_every_fastro_command_the_overlay_names_is_one_a_project_has(path: str): + """A project told to run a command its blueprint doesn't declare is a project that can't. + + `fastro make ` is checked against `[generators]` too, which is why this file says + nothing about `make module` yet: that generator arrives with the module scaffold. + """ + spans = [span or fenced for span, fenced in A_CODE_SPAN.findall((OVERLAY / path).read_text())] + declared = _declared_commands() + + for named in (found for span in spans for found in A_FASTRO_COMMAND.findall(span)): + verb, _, rest = named.partition(" ") + if verb == "make" and rest: + assert rest in CATALOG["generators"], named + elif verb in BUILT_IN_COMMANDS: + continue + else: + assert named in declared if rest else verb in declared, named + + +README = "README.md.j2" + +FEATURE_LINES = { + "accounts": "setup_initial_data", + "admin": "/admin", + "taskiq": "taskiq worker", +} +"""What the README writes for a feature, and nothing else writes: a project without the feature +must be told none of it.""" + + +def _rendered(path: str, features: tuple[str, ...]) -> str: + environment = Environment(loader=FileSystemLoader(OVERLAY), undefined=StrictUndefined, keep_trailing_newline=True) + + return environment.get_template(path).render(_context(features)) + + +@pytest.mark.parametrize("features", [(), ("accounts",), tuple(CATALOG["features"])], ids=["core", "accounts", "all"]) +def test_the_readme_tells_a_project_only_what_it_carries(features: tuple[str, ...]): + """Each feature's lines appear exactly where the feature does. A README is the first thing a + reader follows, and a step for something the project hasn't got is a step that fails.""" + rendered = _rendered(README, features) + + for feature, line in FEATURE_LINES.items(): + assert (line in rendered) == (feature in features), feature + + for name in CATALOG["features"]: + if name not in features: + assert not re.search(rf"\b{name}\b", rendered), name + + +def test_the_readme_describes_the_admin_panel_the_example_ships(): + """The README and `.env.example` go to the same project, so one can't say the panel is off + while the other turns it on.""" + example = (REPO_ROOT / CATALOG["blueprint"]["python_root"] / ".env.example").read_text() + rendered = _rendered(README, ("accounts", "admin")) + shipped_off = "\nADMIN_ENABLED=false\n" in example + + assert ("ships switched off" in rendered) == shipped_off + assert ("Set `ADMIN_ENABLED=true`" in rendered) == shipped_off + + +def test_the_readme_says_what_a_project_with_no_features_is(): + """Core only is a real answer, so the file says so rather than leaving the line empty.""" + rendered = _rendered(README, ()) + + assert "Nothing optional is selected" in rendered + assert "Selected:" not in rendered + + +def test_the_readme_names_the_features_a_project_selected(): + rendered = _rendered(README, ("accounts", "admin")) + + assert "Selected: accounts, admin." in rendered + + +@pytest.mark.parametrize("features", [(), ("accounts", "admin")]) +def test_the_readme_names_the_blueprint_a_project_came_from(features: tuple[str, ...]): + """The catalog's `name` is an id; a reader meets the blueprint by its name in full.""" + environment = Environment(loader=FileSystemLoader(OVERLAY), undefined=StrictUndefined) + blueprint = {"name": "a-blueprint-id", "version": "9.8.7"} + rendered = environment.get_template(README).render({**_context(features), "blueprint": blueprint}) + + assert f"the FastAPI-boilerplate blueprint (`{blueprint['name']}` {blueprint['version']})" in " ".join(rendered.split()) + + +def test_the_agents_file_names_the_blueprint_a_project_came_from(): + assert re.search(r"\bFastAPI-boilerplate\b", (OVERLAY / "AGENTS.md").read_text()) + + +@pytest.mark.parametrize("path", [str(path.relative_to(OVERLAY)) for path in _files() if path.suffix == ".j2"]) +def test_every_fastro_command_a_template_writes_runs_the_tool_that_generated_the_project(path: str): + """`uvx fastro@` needs nothing installed first and pins the project to the tool it + was generated with, so a reader never gets a newer tool's behaviour by accident. + + Templates only: `AGENTS.md` is written by hand and has no version to interpolate. In Markdown + the commands are what is written as code; anywhere else every line is run, so the whole file + counts. `fastro.toml` is a file and `fastro.version` a context value, so neither is read as a + command, however a pattern escapes the dot. + """ + text = (OVERLAY / path).read_text() + spans = ( + [span or fenced for span, fenced in A_CODE_SPAN.findall(text)] if _landing(OVERLAY / path).suffix == ".md" else [text] + ) + unpinned = [] + for span in spans: + for found in re.finditer(r"fastro", span): + before, after = span[: found.start()], span[found.end() :] + if after.removeprefix("\\").startswith((".toml", ".version")): + continue + + if not (before.endswith("uvx ") and after.startswith("@{{ fastro.version }}")): + unpinned.append(span.strip()[:60]) + + assert unpinned == [] + + +WORKFLOW = ".github/workflows/ci.yml.j2" + +PRE_COMMIT = ".pre-commit-config.yaml.j2" + +BEFORE_FINISHING = ("ruff check .", "ruff format --check .", "mypy src scripts migrations tests", "pytest") +"""What an agent is told to run before finishing, which is what CI runs: one list, two files.""" + + +@pytest.mark.parametrize("path", [WORKFLOW, PRE_COMMIT]) +def test_the_yaml_a_project_receives_parses(path: str): + """Rendered for the harshest selection, since a conditional that empties a list or leaves a + dangling key is only visible once it is parsed.""" + assert yaml.safe_load(_rendered(path, ())) + + +def test_the_workflow_runs_what_the_agent_file_tells_an_agent_to_run(): + """An agent whose checks are looser than CI's finishes work that CI then rejects.""" + agents = (OVERLAY / "AGENTS.md").read_text() + workflow = _rendered(WORKFLOW, ()) + + for command in BEFORE_FINISHING: + assert command in agents, command + assert command in workflow, command + + +def test_the_workflow_installs_the_project_rather_than_this_workspace(): + """A project has one `pyproject.toml`, under the python root: `--all-packages` and a root + lock are this repository's own shape, and neither is there.""" + workflow = yaml.safe_load(_rendered(WORKFLOW, ())) + steps = workflow["jobs"]["check"]["steps"] + installing = next(step for step in steps if step.get("name") == "Install") + + assert "--project backend" in installing["run"] + assert "--all-packages" not in installing["run"] + assert ( + "backend/uv.lock" in next(step for step in steps if step.get("name") == "Install uv")["with"]["cache-dependency-glob"] + ) + + +def test_every_pre_commit_hook_watches_paths_a_project_has(): + """A `files:` pattern naming `docs/` or `blueprint/` is a hook over nothing: those are the + blueprint's own, and no project receives them.""" + hooks = yaml.safe_load(_rendered(PRE_COMMIT, ())) + watched = [hook["files"] for repo in hooks["repos"] for hook in repo["hooks"] if "files" in hook] + + assert watched + for pattern in watched: + head = re.split(r"[(\[{|?*+\\]", pattern.removeprefix("^"))[0].rstrip("/") + assert head in {"backend", "fastro.toml", "fastro\\.toml", ""} or not _withheld(head), pattern + + +def test_the_claude_file_points_at_the_agents_file(): + """One file for both, so instructions never drift: Claude Code reads `@AGENTS.md` as an import.""" + assert (OVERLAY / "CLAUDE.md").read_text().strip() == "@AGENTS.md" + + +def test_the_agents_file_tells_an_agent_what_it_must_not_edit(): + """The wiring is generated, and an agent editing it loses its work on the next sync.""" + text = (OVERLAY / "AGENTS.md").read_text() + + assert "src/wiring/" in text + assert "fastro sync" in text + assert "make module" not in text, "that generator does not exist yet" diff --git a/blueprint/tests/test_pre_commit.py b/blueprint/tests/test_pre_commit.py new file mode 100644 index 00000000..46200ce2 --- /dev/null +++ b/blueprint/tests/test_pre_commit.py @@ -0,0 +1,38 @@ +"""The pre-commit hooks the development guide describes, run the way a contributor runs them.""" + +import os +import re +import subprocess +import sys +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parents[2] + + +def _unit_test_hook() -> tuple[str, list[str]]: + """The directory the unit test hook runs in, and the arguments it gives pytest.""" + config = (REPO_ROOT / ".pre-commit-config.yaml").read_text() + entry = r" +entry: bash -c 'cd (\S+) && uv run --no-sync pytest(.*)'\n" + found = re.search(rf"- id: unit_test\n(?: +[\w-]+:.*\n)*?{entry}", config) + assert found, config + + return found[1], found[2].split() + + +def test_the_unit_test_hook_passes_without_docker(tmp_path: Path): + """Every unit test that starts a container skips when Docker can't be reached, and the rest pass.""" + directory, arguments = _unit_test_hook() + unreachable = {name: value for name, value in os.environ.items() if not name.startswith("TESTCONTAINERS")} + unreachable |= {"HOME": str(tmp_path), "DOCKER_HOST": "tcp://127.0.0.1:1"} + + run = subprocess.run( + [sys.executable, "-m", "pytest", *arguments, "-q", "-n", "auto", "-p", "no:cacheprovider"], + cwd=REPO_ROOT / directory, + env=unreachable, + capture_output=True, + text=True, + check=False, + ) + + assert run.returncode == 0, run.stdout[-4000:] + assert re.search(r"\b[1-9]\d* skipped\b", run.stdout), run.stdout[-4000:] diff --git a/blueprint/tests/test_retired_cli.py b/blueprint/tests/test_retired_cli.py new file mode 100644 index 00000000..0a0ed761 --- /dev/null +++ b/blueprint/tests/test_retired_cli.py @@ -0,0 +1,165 @@ +"""Nothing outside the history names the developer tool's old package, the command it shipped, +or the drill that built the repository without each feature.""" + +import importlib.metadata +import re +from collections.abc import Iterator + +import click +import pytest +import typer.main +from fastro import compat +from fastro.cli import app +from fastro.engine import blueprint +from fastro.tools import installed_version +from fastro.verify import verify_sets +from retired import ( + NAMES_OLD_COMMAND, + NAMES_OLD_DRILL, + NAMES_OLD_PACKAGE, + OLD_COMMAND, + OLD_DRILL, + OLD_PACKAGE, + REPO_ROOT, + SAYS_OLD_COMMAND_EXITS, + tracked_text, +) + +NEEDLES = {"package": NAMES_OLD_PACKAGE, "command": NAMES_OLD_COMMAND, "drill": NAMES_OLD_DRILL} + +STILL_CARRYING = { + ("package", "docs/changelog.md"): "the history, for good", + ("command", "docs/changelog.md"): "the history, for good", + ("command", "docs/assets/build-cover.cjs"): "B5", + ("drill", "docs/changelog.md"): "the history, for good", + ("drill", "docs/index.md"): "B5", + ("drill", "docs/user-guide/testing.md"): "B5", + ("drill", "docs/user-guide/composable-features.md"): "B5", + ("drill", "docs/user-guide/project-structure.md"): "B5", + ("drill", "docs/assets/build-diagrams.cjs"): "B5", +} +"""Which needle each exempted file carries, and the item that lifts the exemption.""" + +REDIRECTS = "[project.plugins.redirects.redirect_maps]" + +FASTRO_PAGE = "docs/user-guide/fastro.md" + + +def _lines(name: str, text: str) -> Iterator[tuple[int, str]]: + """The numbered lines of a file, without the lines of `zensical.toml`'s redirect map.""" + inside = False + for number, line in enumerate(text.splitlines(), 1): + if name == "zensical.toml" and line.startswith("["): + inside = line.strip() == REDIRECTS + if not inside: + yield number, line + + +def _hits() -> dict[tuple[str, str], list[str]]: + hits: dict[tuple[str, str], list[str]] = {} + for name, text in tracked_text(): + for number, line in _lines(name, text): + for needle, pattern in NEEDLES.items(): + if pattern.search(line) and not (name == FASTRO_PAGE and SAYS_OLD_COMMAND_EXITS.match(line)): + hits.setdefault((needle, name), []).append(f"{name}:{number}: {line.strip()}") + + return hits + + +def test_no_file_names_the_old_package_its_command_or_the_drill(): + found = [line for key, lines in _hits().items() if key not in STILL_CARRYING for line in lines] + + assert found == [] + + +def test_every_exempted_file_still_carries_what_it_is_exempt_for(): + assert set(STILL_CARRYING) <= set(_hits()), "drop the exemption of a file that no longer carries it" + + +@pytest.mark.parametrize( + ("line", "named"), + [ + (f"run: cd {OLD_PACKAGE} && uv run --no-sync pytest", True), + (f"COPY {OLD_PACKAGE}/pyproject.toml {OLD_PACKAGE}/pyproject.toml", True), + (f"uv run --no-sync mypy -p {OLD_PACKAGE}", True), + (f'members = ["backend", "{OLD_PACKAGE}"]', True), + (f"uv tool install --editable ./{OLD_PACKAGE}", True), + (f"from {OLD_PACKAGE}.commands import deploy", True), + (f"uv sync --reinstall-package fastapi-boilerplate-{OLD_PACKAGE}", True), + ("docker compose exec redis redis-cli ping", False), + ("from fastro.cli import app", False), + ("fastro is a CLI", False), + ("the clipboard and a clinic", False), + ], +) +def test_the_package_needle(line: str, named: bool): + assert bool(NAMES_OLD_PACKAGE.search(line)) is named + + +@pytest.mark.parametrize( + ("line", "named"), + [ + (f"uv run {OLD_COMMAND} deploy generate prod", True), + (f"{OLD_COMMAND} env validate", True), + (f"the `{OLD_COMMAND}` command", True), + (f"uv run {OLD_COMMAND} ...", True), + (f'plugin-ready {OLD_COMMAND} CLI', True), + (f"a plugin-aware {OLD_COMMAND} CLI", True), + (f"{OLD_COMMAND}-and-fastro", False), + ("fastro make deploy prod", False), + ], +) +def test_the_command_needle(line: str, named: bool): + assert bool(NAMES_OLD_COMMAND.search(line)) is named + + +@pytest.mark.parametrize( + ("line", "named"), + [ + (f"uv run --no-sync python tools/{OLD_DRILL}.py accounts-only", True), + (f"backend/tests/unit/test_{OLD_DRILL}.py", True), + (f' "{OLD_COMMAND}-and-fastro",', True), + ("uv run --no-sync fastro blueprint verify accounts-only", False), + ("a removal that leaves nothing behind", False), + ], +) +def test_the_drill_needle(line: str, named: bool): + assert bool(NAMES_OLD_DRILL.search(line)) is named + + +def _removed() -> str: + """The changelog's Unreleased `#### Removed` section, on one line.""" + changelog = (REPO_ROOT / "docs" / "changelog.md").read_text() + unreleased = changelog.split("\n## Unreleased\n", 1)[1].split("\n## ", 1)[0] + + return " ".join(unreleased.split("#### Removed", 1)[1].split("\n#### ", 1)[0].split()) + + +def _old_and_new_commands() -> list[tuple[str, str]]: + """The pairs the changelog's entry for the package's removal gives, old command first.""" + return re.findall(rf"`{OLD_COMMAND} ([^`]+)` is `fastro ([^`]+)`", _removed()) + + +def test_the_changelog_says_what_verify_builds_and_keeps(): + entry = _removed().split("**The removal drill.**", 1)[1].split(" - **", 1)[0] + catalog = blueprint.load("blueprint.toml", (REPO_ROOT / "blueprint.toml").read_text(), installed_version()) + root = typer.main.get_command(app) + assert isinstance(root, click.Group) + group = root.commands["blueprint"] + assert isinstance(group, click.Group) + options = {flag for param in group.commands["verify"].params for flag in param.opts} + + assert "`uv run --no-sync fastro blueprint verify`" in entry + assert "`--keep`" in entry and "--keep" in options + assert "each set in `blueprint.toml`, each preset and `everything`" in entry + assert set(verify_sets(catalog)) == {*catalog.verify.sets, *catalog.presets, "everything"} + + +def test_fastro_still_answers_to_the_old_commands_the_changelog_maps(): + scripts = {point.name: point.value for point in importlib.metadata.entry_points(group="console_scripts")} + pairs = _old_and_new_commands() + + assert scripts[OLD_COMMAND] == f"fastro.compat:{OLD_COMMAND}_main" + assert len(pairs) == 3, pairs + for old, new in pairs: + assert compat.translate(old.split()) == new.split(), (old, new) diff --git a/blueprint/tests/test_verify_matrix.py b/blueprint/tests/test_verify_matrix.py new file mode 100644 index 00000000..b925fd97 --- /dev/null +++ b/blueprint/tests/test_verify_matrix.py @@ -0,0 +1,51 @@ +"""CI verifies every set `fastro blueprint verify` builds, one job each.""" + +from pathlib import Path +from typing import Any + +import yaml +from fastro.engine import blueprint +from fastro.tools import installed_version +from fastro.verify import verify_sets + +REPO_ROOT = Path(__file__).resolve().parents[2] +WORKFLOW = REPO_ROOT / ".github" / "workflows" / "tests.yml" +TESTING = REPO_ROOT / "docs" / "user-guide" / "testing.md" + +VERIFY = "uv run --no-sync fastro blueprint verify ${{ matrix.preset }}" + + +def _job() -> dict[str, Any]: + jobs: dict[str, dict[str, Any]] = yaml.safe_load(WORKFLOW.read_text())["jobs"] + (job,) = [job for job in jobs.values() if any(step.get("run") == VERIFY for step in job.get("steps", []))] + + return job + + +def _catalog() -> blueprint.Blueprint: + return blueprint.load("blueprint.toml", (REPO_ROOT / "blueprint.toml").read_text(), installed_version()) + + +def test_the_ci_matrix_is_every_set_verify_builds(): + assert set(_job()["strategy"]["matrix"]) == {"preset"} + assert sorted(_job()["strategy"]["matrix"]["preset"]) == sorted(verify_sets(_catalog())) + + +def test_one_sets_failure_leaves_the_others_running(): + assert _job()["strategy"]["fail-fast"] is False + + +def test_a_failed_verify_fails_the_job(): + job = _job() + (step,) = [step for step in job["steps"] if step.get("run") == VERIFY] + + assert not {"if", "continue-on-error"} & (set(job) | set(step)) + + +def test_the_testing_guide_says_ci_verifies_every_set(): + section = " ".join(TESTING.read_text().split("## Continuous Integration", 1)[1].split("\n## ", 1)[0].split()) + + assert "`fastro blueprint verify`" in section + assert "`[verify.sets]`" in section + assert "`everything`" in section + assert ("presets" in section) is _catalog().verify.include_presets diff --git a/cli/README.md b/cli/README.md deleted file mode 100644 index e379b391..00000000 --- a/cli/README.md +++ /dev/null @@ -1,48 +0,0 @@ -# bp — FastAPI-boilerplate CLI - -`bp` is the developer/operator command-line tool for projects built on the -FastAPI boilerplate. It generates deployment artifacts, helps prepare the -runtime environment, and serves as the host for plugin commands and feature -generators. - -## Install - -This package is part of the workspace. From the repo root: - -```bash -uv sync --all-packages --all-extras # bp is then available via `uv run bp` -uv run bp --help -``` - -To install `bp` machine-wide so it works outside this repo: - -```bash -uv tool install --editable ./cli -bp --help -``` - -## What's here - -``` -cli/src/cli/ -├── app.py root Typer app + plugin discovery -├── plugins.py entry-point loaders for bp.commands and bp.features -├── commands/ in-tree command sub-apps -│ ├── deploy.py bp deploy generate -│ └── env.py bp env gen-secret / bp env validate -├── features/ feature framework (manifest, plan, installer) -│ └── _builtins/ in-tree features -│ └── deploy/ compose/Dockerfile templates for local/prod/nginx -└── lib/ shared helpers (project discovery, prompts, render) -``` - -## Plugin extension points - -Two kinds of plugins, kept deliberately separate: - -- `bp.commands` entry-point group — third-party Typer sub-apps mounted under - `bp ` (e.g. `bp aws deploy`). -- `bp.features` entry-point group — code generators with a manifest that - `bp feature` can list, install, and remove. - -See `cli/src/cli/plugins.py` for the discovery contracts. diff --git a/cli/pyproject.toml b/cli/pyproject.toml deleted file mode 100644 index d17c074d..00000000 --- a/cli/pyproject.toml +++ /dev/null @@ -1,60 +0,0 @@ -[build-system] -requires = ["setuptools", "wheel"] -build-backend = "setuptools.build_meta" - -[project] -name = "fastapi-boilerplate-cli" -version = "0.1.0" -description = "bp — developer/operator CLI for the FastAPI boilerplate. Hosts in-tree commands and discovers third-party plugins." -authors = [{ name = "Benav Labs", email = "contact@benav.io" }] -license = { text = "MIT" } -readme = "README.md" -requires-python = ">=3.11" -dependencies = [ - "typer>=0.12", - "jinja2>=3.1", - "fastapi-boilerplate", -] - -[project.optional-dependencies] -dev = [ - "pytest>=8.3.5", - "pyyaml>=6.0.2", -] - -[project.scripts] -bp = "cli.app:app" - -[tool.uv.sources] -fastapi-boilerplate = { workspace = true } - -[tool.setuptools] -include-package-data = true - -[tool.setuptools.packages.find] -where = ["src"] -include = ["*"] - -[tool.setuptools.package-data] -"*" = ["*.j2", "*.toml", "*.conf", "py.typed"] - -[tool.pytest.ini_options] -testpaths = ["tests"] -pythonpath = ["src"] -python_files = ["test_*.py"] - -[tool.ruff] -line-length = 128 - -[tool.ruff.lint] -select = ["E", "F", "I", "UP"] -extend-select = ["UP006", "UP007", "UP035", "UP039", "PLC0415"] - -[tool.ruff.lint.isort] -known-first-party = ["cli"] - -[tool.mypy] -python_version = "3.11" -warn_return_any = true -warn_unused_configs = true -warn_unused_ignores = true diff --git a/cli/src/cli/__init__.py b/cli/src/cli/__init__.py deleted file mode 100644 index d32794ee..00000000 --- a/cli/src/cli/__init__.py +++ /dev/null @@ -1,12 +0,0 @@ -"""bp — the FastAPI-boilerplate command-line tool. - -The CLI is a Typer application with two extension points: - -- `bp.commands` entry-point group: third-party packages can register - top-level Typer sub-apps that mount under `bp `. -- `bp.features` entry-point group: third-party packages can register - ``Feature`` instances that ``bp feature`` can list, install, and remove. - -In-tree commands and features live alongside this package and follow -the same contracts as plugins. -""" diff --git a/cli/src/cli/app.py b/cli/src/cli/app.py deleted file mode 100644 index fcae4ce1..00000000 --- a/cli/src/cli/app.py +++ /dev/null @@ -1,62 +0,0 @@ -"""bp — root Typer application and entry point. - -Mounts in-tree command sub-apps and discovers third-party plugins. -The shipped console script (``[project.scripts] bp``) targets -``app`` directly. -""" - -from __future__ import annotations - -import typer - -from . import plugins as _plugins -from .commands import deploy as _deploy_cmd -from .commands import env as _env_cmd - -app = typer.Typer( - name="bp", - help="FastAPI-boilerplate command-line tool.", - no_args_is_help=True, - pretty_exceptions_show_locals=False, -) - -# In-tree commands. Mounted before plugin discovery so a plugin can't -# silently shadow a built-in by registering the same name. -app.add_typer(_deploy_cmd.app, name="deploy", help="Generate deployment artifacts (Dockerfile, compose, nginx config).") -app.add_typer(_env_cmd.app, name="env", help="Inspect and prepare the runtime environment.") - - -def _mount_command_plugins() -> None: - """Mount external Typer sub-apps registered under ``bp.commands``. - - A plugin that fails to load warns rather than stopping the CLI, so the warning - is routed to stderr first: on stdout it would land in whatever the caller is - piping command output into. - """ - _plugins.emit_plugin_warnings_to_stderr() - - builtin_names = {"deploy", "env", "feature"} - for name, sub_app in _plugins.discover_command_plugins().items(): - if name in builtin_names: - typer.secho( - f"warning: plugin command '{name}' shadows a built-in; ignoring.", - fg=typer.colors.YELLOW, - err=True, - ) - continue - app.add_typer(sub_app, name=name) - - -_mount_command_plugins() - - -@app.callback() -def _root() -> None: - """bp — FastAPI-boilerplate command-line tool.""" - # Typer uses this docstring as the root help text. The body is - # intentionally empty: the callback exists so options like - # ``--install-completion`` work without arguments. - - -if __name__ == "__main__": # pragma: no cover - app() diff --git a/cli/src/cli/commands/__init__.py b/cli/src/cli/commands/__init__.py deleted file mode 100644 index e69de29b..00000000 diff --git a/cli/src/cli/commands/deploy.py b/cli/src/cli/commands/deploy.py deleted file mode 100644 index 84200f5b..00000000 --- a/cli/src/cli/commands/deploy.py +++ /dev/null @@ -1,107 +0,0 @@ -"""``bp deploy`` — generate deployment artifacts. - -Today this is just a wrapper around the in-tree ``deploy`` feature. -Other deploy-adjacent commands (``bp deploy nginx-tls``, ``bp deploy -github-actions``) can mount here as siblings. -""" - -from __future__ import annotations - -from enum import StrEnum -from pathlib import Path - -import typer - -from ..features._builtins.deploy.feature import DEFAULT_INTERNAL_SUBNET -from ..features.installer import FeatureInstaller -from ..features.registry import get_feature -from ..lib.project import discover_project -from ..lib.prompts import error, info - -app = typer.Typer(no_args_is_help=True, help="Generate deployment artifacts.") - - -class DeployMode(StrEnum): - local = "local" - prod = "prod" - nginx = "nginx" - - -@app.command("generate") -def generate( - mode: DeployMode = typer.Argument( - ..., - help="Deployment mode to generate. Pick `local` for hot-reload dev, `prod` for " - "single-host production, `nginx` for production behind a reverse proxy.", - ), - output_dir: Path = typer.Option( - None, - "--output-dir", - "-o", - help="Where to write the compose file. Defaults to the repo root.", - ), - api_port: int = typer.Option(8000, "--api-port", help="Host port to publish the API on."), - workers: int = typer.Option(4, "--workers", help="Number of API workers (prod / nginx only)."), - internal_subnet: str = typer.Option( - DEFAULT_INTERNAL_SUBNET, - "--internal-subnet", - help="Subnet for the compose network, and the only peers uvicorn takes forwarded headers from (nginx only).", - ), - force: bool = typer.Option(False, "--force", "-f", help="Overwrite existing files without asking."), - yes: bool = typer.Option(False, "--yes", "-y", help="Assume yes for all prompts."), - dry_run: bool = typer.Option(False, "--dry-run", help="Show what would be written, don't touch disk."), -) -> None: - """Generate ``docker-compose.yml`` (and ``nginx/default.conf`` for nginx mode).""" - project = discover_project(output_dir) - feature = get_feature("deploy") - if feature is None: # pragma: no cover — built-in feature, always present - error("deploy feature is not registered.") - raise typer.Exit(code=1) - - target_root = (output_dir or project.repo_root).resolve() - if not dry_run: - target_root.mkdir(parents=True, exist_ok=True) - - params: dict = { - "mode": mode.value, - "api_port": api_port, - "workers": workers, - "compose_target": target_root / "docker-compose.yml", - } - if mode == DeployMode.nginx: - params["nginx_conf_target"] = target_root / "nginx" / "default.conf" - params["internal_subnet"] = internal_subnet - - try: - plan = feature.plan(params, project) - except ValueError as failure: - error(f"--internal-subnet: {failure}") - raise typer.Exit(code=1) from failure - - installer = FeatureInstaller(dry_run=dry_run, assume_yes=force or yes) - info(f"deploy: generating '{mode.value}' compose for {project.repo_root}") - result = installer.apply(plan) - - if result.files_skipped: - info("") - info(f"{len(result.files_skipped)} file(s) skipped.") - if dry_run: - info("") - info("dry-run complete — no files were written.") - return - - info("") - info("done. Next steps:") - if mode == DeployMode.local: - info(" docker compose up --build") - return - - info(" cp backend/.env.example backend/.env # if you haven't already") - info(" # with migrations/versions empty, generate and commit the baseline first,") - info(" # against a database with nothing in it, or upgrade writes an empty revision:") - info(" # docs/user-guide/database/migrations.md#alembic-migrations") - info(" docker compose build") - info(" docker compose --profile migrate run --rm migrate") - info(" docker compose up -d") - if mode == DeployMode.nginx: - info(" curl -i http://localhost/health/ready") diff --git a/cli/src/cli/commands/env.py b/cli/src/cli/commands/env.py deleted file mode 100644 index cb889947..00000000 --- a/cli/src/cli/commands/env.py +++ /dev/null @@ -1,139 +0,0 @@ -"""``bp env`` — inspect and prepare the runtime environment. - -Two commands today: - -- ``bp env gen-secret`` prints a 64-char hex string suitable for - ``SECRET_KEY``. No filesystem I/O — pipe it into your secrets manager. - -- ``bp env validate`` runs the production security validator against - the current settings, regardless of the configured environment, and - prints critical errors and warnings. -""" - -from __future__ import annotations - -import importlib -import importlib.util -import secrets -import sys -from pathlib import Path -from types import ModuleType - -import typer - -from ..lib.prompts import error, info, success, warn - - -def _backend_root() -> Path | None: - """The ``backend/`` of the project this command was run in, if there is one.""" - return next((p / "backend" for p in (Path.cwd(), *Path.cwd().parents) if (p / "backend" / "src").is_dir()), None) - - -def _app_module(name: str) -> ModuleType: - """Import a backend module by its ``src.`` path, putting ``backend/`` on the path first. - - The app is imported through a single root, ``src``, which the installed - distribution does not expose: its packages are published from inside ``src/``. - Resolving it here, when a command needs it, also keeps ``bp --help`` from - paying for the app's settings and database imports. - """ - backend = _backend_root() - if backend is None: - error("No `backend/src` in this directory or above it: run this from inside a project.") - raise typer.Exit(code=1) - - if str(backend) not in sys.path: - sys.path.insert(0, str(backend)) - - return importlib.import_module(name) - - -def _secret_key_rules() -> ModuleType | None: - """The app's own secret-key rules, or ``None`` outside a project. - - Loaded from their file, which keeps the settings and logging imports of the - package around them out of this command's output. - """ - backend = _backend_root() - if backend is None: - return None - - spec = importlib.util.spec_from_file_location( - "app_secret_key_rules", backend / "src" / "infrastructure" / "security" / "secret_key.py" - ) - if spec is None or spec.loader is None: - return None - - rules = importlib.util.module_from_spec(spec) - try: - spec.loader.exec_module(rules) - except Exception: - return None - - return rules - - -SECRET_KEY_DRAWS = 8 - -app = typer.Typer(no_args_is_help=True, help="Inspect and prepare the runtime environment.") - - -@app.command("gen-secret") -def gen_secret( - bytes_: int = typer.Option(32, "--bytes", min=16, max=128, help="Number of random bytes (hex output is 2x)."), -) -> None: - """Generate a high-entropy hex secret suitable for ``SECRET_KEY``. - - Draws again while the app's own rules would refuse the key: about one hex key in - twelve million runs through eight consecutive digits, which production refuses at - startup. Outside a project, where those rules cannot be imported, the first draw - is printed. - """ - rules = _secret_key_rules() - is_weak = getattr(rules, "is_weak_secret_key", None) - - candidate = secrets.token_hex(bytes_) - for _ in range(SECRET_KEY_DRAWS - 1): - if is_weak is None or not is_weak(candidate): - break - candidate = secrets.token_hex(bytes_) - - typer.echo(candidate) - - -@app.command("validate") -def validate() -> None: - """Run the production security validator against the current settings. - - Reports what production would refuse whatever ``ENVIRONMENT`` says, so a dev - or staging config can be audited the same way prod is gated. The settings are - audited as a copy that says ``production``, so a finding that names the - environment names the one being audited for. - """ - settings_module = _app_module("src.infrastructure.config.settings") - settings = settings_module.get_settings() - validator_module = _app_module("src.infrastructure.security.production_validator") - ProductionSecurityValidator = validator_module.ProductionSecurityValidator - - production = settings_module.EnvironmentOption.PRODUCTION - as_production = settings.model_copy(update={"ENVIRONMENT": production}) - critical_errors, captured_warnings = ProductionSecurityValidator(as_production).audit() - - if not critical_errors and not captured_warnings: - success("No issues found. Configuration would pass production validation.") - return - - if critical_errors: - error(f"Critical ({len(critical_errors)}):") - for item in critical_errors: - typer.secho(f" • {item}", fg=typer.colors.RED) - - if captured_warnings: - if critical_errors: - info("") - warn(f"Warnings ({len(captured_warnings)}):") - for item in captured_warnings: - typer.secho(f" • {item}", fg=typer.colors.YELLOW) - - if critical_errors: - raise typer.Exit(code=1) diff --git a/cli/src/cli/features/__init__.py b/cli/src/cli/features/__init__.py deleted file mode 100644 index 424beee4..00000000 --- a/cli/src/cli/features/__init__.py +++ /dev/null @@ -1,25 +0,0 @@ -"""Feature framework: typed manifests, plans, and the installer. - -A feature is a self-contained unit of work that mutates a user's -project — generating files, editing existing files, running setup -hooks. ``Feature`` subclasses describe themselves via a manifest and -emit a ``FeaturePlan`` that the installer executes. - -For v1 only ``FileOp`` operations are supported. ``Codemod`` and ``Hook`` -slots in the plan exist for forward compatibility — installers raise -``NotImplementedError`` if a plan asks for one. -""" - -from .base import Codemod, Feature, FeatureManifest, FeaturePlan, FileOp, Hook -from .installer import FeatureInstaller, InstallResult - -__all__ = [ - "Codemod", - "Feature", - "FeatureInstaller", - "FeatureManifest", - "FeaturePlan", - "FileOp", - "Hook", - "InstallResult", -] diff --git a/cli/src/cli/features/_builtins/__init__.py b/cli/src/cli/features/_builtins/__init__.py deleted file mode 100644 index e69de29b..00000000 diff --git a/cli/src/cli/features/_builtins/deploy/__init__.py b/cli/src/cli/features/_builtins/deploy/__init__.py deleted file mode 100644 index e69de29b..00000000 diff --git a/cli/src/cli/features/_builtins/deploy/feature.py b/cli/src/cli/features/_builtins/deploy/feature.py deleted file mode 100644 index 30817b2a..00000000 --- a/cli/src/cli/features/_builtins/deploy/feature.py +++ /dev/null @@ -1,108 +0,0 @@ -"""The deploy feature — generate Dockerfile-friendly compose files. - -Three modes are supported in v1: - -- ``local``: hot-reload dev stack (mounts source, exposes port 8000) -- ``prod``: production stack with multiple workers, ports exposed directly -- ``nginx``: ``prod`` plus an nginx reverse proxy on port 80 - -All modes target the existing multi-stage ``backend/Dockerfile`` — -no per-mode Dockerfile is generated. Modes only differ in the -compose file (and an optional nginx config). -""" - -from __future__ import annotations - -from ipaddress import ip_network -from pathlib import Path -from typing import Any - -from ....lib.project import ProjectContext -from ...base import Feature, FeatureManifest, FeaturePlan, FileOp - -SUPPORTED_MODES: tuple[str, ...] = ("local", "prod", "nginx") -DEFAULT_INTERNAL_SUBNET = "172.31.240.0/24" -SMALLEST_TRUSTED_PREFIX = {4: 8, 6: 48} -TASKIQ_PACKAGE = "src/infrastructure/taskiq" -"""The feature whose worker and scheduler services the compose files carry.""" - -_TEMPLATES_ROOT = Path(__file__).parent / "templates" - - -def validated_subnet(value: str) -> str: - """The subnet in the form ``ipaddress`` reads, refusing one that trusts too much. - - Takes a network of ``/8`` or smaller for IPv4, ``/48`` or smaller for IPv6. - - Raises: - ValueError: ``value`` is not a network address, carries host bits, or covers - more than the smallest prefix its family allows. - """ - try: - network = ip_network(value, strict=True) - except ValueError as error: - raise ValueError(f"{value!r} is not a network address, such as 172.31.240.0/24.") from error - - smallest = SMALLEST_TRUSTED_PREFIX[network.version] - if network.prefixlen < smallest: - raise ValueError(f"{value!r} covers {network.num_addresses} addresses; name a range of /{smallest} or smaller.") - - return str(network) - - -class DeployFeature(Feature): - def manifest(self) -> FeatureManifest: - return FeatureManifest( - name="deploy", - version="1.0", - summary="Generate a docker-compose.yml for local, prod, or nginx-fronted deployments.", - ) - - def plan(self, params: dict[str, Any], project: ProjectContext) -> FeaturePlan: - mode = params.get("mode") - if mode not in SUPPORTED_MODES: - raise ValueError(f"Unsupported deploy mode: {mode!r}. Choose one of {SUPPORTED_MODES}.") - - project_name = params.get("project_name") or project.repo_root.name - api_port = int(params.get("api_port", 8000)) - workers = int(params.get("workers", 4)) - postgres_image = params.get("postgres_image", "postgres:16-alpine") - redis_image = params.get("redis_image", "redis:7-alpine") - nginx_image = params.get("nginx_image", "nginx:1.27-alpine") - backend_context = params.get("backend_context", "./backend") - build_context = params.get("build_context", ".") - backend_dockerfile = params.get("backend_dockerfile", "backend/Dockerfile") - env_file = params.get("env_file", "./backend/.env") - internal_subnet = validated_subnet(params.get("internal_subnet", DEFAULT_INTERNAL_SUBNET)) - taskiq = (project.backend_dir / TASKIQ_PACKAGE).is_dir() - - context = { - "mode": mode, - "project_name": project_name, - "api_port": api_port, - "workers": workers, - "postgres_image": postgres_image, - "redis_image": redis_image, - "nginx_image": nginx_image, - "backend_context": backend_context, - "build_context": build_context, - "backend_dockerfile": backend_dockerfile, - "env_file": env_file, - "internal_subnet": internal_subnet, - "taskiq": taskiq, - } - - compose_target = Path(params.get("compose_target") or (project.repo_root / "docker-compose.yml")) - files: list[FileOp] = [ - FileOp(template=f"{mode}/docker-compose.yml.j2", target=compose_target), - ] - if mode == "nginx": - nginx_target = Path(params.get("nginx_conf_target") or (project.repo_root / "nginx" / "default.conf")) - files.append(FileOp(template="nginx/default.conf.j2", target=nginx_target)) - - return FeaturePlan( - manifest=self.manifest(), - templates_root=_TEMPLATES_ROOT, - template_context=context, - files=tuple(files), - ) diff --git a/cli/src/cli/features/base.py b/cli/src/cli/features/base.py deleted file mode 100644 index 1bd8f019..00000000 --- a/cli/src/cli/features/base.py +++ /dev/null @@ -1,98 +0,0 @@ -"""Feature contracts: manifest, plan, base class, and operation types. - -The shapes here are designed so that today's "render templates to disk" -features and tomorrow's "drop a module + edit settings + run a -migration" features can both describe themselves with the same plan -schema. Installers grow capabilities over time; manifests don't have -to change. -""" - -from __future__ import annotations - -from abc import ABC, abstractmethod -from dataclasses import dataclass, field -from pathlib import Path -from typing import Any - -from ..lib.project import ProjectContext - - -@dataclass(frozen=True) -class FeatureManifest: - """Static metadata about a feature. - - The manifest is the part that's safe to read without executing - anything — used by ``bp feature list`` / ``bp feature info`` to - describe what's available. - """ - - name: str - version: str - summary: str - requires_features: tuple[str, ...] = () - adds_dependencies: tuple[str, ...] = () - - -@dataclass(frozen=True) -class FileOp: - """Render a Jinja template and write it to ``target``. - - ``template`` is interpreted relative to the feature's templates - directory. ``target`` is an absolute path on the user's disk. - """ - - template: str - target: Path - overwrite: bool = False - skip_if_exists: bool = False - executable: bool = False - - -@dataclass(frozen=True) -class Codemod: - """Reserved for AST-aware edits to existing source files. - - Not implemented in v1. Defining the type here means feature plans - can reference codemods today without breaking the manifest schema - when the installer learns to execute them. - """ - - target: Path - operation: str - params: dict[str, Any] = field(default_factory=dict) - - -@dataclass(frozen=True) -class Hook: - """Reserved for post-install commands (alembic revisions, scripts, etc.).""" - - name: str - command: tuple[str, ...] - cwd: Path | None = None - - -@dataclass(frozen=True) -class FeaturePlan: - """Concrete description of what a feature wants to do, given parameters.""" - - manifest: FeatureManifest - templates_root: Path | None - template_context: dict[str, Any] = field(default_factory=dict) - files: tuple[FileOp, ...] = () - codemods: tuple[Codemod, ...] = () - hooks: tuple[Hook, ...] = () - - -class Feature(ABC): - """Base class for all features. - - Subclasses declare a static ``manifest()`` and an instance-method - ``plan(params, project)`` that yields the concrete plan for the - current invocation. - """ - - @abstractmethod - def manifest(self) -> FeatureManifest: ... - - @abstractmethod - def plan(self, params: dict[str, Any], project: ProjectContext) -> FeaturePlan: ... diff --git a/cli/src/cli/features/installer.py b/cli/src/cli/features/installer.py deleted file mode 100644 index e2692ae8..00000000 --- a/cli/src/cli/features/installer.py +++ /dev/null @@ -1,88 +0,0 @@ -"""Execute a ``FeaturePlan`` against the user's project. - -V1 supports file rendering only. Codemods and hooks raise -``NotImplementedError`` so plans can declare them today and the -installer will gain support over time without breaking the contract. -""" - -from __future__ import annotations - -import stat -from dataclasses import dataclass, field -from pathlib import Path - -from ..lib.prompts import confirm_overwrite, info, success, warn -from ..lib.render import Renderer -from .base import FeaturePlan - - -@dataclass -class InstallResult: - """Summary of what an installer pass actually did.""" - - files_written: list[Path] = field(default_factory=list) - files_skipped: list[Path] = field(default_factory=list) - - -class FeatureInstaller: - """Apply a ``FeaturePlan`` to disk. - - Construction options control the prompting / I/O behavior. - """ - - def __init__(self, *, dry_run: bool = False, assume_yes: bool = False, quiet: bool = False) -> None: - self.dry_run = dry_run - self.assume_yes = assume_yes - self.quiet = quiet - - def apply(self, plan: FeaturePlan) -> InstallResult: - result = InstallResult() - if plan.codemods: - raise NotImplementedError("Codemod operations are not yet supported by the installer.") - if plan.hooks: - raise NotImplementedError("Post-install hooks are not yet supported by the installer.") - - renderer: Renderer | None = None - if plan.files and plan.templates_root is not None: - renderer = Renderer(plan.templates_root) - - for op in plan.files: - if op.target.exists(): - if op.skip_if_exists: - if not self.quiet: - warn(f"skip {op.target} (exists)") - result.files_skipped.append(op.target) - continue - if not op.overwrite and not self.dry_run: - if not confirm_overwrite(str(op.target), assume_yes=self.assume_yes): - if not self.quiet: - warn(f"skip {op.target} (kept existing)") - result.files_skipped.append(op.target) - continue - - if renderer is None: - raise RuntimeError(f"Plan has files but no templates_root: cannot render {op.template!r}") - - content = renderer.render(op.template, plan.template_context) - - if self.dry_run: - if not self.quiet: - replacing = " (replacing what is there)" if op.target.exists() else "" - info(f"would write {op.target} ({len(content)} bytes){replacing}") - result.files_written.append(op.target) - continue - - op.target.parent.mkdir(parents=True, exist_ok=True) - op.target.write_text(content, encoding="utf-8") - if op.executable: - _make_executable(op.target) - if not self.quiet: - success(f"wrote {op.target}") - result.files_written.append(op.target) - - return result - - -def _make_executable(path: Path) -> None: - current = path.stat().st_mode - path.chmod(current | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH) diff --git a/cli/src/cli/features/registry.py b/cli/src/cli/features/registry.py deleted file mode 100644 index 85c3ae4a..00000000 --- a/cli/src/cli/features/registry.py +++ /dev/null @@ -1,44 +0,0 @@ -"""Look up features by name across in-tree and plugin sources. - -In-tree features are imported lazily so that adding new ones doesn't -slow down every CLI invocation. Plugin features come from the -``bp.features`` entry-point group. -""" - -from __future__ import annotations - -import warnings - -from .. import plugins as _plugins -from ._builtins.deploy.feature import DeployFeature -from .base import Feature - - -def _builtin_features() -> dict[str, Feature]: - """Return in-tree features.""" - return { - "deploy": DeployFeature(), - } - - -def all_features() -> dict[str, Feature]: - """Return ``{name: feature}`` for every in-tree and plugin feature. - - In-tree features take precedence on name collisions; a warning is - surfaced when a plugin tries to shadow a built-in. - """ - found: dict[str, Feature] = dict(_builtin_features()) - for name, feature in _plugins.discover_feature_plugins().items(): - if name in found: - warnings.warn( - f"feature plugin {name!r} shadows a built-in; ignoring plugin.", - RuntimeWarning, - stacklevel=2, - ) - continue - found[name] = feature - return found - - -def get_feature(name: str) -> Feature | None: - return all_features().get(name) diff --git a/cli/src/cli/lib/__init__.py b/cli/src/cli/lib/__init__.py deleted file mode 100644 index e69de29b..00000000 diff --git a/cli/src/cli/lib/project.py b/cli/src/cli/lib/project.py deleted file mode 100644 index 5501a4e8..00000000 --- a/cli/src/cli/lib/project.py +++ /dev/null @@ -1,70 +0,0 @@ -"""Locate the user's project on disk and read context from it. - -The CLI is shipped inside ``backend/src/cli`` of the boilerplate, but -when invoked it operates on whichever directory the user is in. These -helpers resolve the repo root, the backend directory, and read values -from the project's ``.env`` files without importing the application. -""" - -from __future__ import annotations - -from dataclasses import dataclass -from pathlib import Path - - -@dataclass(frozen=True) -class ProjectContext: - """Resolved paths the CLI needs to operate on the user's repo.""" - - repo_root: Path - backend_dir: Path - - @property - def env_file(self) -> Path: - return self.backend_dir / ".env" - - @property - def env_example(self) -> Path: - return self.backend_dir / ".env.example" - - @property - def compose_file(self) -> Path: - return self.repo_root / "docker-compose.yml" - - -def discover_project(start: Path | None = None) -> ProjectContext: - """Walk up from ``start`` looking for a ``backend/pyproject.toml`` marker. - - Falls back to the current working directory if no marker is found — - the caller is responsible for deciding whether that's acceptable. - """ - current = (start or Path.cwd()).resolve() - for candidate in [current, *current.parents]: - if (candidate / "backend" / "pyproject.toml").is_file(): - return ProjectContext(repo_root=candidate, backend_dir=candidate / "backend") - if (candidate / "pyproject.toml").is_file() and candidate.name == "backend": - return ProjectContext(repo_root=candidate.parent, backend_dir=candidate) - return ProjectContext(repo_root=current, backend_dir=current / "backend") - - -def read_env_value(env_path: Path, key: str) -> str | None: - """Read a single value from a ``.env``-style file. - - Returns ``None`` if the file is missing or the key isn't set. Quotes - around the value (single or double) are stripped. Lines beginning - with ``#`` are skipped. - """ - if not env_path.is_file(): - return None - for raw in env_path.read_text(encoding="utf-8").splitlines(): - line = raw.strip() - if not line or line.startswith("#") or "=" not in line: - continue - name, _, value = line.partition("=") - if name.strip() != key: - continue - value = value.strip() - if len(value) >= 2 and value[0] == value[-1] and value[0] in {'"', "'"}: - value = value[1:-1] - return value - return None diff --git a/cli/src/cli/lib/prompts.py b/cli/src/cli/lib/prompts.py deleted file mode 100644 index 49cf3b9c..00000000 --- a/cli/src/cli/lib/prompts.py +++ /dev/null @@ -1,32 +0,0 @@ -"""Consistent prompt helpers used across the CLI. - -Centralizes ``--yes`` (assume-yes) and ``--quiet`` handling so individual -commands don't each invent their own. -""" - -from __future__ import annotations - -import typer - - -def confirm_overwrite(path: str, *, assume_yes: bool) -> bool: - """Confirm overwriting an existing file. Returns True to proceed.""" - if assume_yes: - return True - return typer.confirm(f"{path} already exists. Overwrite?", default=False) - - -def info(message: str) -> None: - typer.echo(message) - - -def success(message: str) -> None: - typer.secho(message, fg=typer.colors.GREEN) - - -def warn(message: str) -> None: - typer.secho(message, fg=typer.colors.YELLOW) - - -def error(message: str) -> None: - typer.secho(message, fg=typer.colors.RED, err=True) diff --git a/cli/src/cli/lib/render.py b/cli/src/cli/lib/render.py deleted file mode 100644 index f43b0ac3..00000000 --- a/cli/src/cli/lib/render.py +++ /dev/null @@ -1,33 +0,0 @@ -"""Jinja-based template rendering for in-tree features and plugins. - -A feature points at a directory containing Jinja templates. ``Renderer`` -loads them with a sandboxed environment, applies the supplied context, -and writes the result to disk. -""" - -from __future__ import annotations - -from pathlib import Path -from typing import Any - -from jinja2 import Environment, FileSystemLoader, StrictUndefined - - -class Renderer: - """Render Jinja templates from a feature's templates directory.""" - - def __init__(self, templates_root: Path) -> None: - if not templates_root.is_dir(): - raise FileNotFoundError(f"Templates directory does not exist: {templates_root}") - self.templates_root = templates_root - self.env = Environment( - loader=FileSystemLoader(str(templates_root)), - keep_trailing_newline=True, - undefined=StrictUndefined, - autoescape=False, - ) - - def render(self, template_path: str, context: dict[str, Any]) -> str: - """Render ``template_path`` (relative to ``templates_root``) with ``context``.""" - template = self.env.get_template(template_path) - return template.render(**context) diff --git a/cli/src/cli/plugins.py b/cli/src/cli/plugins.py deleted file mode 100644 index 7326b5f2..00000000 --- a/cli/src/cli/plugins.py +++ /dev/null @@ -1,109 +0,0 @@ -"""Plugin discovery for the bp CLI. - -Two extension points, kept deliberately separate: - -- ``bp.commands`` — a Typer sub-app mounted under the root, e.g. - ``bp aws deploy``. Plugin packages declare entry points whose values - resolve to a ``typer.Typer`` instance. - -- ``bp.features`` — a ``Feature`` instance that ``bp feature`` can list - and apply. Plugin packages declare entry points whose values resolve - to ``Feature`` instances (or callables that return one). - -A broken plugin must not break the CLI. Discovery wraps each load in a -broad except and surfaces a warning so the user can still operate the -working subset. -""" - -from __future__ import annotations - -import sys -import warnings -from importlib.metadata import EntryPoint, entry_points - -import typer - -from .features.base import Feature - -COMMANDS_GROUP = "bp.commands" -FEATURES_GROUP = "bp.features" - - -def _safe_load(ep: EntryPoint) -> object | None: - try: - loaded: object = ep.load() - except Exception as exc: - warnings.warn( - f"Failed to load plugin {ep.name!r} from {ep.value!r}: {exc!s}", - RuntimeWarning, - stacklevel=2, - ) - return None - return loaded - - -def discover_command_plugins() -> dict[str, typer.Typer]: - """Return ``{name: typer_app}`` for every healthy ``bp.commands`` entry point.""" - found: dict[str, typer.Typer] = {} - for ep in entry_points(group=COMMANDS_GROUP): - loaded = _safe_load(ep) - if loaded is None: - continue - if isinstance(loaded, typer.Typer): - found[ep.name] = loaded - else: - warnings.warn( - f"Plugin {ep.name!r} resolved to {type(loaded).__name__}, expected typer.Typer; ignoring.", - RuntimeWarning, - stacklevel=2, - ) - return found - - -def discover_feature_plugins() -> dict[str, Feature]: - """Return ``{name: feature}`` for every healthy ``bp.features`` entry point. - - Entry-point values may be either a ``Feature`` instance or a callable - that returns one (helpful when constructing features needs the project - context). - """ - found: dict[str, Feature] = {} - for ep in entry_points(group=FEATURES_GROUP): - loaded = _safe_load(ep) - if loaded is None: - continue - candidate = loaded() if callable(loaded) and not isinstance(loaded, Feature) else loaded - if isinstance(candidate, Feature): - found[ep.name] = candidate - else: - warnings.warn( - f"Feature plugin {ep.name!r} resolved to {type(candidate).__name__}, expected Feature; ignoring.", - RuntimeWarning, - stacklevel=2, - ) - return found - - -def emit_plugin_warnings_to_stderr() -> None: - """Route plugin-load warnings to stderr so CLI output stays clean.""" - warnings.filterwarnings("default", category=RuntimeWarning, module=__name__) - if not any(isinstance(h, _StderrWarningHandler) for h in _installed_handlers()): - warnings.showwarning = _StderrWarningHandler() - - -class _StderrWarningHandler: - def __call__( - self, - message: Warning | str, - category: type[Warning], - filename: str, - lineno: int, - file: object = None, - line: str | None = None, - ) -> None: - print(f"warning: {message}", file=sys.stderr) - - -def _installed_handlers() -> list[object]: - handler = warnings.showwarning - return [handler] if handler is not None else [] diff --git a/cli/src/cli/py.typed b/cli/src/cli/py.typed deleted file mode 100644 index e69de29b..00000000 diff --git a/cli/tests/__init__.py b/cli/tests/__init__.py deleted file mode 100644 index e69de29b..00000000 diff --git a/cli/tests/test_deploy_command.py b/cli/tests/test_deploy_command.py deleted file mode 100644 index 4ef410c4..00000000 --- a/cli/tests/test_deploy_command.py +++ /dev/null @@ -1,121 +0,0 @@ -"""``bp deploy generate``: what it writes, and what a dry run leaves alone.""" - -import pytest -import yaml -from typer.testing import CliRunner - -from cli.commands import deploy - -runner = CliRunner() - - -@pytest.fixture -def project(tmp_path): - """A directory that looks enough like a project for the command to run in.""" - (tmp_path / "backend").mkdir() - (tmp_path / "pyproject.toml").write_text("[project]\nname = 'example'\n") - - return tmp_path - - -def test_a_dry_run_writes_nothing_and_creates_no_directory(project): - target = project / "generated" - - result = runner.invoke(deploy.app, ["nginx", "-o", str(target), "--dry-run"]) - - assert result.exit_code == 0, result.output - assert "would write" in result.output - assert not target.exists() - - -def test_a_dry_run_over_an_existing_file_asks_nothing(project): - compose = project / "docker-compose.yml" - compose.write_text("keep me\n") - - result = runner.invoke(deploy.app, ["prod", "-o", str(project), "--dry-run"], input="") - - assert result.exit_code == 0, result.output - assert compose.read_text() == "keep me\n" - assert "Overwrite" not in result.output - - -def test_a_project_with_taskiq_gets_its_worker_and_scheduler(project): - """The services are read off the project: this one carries the feature.""" - (project / "backend/src/infrastructure/taskiq").mkdir(parents=True) - - result = runner.invoke(deploy.app, ["prod", "-o", str(project), "--yes"]) - - assert result.exit_code == 0, result.output - compose = (project / "docker-compose.yml").read_text() - assert "taskiq worker src.infrastructure.taskiq.worker:default_broker" in compose - assert "taskiq scheduler src.infrastructure.taskiq.scheduler:scheduler" in compose - - -def test_a_project_without_taskiq_gets_neither(project): - result = runner.invoke(deploy.app, ["prod", "-o", str(project), "--yes"]) - - assert result.exit_code == 0, result.output - services = yaml.safe_load((project / "docker-compose.yml").read_text())["services"] - assert "worker" not in services - assert "scheduler" not in services - - -def test_generating_writes_the_compose_file(project): - result = runner.invoke(deploy.app, ["prod", "-o", str(project), "--yes"]) - - assert result.exit_code == 0, result.output - assert (project / "docker-compose.yml").read_text().startswith("# Generated by") - - -@pytest.mark.parametrize( - "subnet", - [ - "*", - "0.0.0.0/0", - "10.0.0.0/7", - "172.31.240.1/24", - "not-a-subnet", - "172.31.240.0/33", - "::/0", - "fd00::/8", - "fd00::/47", - "fd00::1/48", - ], -) -def test_a_subnet_that_trusts_too_much_is_refused(project, subnet: str): - """The range decides whose forwarded headers the app believes.""" - result = runner.invoke(deploy.app, ["nginx", "-o", str(project), "--internal-subnet", subnet, "--yes"]) - - assert result.exit_code == 1 - assert "--internal-subnet" in result.output - assert not (project / "docker-compose.yml").exists() - - -@pytest.mark.parametrize("subnet", ["172.31.240.0/24", "10.1.2.0/28", "192.168.0.0/16", "fd00::/48", "fd00::/64"]) -def test_a_subnet_that_names_a_network_is_accepted(project, subnet: str): - result = runner.invoke(deploy.app, ["nginx", "-o", str(project), "--internal-subnet", subnet, "--yes"]) - - assert result.exit_code == 0, result.output - assert f'- subnet: "{subnet}"' in (project / "docker-compose.yml").read_text() - - -@pytest.mark.parametrize("mode", ["prod", "nginx"]) -def test_the_next_steps_migrate_before_starting_the_stack(project, mode: str): - """The API doesn't create its own schema here, and nothing waits on the migrate service.""" - result = runner.invoke(deploy.app, [mode, "-o", str(project), "--yes"]) - - assert result.exit_code == 0, result.output - steps = [line.strip() for line in result.output.splitlines()] - migrate = steps.index("docker compose --profile migrate run --rm migrate") - - assert "generate and commit the baseline first" in result.output - assert "database/migrations.md" in result.output - assert steps.index("docker compose build") < migrate < steps.index("docker compose up -d") - - -def test_the_local_next_steps_just_start_the_stack(project): - result = runner.invoke(deploy.app, ["local", "-o", str(project), "--yes"]) - - assert result.exit_code == 0, result.output - assert "docker compose up --build" in result.output - assert "migrate" not in result.output diff --git a/cli/tests/test_env_command.py b/cli/tests/test_env_command.py deleted file mode 100644 index 0be6adbe..00000000 --- a/cli/tests/test_env_command.py +++ /dev/null @@ -1,216 +0,0 @@ -"""``bp env``: what it reports about a configuration, and what it refuses.""" - -import secrets -import warnings -from types import SimpleNamespace - -import pytest -from typer.testing import CliRunner - -import cli.app -from cli import plugins -from cli.commands import env - -runner = CliRunner() - - -def _backend_settings(**overrides): - """The app's own settings object, as the command builds it. - - ``CREATE_TABLES_ON_STARTUP``, ``EMAIL_BACKEND`` and ``FRONTEND_URL`` are passed in because - their defaults describe a development environment, not the production one these stand for. - """ - module = env._app_module("src.infrastructure.config.settings") - fields = { - "ENVIRONMENT": "production", - "CREATE_TABLES_ON_STARTUP": False, - "EMAIL_BACKEND": "smtp", - "FRONTEND_URL": "https://app.example.com", - } - - return module.Settings(**(fields | overrides)) - - -def _settings_module_answering(settings) -> SimpleNamespace: - """The settings module as the command uses it: the settings it asks for, and the enum it reads.""" - module = env._app_module("src.infrastructure.config.settings") - - return SimpleNamespace(get_settings=lambda: settings, EnvironmentOption=module.EnvironmentOption) - - -@pytest.fixture -def audited(monkeypatch): - """Answer the command with a validator whose audit we control, and collect what it was handed.""" - - def audit_returning(errors: list[str], warnings: list[str]) -> list: - handed: list = [] - - class _Validator: - def __init__(self, settings): - handed.append(settings) - self.settings = settings - - def audit(self): - return errors, warnings - - def _is_production(self): - return True - - module = SimpleNamespace(ProductionSecurityValidator=_Validator) - settings = SimpleNamespace(ENVIRONMENT="development") - settings.model_copy = lambda update: SimpleNamespace(**(vars(settings) | update)) - answered = _settings_module_answering(settings) - monkeypatch.setattr(env, "_app_module", lambda name: module if "production_validator" in name else answered) - - return handed - - return audit_returning - - -def test_warnings_are_reported_even_when_something_is_critical(audited): - """The warnings used to be computed only when nothing critical was found.""" - audited(["SECRET_KEY is using a default value"], ["Redis has no password"]) - - result = runner.invoke(env.app, ["validate"]) - - assert result.exit_code == 1 - assert "SECRET_KEY" in result.output - assert "Redis has no password" in result.output - - -def test_warnings_alone_do_not_fail_the_command(audited): - audited([], ["Redis has no password"]) - - result = runner.invoke(env.app, ["validate"]) - - assert result.exit_code == 0 - assert "Redis has no password" in result.output - - -def test_a_clean_configuration_says_so(audited): - audited([], []) - - result = runner.invoke(env.app, ["validate"]) - - assert result.exit_code == 0 - assert "No issues found" in result.output - - -def test_the_audited_settings_carry_the_environment_as_the_app_reads_it(audited): - """The app factory and the logger read ``ENVIRONMENT.value``, which a plain string has not.""" - handed = audited([], []) - - result = runner.invoke(env.app, ["validate"]) - - assert result.exit_code == 0 - assert handed[0].ENVIRONMENT.value == "production" - - -def test_gen_secret_produces_a_key_the_validator_accepts(): - """The command is what operators run to satisfy the validator, so ask the validator.""" - result = runner.invoke(env.app, ["gen-secret"]) - key = result.output.strip() - - settings = _backend_settings(SECRET_KEY=key) - validator_module = env._app_module("src.infrastructure.security.production_validator") - - assert result.exit_code == 0 - assert len(key) == 64 - assert not validator_module.ProductionSecurityValidator(settings)._is_insecure_secret_key() - - -REFUSED_BY_THE_APP = "e48102bfe6ac2eac3aa8623456789a6030e4fa7dee3cd173bfb7941f2f819678" - - -def test_a_key_the_app_would_refuse_is_drawn_again(monkeypatch): - """One hex key in twelve million runs through eight digits, which production refuses.""" - accepted = secrets.token_hex(32) - draws = iter([REFUSED_BY_THE_APP, accepted]) - monkeypatch.setattr(env.secrets, "token_hex", lambda size: next(draws)) - - result = runner.invoke(env.app, ["gen-secret"]) - - assert result.exit_code == 0 - assert result.output.strip() == accepted - - -def test_the_first_draw_is_printed_outside_a_project(monkeypatch, tmp_path): - """Nothing to ask: the rules live in the project, and the command still answers.""" - monkeypatch.chdir(tmp_path) - - result = runner.invoke(env.app, ["gen-secret"]) - - assert result.exit_code == 0 - assert len(result.output.strip()) == 64 - - -def test_a_plugin_warning_is_written_to_stderr(capsys): - """On stdout it would corrupt whatever the caller is piping command output into.""" - plugins.emit_plugin_warnings_to_stderr() - - warnings.showwarning("entry point 'acme' failed to load", RuntimeWarning, "plugins.py", 1) - captured = capsys.readouterr() - - assert "acme" in captured.err - assert captured.out == "" - - -def test_mounting_the_plugins_routes_their_warnings(monkeypatch): - routed: list[bool] = [] - monkeypatch.setattr(plugins, "emit_plugin_warnings_to_stderr", lambda: routed.append(True)) - - cli.app._mount_command_plugins() - - assert routed == [True] - - -@pytest.fixture -def real_validator(monkeypatch): - """The command with the app's own validator, against settings the test picks.""" - validator_module = env._app_module("src.infrastructure.security.production_validator") - - def with_settings(**overrides): - answered = _settings_module_answering(_backend_settings(**overrides)) - monkeypatch.setattr(env, "_app_module", lambda name: validator_module if "production_validator" in name else answered) - - return with_settings - - -def test_validate_runs_the_real_validator_against_a_weak_configuration(real_validator): - """The stubs above pin the report's shape; this pins that the command really audits.""" - real_validator(SECRET_KEY="insecure-secret-key-change-this", POSTGRES_PASSWORD="postgres") - - result = runner.invoke(env.app, ["validate"]) - - assert result.exit_code == 1 - assert "SECRET_KEY" in result.output - assert "Database is using default credentials" in result.output - - -def test_every_finding_names_the_environment_being_audited_for(real_validator): - """The command audits as production, so a finding that names a development one is a lie.""" - real_validator(ENVIRONMENT="development", EMAIL_BACKEND="console", CREATE_TABLES_ON_STARTUP=True) - - result = runner.invoke(env.app, ["validate"]) - - assert "in production" in result.output - assert "in development" not in result.output - - -def test_validate_reports_a_strong_configuration_as_clean(real_validator): - """The real validator, with nothing to complain about.""" - real_validator( - SECRET_KEY=secrets.token_hex(32), - POSTGRES_PASSWORD="a-strong-database-password", - CORS_ORIGINS="https://app.example.com", - ADMIN_ENABLED=False, - DEBUG=False, - OPENAPI_URL="", - CACHE_REDIS_PASSWORD="redis-password", - RATE_LIMITER_REDIS_PASSWORD="redis-password", - SESSION_SECURE_COOKIES=True, - ) - - result = runner.invoke(env.app, ["validate"]) - - assert result.exit_code == 0, result.output diff --git a/docs/assets/build-diagrams.cjs b/docs/assets/build-diagrams.cjs index 5a26d110..15731d62 100644 --- a/docs/assets/build-diagrams.cjs +++ b/docs/assets/build-diagrams.cjs @@ -23,7 +23,7 @@ const marker = (line) => ` `; -const compositionRoot = ({ primary, body, muted, line, panel }) => ` +const compositionRoot = ({ primary, body, muted, line, panel }) => ` ${marker(line)} THE COMPOSITION ROOT @@ -52,7 +52,7 @@ const compositionRoot = ({ primary, body, muted, line, panel }) => ` contributes - + app.pyROUTER_MOUNTS, LIFECYCLES settings.pythe settings mixins @@ -64,6 +64,8 @@ const compositionRoot = ({ primary, body, muted, line, panel }) => `tables.pyTABLE_MODULES transports.pyEXTRA_TRANSPORTS cache.pycached + scope.pySCOPE_FINGERPRINT + signup.pyNEW_ACCOUNT_FIELDS @@ -80,9 +82,9 @@ const compositionRoot = ({ primary, body, muted, line, panel }) => `imports the task modules - - The wiring imports every feature. No feature imports another, and nothing imports the wiring back. - written by tools/removal_drill.py from the feature manifest · compared with what it writes by tests/unit/test_removal_drill.py + + The wiring imports every feature. No feature imports another, and nothing imports the wiring back. + written by tools/removal_drill.py from the feature manifest · compared with what it writes by tests/unit/test_removal_drill.py `; const removalDrill = ({ primary, body, muted, line, panel }) => ` diff --git a/docs/changelog.md b/docs/changelog.md index 32ad0a17..a346835b 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -12,11 +12,87 @@ ___ #### Changed +- **Settings read the environment when they're built, not when the module is imported.** Every + settings class derives from `EnvSettings` (`src/infrastructure/config/base.py`), whose fields + carry plain defaults; the environment and `backend/.env` are read each time a class is built. A + test that deletes a variable now gets the field's default rather than the value the process + started with, and `CREATE_TABLES_ON_STARTUP` follows the `ENVIRONMENT` the settings are built + with. Every value is the same as before with no environment and with `.env.example`, and + values are read as they always were, in the environment and in the file: a flag is `true`, + `false`, `1` or `0` in any case, a number is what `int()` reads, and the file is taken + literally, names exactly as written, with no `${...}` expansion. A string handed to a settings + class's constructor is held to the same rule now, so `Settings(DEBUG="yes")`, which pydantic + used to read as true, is refused. A mixin of your own derives from `EnvSettings` in + `src.infrastructure.config.base`. + `config` is still exported from `src.infrastructure.config.settings`, so a settings class of + your own written as `config("NAME", default=...)` keeps working, with the old import-time + reading. +- **`fastro make deploy` renders this repository's `[generators.deploy]`.** The files are the ones + `bp deploy generate` wrote, apart from the header, which names `fastro make deploy `, and + the compose project name, which is the project's slug, `fastapi-boilerplate`. Every + `--internal-subnet` value is checked in every mode, and a bad one exits 2. Make prints + `wrote`, `unchanged` or `kept` per file, replaces a file that differs only after you confirm or + with `--force`/`--yes`, and with no terminal keeps it and exits 0. It runs in the blueprint + repository only for now. `fastro env validate` exits 2 and says why outside a project, where it + used to exit 1. +- **The tracing recipe registers its installer in `fastro.toml`.** + [Observability](user-guide/observability.md) used to have you call `configure_tracing()` and add + the installer in `src/interfaces/main.py`. Now `install()` configures tracing itself, and you + list it under `[app.contributes]` and run `fastro sync`, which adds it to the generated + `src/wiring/app.py`. +- **FastAPI is capped below 0.140.7.** The app imports `get_flat_dependant` from + `fastapi.dependencies.utils`, which 0.140.7 removed, and passes `openapi_prefix` to `FastAPI`, + which 0.145.0 refuses. A project resolves its own dependencies, so without the cap a new one got + the newest FastAPI and couldn't import the app. The lock still holds 0.136.1. A later release + moves off both and lifts the cap. - **`virtualenv` 21.14.13 and `filelock` 4.2.4**, for eighteen advisories published against the versions the lock held. Both arrive through `pre-commit`, which lives in the `dev` extra, so the image installs neither and a deployment is unaffected: the advisories are about the environments a hook runs in and the lock files it takes, on the machines that run the hooks. `pre-commit run --all-files` passes on the new versions. +- **`faker` and `httpx` are development dependencies now**, because only the tests import them. + The image installs the runtime list with `--no-dev`, so `faker` is no longer in it: code of your + own that imported it there has to declare it. `httpx` still arrives in the image through + `fastapi[standard]`, which requires it, so only `faker` actually leaves. +- **`aiosqlite` is gone and `jinja2` is a development dependency.** Nothing imported either: + `aiosqlite` answered `SQLITE_ASYNC_PREFIX`, which no module reads, and the admin panel gets + `jinja2` through `sqladmin`, which requires it. `jinja2` stays in the `dev` extra for the + template tests. A project of your own that imported either has to declare it. +- **`.env.example` ships `ADMIN_ENABLED=false`.** The setting has defaulted to `false` since + 0.20.0, but the example still turned the panel on, so a copied example served `/admin` with the + example's own `admin` credentials. Set `ADMIN_ENABLED=true`, with credentials of your own, where + you want it. +- **The CLI docs are one page about fastro now.** The `CLI` section's Overview, Commands and + Plugins pages are gone, and + [Generating and updating projects with fastro](user-guide/fastro.md) covers `fastro make deploy`, + `fastro env secret` and `fastro env validate`. The old `cli/` URLs redirect there. + +#### Removed + +- **The `bp` CLI and its `cli/` workspace package.** fastro, which the root dev group installs, + runs the same commands: `bp deploy generate MODE` is `fastro make deploy MODE`, with the same + modes and options; `bp env gen-secret` is `fastro env secret`; `bp env validate` is + `fastro env validate`. fastro installs a `bp` command too, which says it is now fastro and runs + the fastro command, so `uv run bp ...` keeps working. In a venv that had the old package, + `uv sync --all-packages --all-extras --reinstall-package fastro` puts that command back after + the sync removes the old one. The `bp.commands` and `bp.features` plugin entry points have no + counterpart in fastro. The workspace's one member is `backend/` now. +- **The removal drill.** `tools/removal_drill.py` and its test are gone. `fastro blueprint verify` + builds a project for each set in `blueprint.toml`, each preset and `everything`, and runs the + same checks on it; CI runs it once per set. Run `uv run --no-sync fastro blueprint verify` for + every set, or name one, and add `--keep` to keep the builds. + +#### Fixed + +- **A project with the cache feature and without accounts imports.** The cache used to import the + accounts feature's scope fingerprint to key a scoped credential apart from its account. Accounts + now contributes it through `SCOPE_FINGERPRINT` in the generated `src/wiring/scope.py`, which is + `None` without accounts. A project with per-tier rate limits and without the cache no longer + ships `tests/integration/tier_limits/test_cached_listing.py`, which imported the cache. +- **A new account is given the default tier.** The signup route said it assigned one, and neither + it nor a provider's first sign-in did. With the tiers feature, both now give a new account the + tier `DEFAULT_TIER_NAME` names, through `NEW_ACCOUNT_FIELDS` in the generated + `src/wiring/signup.py`. While no such tier exists, or it is deleted, the account has none. ___ diff --git a/docs/cli/commands.md b/docs/cli/commands.md deleted file mode 100644 index 842e4708..00000000 --- a/docs/cli/commands.md +++ /dev/null @@ -1,208 +0,0 @@ -# Commands - -Complete reference for the in-tree `bp` commands. Plugin commands have their own help text — see [Plugins](plugins.md). - -## `bp deploy` - -Generate deployment artifacts. Today's only sub-command is `generate`. - -### `bp deploy generate ` - -Render `docker-compose.yml` (and `nginx/default.conf` for `nginx` mode) for the chosen deployment shape. - -```text -Usage: bp deploy generate [OPTIONS] MODE - -Arguments: - MODE {local|prod|nginx} [required] - -Options: - -o, --output-dir DIRECTORY Where to write the compose file (default: repo root). - --api-port INTEGER Host port to publish the API on. [default: 8000] - --workers INTEGER Number of API workers (prod / nginx only). [default: 4] - --internal-subnet TEXT Subnet for the compose network, and the only peers uvicorn - takes forwarded headers from (nginx only). - [default: 172.31.240.0/24] - -f, --force Overwrite existing files without asking. - -y, --yes Assume yes for all prompts. - --dry-run Show what would be written, don't touch disk. -``` - -#### Modes - -| Mode | Stack | Use for | -|---------|--------------------------------------------------------------------------|----------------------------------------| -| `local` | API (target `dev`) + Postgres + Redis. Source mounted, hot-reload. | Local development | -| `prod` | API (target `prod`, `WORKERS` env) + Postgres + Redis + a `migrate` one-shot. | Single-host production, no proxy | -| `nginx` | `prod` + nginx reverse proxy on port 80. API exposed on internal network. | Production behind a reverse proxy | - -Every mode also gets a taskiq `worker` and a single `scheduler`, for a project that carries the -taskiq feature; a project without it gets neither. - -All modes target the same multi-stage `backend/Dockerfile` — no per-mode Dockerfile is generated. - -The `migrate` service sits behind a compose profile and nothing waits on it, so `docker compose up` -never migrates. Run it, then restart: - -```bash -docker compose --profile migrate run --rm migrate -docker compose up -d -``` - -In that order a migration that fails leaves the old containers serving on the old schema, instead of -restarting the API into a schema it can't use. - -#### Examples - -```bash -# Generate the dev stack at the repo root -uv run --no-sync bp deploy generate local - -# Override workers and port -uv run --no-sync bp deploy generate prod --workers 8 --api-port 9000 - -# Dry run — print what would be written, don't touch disk -uv run --no-sync bp deploy generate nginx --output-dir /tmp/scratch --dry-run - -# Generate into a separate directory (for staging configs in CI, etc.) -uv run --no-sync bp deploy generate prod --output-dir ./deploy/prod --yes - -# Put the stack on another range when 172.31.240.0/24 clashes with a network you use -uv run --no-sync bp deploy generate nginx --internal-subnet 10.89.0.0/24 -``` - -`--internal-subnet` has to name a network address of `/8` or smaller for IPv4, `/48` or smaller for IPv6: it is written both as the -compose network's `ipam` subnet and as `FORWARDED_ALLOW_IPS` for the API container, which decides -whose `X-Forwarded-For` and `X-Forwarded-Proto` the app believes. A value with host bits set -(`172.31.240.1/24`), a wildcard, or a wider range is refused before anything is written. - -#### What it writes - -| Mode | Files | -|---------|------------------------------------------------| -| `local` | `/docker-compose.yml` | -| `prod` | `/docker-compose.yml` | -| `nginx` | `/docker-compose.yml`
`/nginx/default.conf` | - -Existing files are protected: if a target already exists you'll be prompted to confirm overwrite. Use `--force` (or `--yes`) for non-interactive runs. - -#### Generated compose conventions - -All three modes use the same service names and networking: - -- **`api`** — the FastAPI application -- **`worker`** (taskiq feature) — Taskiq worker, running `taskiq worker src.infrastructure.taskiq.worker:default_broker` -- **`scheduler`** (taskiq feature) — one Taskiq scheduler, running `taskiq scheduler src.infrastructure.taskiq.scheduler:scheduler` -- **`postgres`** — Postgres 16 (alpine), with health check -- **`redis`** — Redis 7 (alpine), with health check -- **`migrate`** (prod & nginx) — runs `alembic upgrade head` once, with `CONFIRM_PRODUCTION_MIGRATION=yes`, behind the `migrate` profile. Nothing depends on it: a deploy runs it and only then restarts the rest. -- **`nginx`** (nginx mode only) — Nginx 1.27 alpine, mounting the generated `nginx/default.conf` read-only - -The compose file references `./backend/.env` for env vars. Make sure that file exists (`cp backend/.env.example backend/.env`) before `docker compose up`. - -## `bp env` - -Inspect and prepare the runtime environment. Two sub-commands today. - -### `bp env gen-secret` - -Generate a high-entropy hex secret suitable for `SECRET_KEY`. - -```text -Usage: bp env gen-secret [OPTIONS] - -Options: - --bytes INTEGER RANGE [16 ≤ x ≤ 128] Number of random bytes (hex output is 2x). [default: 32] -``` - -```bash -$ uv run --no-sync bp env gen-secret -af97045f600bf988041ec4b6fd891763d8f79f01f0a0a4a7ed2022e57f771a9e - -$ uv run --no-sync bp env gen-secret --bytes 16 -c042a8aa0d678a9c73dc371e3e0d6a5e -``` - -The default produces 64 hex characters (256 bits of entropy) — enough for any of the boilerplate's secret slots (`SECRET_KEY`, signed-cookie secrets, etc.). - -Run inside a project, the command checks each draw against the app's own secret-key rules and draws again while they would refuse it: about one hex key in 12.6 million runs through eight consecutive digits, which production refuses at startup. Run outside a project, where those rules aren't there to ask, it prints the first draw. - -Pipe directly into your secrets manager: - -```bash -uv run --no-sync bp env gen-secret | gh secret set SECRET_KEY --repo my-org/my-app -``` - -### `bp env validate` - -Run the production security validator against your current settings, regardless of `ENVIRONMENT`. - -```text -Usage: bp env validate -``` - -```bash -$ uv run --no-sync bp env validate -Critical (2): - • SECRET_KEY is using default or insecure value. ... - • Database is using default credentials (POSTGRES_PASSWORD='postgres'). ... -``` - -The command: - -1. Imports the same `ProductionSecurityValidator` the application uses at startup -2. Audits a copy of your settings whose `ENVIRONMENT` reads `production`, so the checks run whatever - the configured environment is and a finding that names an environment names the one audited for -3. Captures critical errors and warnings, prints them grouped, and exits non-zero if any critical issues exist - -Exit codes: - -| Code | Meaning | -|------|------------------------------------------------------| -| 0 | No critical issues. Warnings (if any) are advisory. | -| 1 | One or more critical issues found. | - -Useful in CI to gate deployments: - -```yaml -# .github/workflows/deploy.yml (excerpt) -- run: uv run --no-sync bp env validate - env: - SECRET_KEY: ${{ secrets.SECRET_KEY }} - POSTGRES_PASSWORD: ${{ secrets.POSTGRES_PASSWORD }} - # ... -``` - -The validator's specific checks are documented in [Production → The Production Validator](../user-guide/production.md#the-production-validator). - -## Global Options - -Typer-provided options work on any sub-command: - -| Option | Effect | -|-------------------------|-----------------------------------------------------| -| `--help` | Show command help and exit | -| `--install-completion` | Install shell completion (bash/zsh/fish) | -| `--show-completion` | Print completion script for the current shell | - -## Exit Codes - -| Code | Meaning | -|------|------------------------------------------------------| -| 0 | Success | -| 1 | Validation or operation failed | -| 2 | Argument parsing error (bad flag, missing argument) | - -## Discoverability - -Every command has `--help`: - -```bash -uv run --no-sync bp --help -uv run --no-sync bp deploy --help -uv run --no-sync bp deploy generate --help -uv run --no-sync bp env --help -uv run --no-sync bp env validate --help -``` - -The root `bp --help` lists every mounted command group, including those contributed by plugins. If a plugin you installed isn't showing up, see [Plugins → Troubleshooting](plugins.md#troubleshooting). diff --git a/docs/cli/index.md b/docs/cli/index.md deleted file mode 100644 index 04195999..00000000 --- a/docs/cli/index.md +++ /dev/null @@ -1,109 +0,0 @@ -# bp — the FastAPI-boilerplate CLI - -`bp` is the developer/operator tool that ships alongside the boilerplate. It generates deployment artifacts, helps prepare the runtime environment, and serves as the host for plugin commands and feature generators. - -It is **not** part of the deployable backend. The backend image stays lean — `bp` lives in its own workspace package (`cli/`) and is only present in development environments and on machines where you've installed it as a tool. - -## What's in this section - -- **[Commands](commands.md)** — complete reference for the in-tree `deploy` and `env` sub-apps -- **[Plugins](plugins.md)** — extension points (`bp.commands` and `bp.features`) and authoring guide - -## Repository Layout - -```text -fastapi-boilerplate/ -├── pyproject.toml # workspace root (uv workspace metadata) -├── backend/ # deployable application — never ships bp -│ └── src/... -├── cli/ # the bp package -│ ├── pyproject.toml # typer + jinja2 + workspace dep on backend -│ └── src/cli/ -│ ├── app.py # Typer root + plugin discovery -│ ├── commands/ # in-tree command sub-apps -│ ├── features/ # feature framework + in-tree features -│ └── plugins.py # entry-point loaders -└── docs/ -``` - -The two-package split is deliberate: `cli/` depends on `backend/` (for things like `bp env validate`), but `backend/` never depends on `cli/`. Production images ship `backend/` only. - -## Install - -### In-repo (most common) - -```bash -git clone https://github.com/benavlabs/fastapi-boilerplate -cd fastapi-boilerplate -uv sync --all-packages --all-extras # one venv with the backend, the cli and the dev tools -uv run --no-sync bp --help # works from anywhere in the repo -``` - -The workspace shares a single `.venv/` at the repo root. You can run `uv run --no-sync bp` from any subdirectory — uv walks up to find the workspace root. - -### Machine-wide (optional) - -If you want `bp` on `PATH` outside the repo: - -```bash -uv tool install --editable ./cli -bp --help -``` - -`--editable` means edits to `cli/src/cli/` show up immediately without reinstall. Re-run `uv tool install --editable ./cli` only when `cli/pyproject.toml` changes (deps, entry points). To uninstall: - -```bash -uv tool uninstall fastapi-boilerplate-cli -``` - -## Quick Tour - -### Generate a Compose File - -```bash -uv run --no-sync bp deploy generate local # hot-reload dev stack -uv run --no-sync bp deploy generate prod --workers 8 # production stack -uv run --no-sync bp deploy generate nginx # production behind nginx -``` - -Each command writes `docker-compose.yml` (and `nginx/default.conf` for the nginx mode) to the repo root by default. Use `--output-dir` to target somewhere else. - -### Generate a Secret - -```bash -uv run --no-sync bp env gen-secret -# → 64-char hex suitable for SECRET_KEY -``` - -### Audit Production Settings - -```bash -uv run --no-sync bp env validate -# Forces the production security validator regardless of ENVIRONMENT. -# Exits 1 if any critical issues are found. -``` - -## Command Tree - -```text -bp -├── deploy -│ └── generate [options] # mode ∈ {local, prod, nginx} -└── env - ├── gen-secret [--bytes N] - └── validate -``` - -Plugin sub-apps mount as siblings of `deploy` and `env`. See [Plugins](plugins.md) for details. - -## Design Principles - -- **No surprises in production.** `bp` never runs against production at runtime — it's a developer/operator tool. Production images don't even include the `cli` package. -- **Two extension points, kept separate.** Command plugins (Typer sub-apps) and feature plugins (code generators with manifests) have different lifecycles and shouldn't share machinery. -- **Templates as data.** Built-in features render Jinja templates. Plugin features do the same. The installer is the only thing that needs to know how to execute the plan. -- **Idempotent and dry-runnable.** Every operation that mutates the user's repo prompts before overwriting and supports `--dry-run`. - -## Next Steps - -- **[Commands](commands.md)** — full reference for the shipped commands -- **[Plugins](plugins.md)** — write your own commands or features diff --git a/docs/cli/plugins.md b/docs/cli/plugins.md deleted file mode 100644 index bd65599d..00000000 --- a/docs/cli/plugins.md +++ /dev/null @@ -1,334 +0,0 @@ -# Plugins - -`bp` has two extension points, kept deliberately separate. They have different lifecycles and shouldn't share machinery: - -- **Command plugins** (`bp.commands`) — third-party Typer sub-apps mounted under the root, e.g. `bp aws deploy`. Pure CLI surface; the plugin doesn't touch the user's repo. -- **Feature plugins** (`bp.features`) — code generators with a manifest that `bp feature` can list, install, and remove. Plugins of this kind mutate the user's repo (write files, edit settings, run hooks). - -Both are discovered via [Python entry points](https://packaging.python.org/en/latest/specifications/entry-points/), so a plugin is just a normal Python package on the user's machine. - -## How Discovery Works - -When `bp` starts, the root app: - -1. Mounts in-tree command sub-apps (`deploy`, `env`) -2. Calls `discover_command_plugins()` (from `cli.plugins`) which walks `entry_points(group="bp.commands")` and mounts each healthy result -3. Builds the feature registry on demand: in-tree features merged with `discover_feature_plugins()` from `bp.features` - -A broken plugin never breaks `bp`. Discovery wraps each load in `try/except`, surfaces a `RuntimeWarning`, and continues with the working subset. - -```python -# cli/src/cli/plugins.py (abridged) -def _safe_load(ep: EntryPoint) -> object | None: - try: - return ep.load() - except Exception as exc: - warnings.warn(f"Failed to load plugin {ep.name!r}: {exc}", RuntimeWarning) - return None -``` - -In-tree commands and features take precedence on name collisions — a plugin can't silently shadow a built-in. - -## Command Plugins - -Use a command plugin when you want to add new top-level verbs to `bp` without modifying the boilerplate. Examples: `bp fly deploy`, `bp pulumi up`, `bp lint custom-rules`. - -### Authoring a Command Plugin - -Create a Python package with a `typer.Typer` instance and register it under the `bp.commands` group. - -#### 1. Package layout - -```text -bp-deploy-fly/ -├── pyproject.toml -└── src/ - └── bp_deploy_fly/ - ├── __init__.py - └── cli.py -``` - -#### 2. `cli.py` — define the sub-app - -```python -import typer - -app = typer.Typer( - name="fly", - help="Deploy this app to Fly.io.", - no_args_is_help=True, -) - - -@app.command("deploy") -def deploy( - region: str = typer.Option("ord", help="Fly region to target."), - yes: bool = typer.Option(False, "--yes", "-y"), -) -> None: - """Build and deploy the current branch to Fly.io.""" - typer.echo(f"deploying to fly region={region}") - # ... real work here ... -``` - -#### 3. `pyproject.toml` — declare the entry point - -```toml -[project] -name = "bp-deploy-fly" -version = "0.1.0" -requires-python = ">=3.11" -dependencies = ["typer>=0.12"] - -[project.entry-points."bp.commands"] -fly = "bp_deploy_fly.cli:app" - -[tool.setuptools.packages.find] -where = ["src"] -``` - -The entry-point key (`fly`) becomes the sub-command name. The value (`bp_deploy_fly.cli:app`) is the import path to your `Typer` instance. - -#### 4. Install and use - -```bash -uv pip install bp-deploy-fly -uv run --no-sync bp --help -# ╭─ Commands ────────────────────────────────────────────────╮ -# │ deploy Generate deployment artifacts ... │ -# │ env Inspect and prepare the runtime environment. │ -# │ fly Deploy this app to Fly.io. ← new │ -# ╰───────────────────────────────────────────────────────────╯ - -uv run --no-sync bp fly deploy --region ord --yes -``` - -### Best Practices for Command Plugins - -- **Pick a unique name.** `bp` warns if you collide with a built-in (`deploy`, `env`, `feature`) and ignores you. Pick something specific (`fly`, `aws`, `pulumi`) rather than generic (`cloud`, `tools`). -- **Keep your sub-app self-contained.** Don't import from the host CLI's internals — use only the public Typer interface. The `cli.app` module is not a public API. -- **Honor the global UX patterns.** Support `--yes` for non-interactive runs and `--dry-run` where it makes sense. Match the style of the in-tree commands. -- **Don't block on broken external dependencies.** If your plugin needs `flyctl` or `kubectl`, check for it gracefully and surface a useful error — not a stack trace from `subprocess`. - -## Feature Plugins - -Use a feature plugin when you want to **mutate the user's repo** — drop in a new module, add OAuth providers, wire up a payments integration, write migrations. Features have a manifest, plan, and installer lifecycle so they can apply, list, and (eventually) revert cleanly. - -!!! note "Feature plugins are designed for, but not yet wired to, `bp feature`" - The feature framework (`Feature`, `FeatureManifest`, `FeaturePlan`, `FeatureInstaller`) is fully implemented and the registry already discovers plugin features. The user-facing `bp feature` sub-app is not yet shipped — features are reachable today only via in-tree commands like `bp deploy generate`. The contract below is stable; once `bp feature {list,add,remove,info}` lands, your plugins will work without changes. - -### The Feature Contract - -A feature is a class that subclasses `cli.features.base.Feature`: - -```python -from cli.features.base import Feature, FeatureManifest, FeaturePlan, FileOp -from cli.lib.project import ProjectContext - - -class MyFeature(Feature): - def manifest(self) -> FeatureManifest: - return FeatureManifest( - name="my-feature", - version="1.0", - summary="One-line description shown by `bp feature list`.", - ) - - def plan(self, params: dict, project: ProjectContext) -> FeaturePlan: - return FeaturePlan( - manifest=self.manifest(), - templates_root=Path(__file__).parent / "templates", - template_context={"project_name": project.repo_root.name, **params}, - files=( - FileOp(template="my_module.py.j2", - target=project.backend_dir / "src/modules/my_feature/__init__.py"), - # ... more files ... - ), - ) -``` - -Two methods, both required: - -- **`manifest()`** — static metadata. Called by registry / list operations without executing anything. -- **`plan(params, project)`** — given runtime parameters and a `ProjectContext`, return a concrete `FeaturePlan`. - -### The Plan Schema - -```python -@dataclass(frozen=True) -class FeaturePlan: - manifest: FeatureManifest - templates_root: Path | None - template_context: dict[str, Any] = field(default_factory=dict) - files: tuple[FileOp, ...] = () - codemods: tuple[Codemod, ...] = () # reserved for v2 — installer raises NotImplementedError - hooks: tuple[Hook, ...] = () # reserved for v2 — installer raises NotImplementedError -``` - -The schema covers today's "render Jinja templates to disk" and tomorrow's "mutate code + run a migration". Defining `Codemod` and `Hook` types now means feature plugins can declare them without breaking the contract when the installer learns to execute them. - -#### `FileOp` - -```python -@dataclass(frozen=True) -class FileOp: - template: str # path relative to templates_root - target: Path # absolute path on disk - overwrite: bool = False - skip_if_exists: bool = False - executable: bool = False -``` - -The installer renders `template` with the plan's `template_context` and writes the result to `target`. If the target exists: - -| Flags | Behavior | -|--------------------------|-------------------------------------------------------------| -| Default | Prompt the user before overwriting | -| `overwrite=True` | Overwrite without asking | -| `skip_if_exists=True` | Skip silently (preserves user customizations) | - -`executable=True` chmods the result with `+x` for owner/group/world. - -### Authoring a Feature Plugin - -#### 1. Package layout - -```text -bp-feature-audit-log/ -├── pyproject.toml -└── src/ - └── bp_feature_audit_log/ - ├── __init__.py - ├── feature.py - └── templates/ - └── audit_log_module.py.j2 -``` - -#### 2. `feature.py` — define the feature - -```python -from pathlib import Path - -from cli.features.base import Feature, FeatureManifest, FeaturePlan, FileOp -from cli.lib.project import ProjectContext - - -class AuditLogFeature(Feature): - def manifest(self) -> FeatureManifest: - return FeatureManifest( - name="audit-log", - version="1.0", - summary="Drop in an audit-log module that records mutating requests.", - ) - - def plan(self, params: dict, project: ProjectContext) -> FeaturePlan: - templates_root = Path(__file__).parent / "templates" - module_path = ( - project.backend_dir - / "src/modules/audit_log/models.py" - ) - return FeaturePlan( - manifest=self.manifest(), - templates_root=templates_root, - template_context={ - "retention_days": params.get("retention_days", 90), - }, - files=( - FileOp(template="audit_log_module.py.j2", target=module_path), - ), - ) - - -# Entry-point target — can be a Feature instance or a callable that returns one. -feature = AuditLogFeature() -``` - -A feature plugin writes into a directory that still exists in the layout — that's why this example targets `src/modules//` rather than the old `auth/oauth/providers/` path. OAuth providers are no longer separate files: they're configured with crudauth's `OAuthCredentials` in `infrastructure/auth/setup.py`, so an "add an OAuth provider" plugin would edit that file (e.g. via an idempotent patch op) instead of dropping in a new module. - -#### 3. `pyproject.toml` — declare the entry point - -```toml -[project] -name = "bp-feature-audit-log" -version = "0.1.0" -requires-python = ">=3.11" -dependencies = ["fastapi-boilerplate-cli"] - -[project.entry-points."bp.features"] -audit-log = "bp_feature_audit_log.feature:feature" - -[tool.setuptools] -include-package-data = true - -[tool.setuptools.packages.find] -where = ["src"] - -[tool.setuptools.package-data] -"*" = ["*.j2"] -``` - -Note `include-package-data = true` and the `package-data` glob — without these, your Jinja templates won't ship with the wheel. - -#### 4. Install - -```bash -uv pip install bp-feature-audit-log -# Once `bp feature` ships: -# uv run --no-sync bp feature add audit-log --retention-days 90 -``` - -### Best Practices for Feature Plugins - -- **Be idempotent.** A user running your feature twice should be safe. Use `skip_if_exists=True` for files that the user might customize after first install. -- **Don't fight the user's structure.** Use `ProjectContext.backend_dir` and `ProjectContext.repo_root` rather than hardcoded paths — different projects may move things. -- **Declare every file.** Don't write files outside the plan. The installer's behavior (dry-run, idempotency, overwrite prompts) only works for files declared in the plan. -- **Put templates next to the feature.** `Path(__file__).parent / "templates"` is the canonical pattern. Keeps the plugin self-contained. -- **Use Jinja's `StrictUndefined`.** The bundled `Renderer` does this for you — missing context variables fail loudly rather than rendering empty strings. -- **Document required `params`.** Once `bp feature` lands, your manifest's `summary` is the first thing users see; document params clearly there. - -## Discovery & Diagnosis - -### Listing Plugins - -```bash -# In-tree + plugin commands -uv run --no-sync bp --help - -# (Once shipped) — list features: -# uv run --no-sync bp feature list -``` - -### Inspecting Entry Points - -```bash -uv run --no-sync python -c " -from importlib.metadata import entry_points -for ep in entry_points(group='bp.commands'): - print(f'command {ep.name:>15s} -> {ep.value}') -for ep in entry_points(group='bp.features'): - print(f'feature {ep.name:>15s} -> {ep.value}') -" -``` - -### Troubleshooting - -#### My plugin doesn't appear in `bp --help` - -1. **Confirm it's installed in the right venv.** Run the entry-point inspection script above. If your plugin isn't listed, the package isn't installed where `bp` runs. -2. **Check for load warnings.** `bp` prints `warning: Failed to load plugin ...` to stderr if your plugin's import fails. Run `bp --help 2>&1` to make sure stderr isn't being suppressed. -3. **Confirm your entry-point shape.** For commands, the value must resolve to a `typer.Typer` instance. For features, a `Feature` instance or a callable returning one. - -#### My plugin shadows a built-in - -`bp` warns and ignores plugins that try to register a name already in use by a built-in (`deploy`, `env`, `feature`). Rename your plugin to a unique key. - -#### My templates aren't shipping in the wheel - -Set `include-package-data = true` in `pyproject.toml` and add a `package-data` glob like `"*" = ["*.j2"]`. Without these, Jinja templates next to your code aren't included in the built wheel. - -## Roadmap - -- **`bp feature {list,add,remove,info}`** — user-facing surface for the feature framework. Currently the registry exists; the commands don't. -- **Codemod execution** — apply AST-aware edits declared in `FeaturePlan.codemods`. Useful for "drop a module + register its router in `interfaces/main.py`" kinds of features. -- **Post-install hooks** — execute commands declared in `FeaturePlan.hooks`. Useful for "after writing the migration, run `alembic upgrade head`" kinds of features. - -The contracts (`Codemod`, `Hook`) are already in `cli.features.base` so plugin authors can declare them today without breaking the schema later. diff --git a/docs/fastro-vs-fastroai.md b/docs/fastro-vs-fastroai.md index 9d67e720..1495753c 100644 --- a/docs/fastro-vs-fastroai.md +++ b/docs/fastro-vs-fastroai.md @@ -1,15 +1,15 @@ -# Fastro vs FastroAI +# FastAPI-boilerplate vs FastroAI -This boilerplate - **Fastro** - is the free, open-source **foundation**: everything you need for a production FastAPI backend. **[FastroAI](https://fastro.ai)** is the paid template built on the same foundation for shipping a **complete SaaS** - Stripe billing (subscriptions, credits, discounts), entitlements, transactional email, and a frontend, all wired together. Building an **AI** product? The PydanticAI agent layer is included too - but every paid feature fits a regular SaaS just as well. +**FastAPI-boilerplate** is the free, open-source **foundation**: everything you need for a production FastAPI backend. **[FastroAI](https://fastro.ai)** is the paid template built on the same foundation for shipping a **complete SaaS** - Stripe billing (subscriptions, credits, discounts), entitlements, transactional email, and a frontend, all wired together. Building an **AI** product? The PydanticAI agent layer is included too - but every paid feature fits a regular SaaS just as well. -| | **Fastro** (this repo · free) | **FastroAI** (paid) | +| | **FastAPI-boilerplate** (this repo · free) | **FastroAI** (paid) | |---|:---:|:---:| | FastAPI + SQLAlchemy 2.0, Pydantic v2 | ✓ | ✓ | | Auth - sessions, OAuth, API keys | ✓ | ✓ **+ JWT** | | FastCRUD · SQLAdmin · Alembic | ✓ | ✓ | | Caching · rate limiting · Taskiq jobs | ✓ | ✓ | | Docker (local / prod / nginx) | ✓ | ✓ | -| `bp` CLI - scaffolding, env audit, plugins | ✓ | | +| fastro - compose scaffolding, env audit | ✓ | | | **Payments** - Stripe: subscriptions, credits, discounts, webhooks | | ✓ | | **Entitlements** - feature gating by plan/tier | | ✓ | | **Transactional email** & notifications | | ✓ | @@ -20,11 +20,11 @@ This boilerplate - **Fastro** - is the free, open-source **foundation**: everyth

- FastroAI - the complete SaaS template: payments, entitlements, email, frontend and AI on top of Fastro - FastroAI - the complete SaaS template: payments, entitlements, email, frontend and AI on top of Fastro + FastroAI - the complete SaaS template: payments, entitlements, email, frontend and AI on top of FastAPI-boilerplate + FastroAI - the complete SaaS template: payments, entitlements, email, frontend and AI on top of FastAPI-boilerplate

-**Stick with Fastro** if you want a clean, hackable FastAPI backend to build on. +**Stick with FastAPI-boilerplate** if you want a clean, hackable FastAPI backend to build on. **[Get FastroAI →](https://fastro.ai)** if you're shipping a SaaS - AI or not - and want billing, entitlements, email, auth, and a frontend ready out of the box, all on the same foundation you already know. diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 97d17c84..b944df61 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -30,8 +30,8 @@ Pick whichever workflow fits you: uv sync --all-packages --all-extras ``` - From the repository root: `--all-packages` installs both workspace members and - `--all-extras` adds the dev tools (ruff, mypy, pytest). + From the repository root: `--all-packages` installs the backend, the workspace's one + member, and `--all-extras` adds the dev tools (ruff, mypy, pytest). ### 3. Environment Setup @@ -55,7 +55,7 @@ Pick whichever workflow fits you: - [Docker](https://docs.docker.com/get-docker/) (20.10+) - [Docker Compose](https://docs.docker.com/compose/install/) (v2+) - - [uv](https://docs.astral.sh/uv/getting-started/installation/) (0.4+), which runs the CLI that writes the compose file + - [uv](https://docs.astral.sh/uv/getting-started/installation/) (0.4+), which runs fastro, the tool that writes the compose file ### 1. Get the Template @@ -68,12 +68,12 @@ Pick whichever workflow fits you: ```bash uv sync --all-packages --all-extras - uv run --no-sync bp deploy generate local + uv run --no-sync fastro make deploy local ``` `docker-compose.yml` is written at the repository root and is not committed, because the stack you want depends on how you deploy. `local` is the hot-reload stack; the other modes - are `prod` and `nginx`, covered in [CLI → Commands](../cli/commands.md). + are `prod` and `nginx`, covered in [Generating and updating projects with fastro](../user-guide/fastro.md). ### 3. Environment Setup @@ -113,7 +113,7 @@ You now have a working FastAPI app with: - Redis-backed cache and rate limiting - Session-based authentication with optional OAuth (Google, GitHub) - API keys with per-key permissions -- SQLAdmin admin interface at `/admin` +- SQLAdmin admin interface at `/admin`, off until you set `ADMIN_ENABLED=true` - Async background task support via Taskiq ## Test Your API diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index ff632704..1d80298f 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -17,7 +17,7 @@ Docker Compose handles every service for you (Postgres + Redis + the app). - [Docker](https://docs.docker.com/get-docker/) (20.10+) - [Docker Compose](https://docs.docker.com/compose/install/) (v2+) -- [uv](https://docs.astral.sh/uv/getting-started/installation/), which runs the CLI that writes the compose file +- [uv](https://docs.astral.sh/uv/getting-started/installation/), which runs fastro, the tool that writes the compose file ### Steps @@ -37,19 +37,19 @@ Docker Compose handles every service for you (Postgres + Redis + the app). 3. **Generate the compose file**: ```bash - uv run --no-sync bp deploy generate local + uv run --no-sync fastro make deploy local ``` `docker-compose.yml` is written at the repo root and is not committed, because the stack you want depends on how you deploy. `local` is the hot-reload stack: API, Taskiq worker, scheduler, Postgres and Redis. The other modes are `prod` and `nginx`, covered in - [CLI → Commands](../cli/commands.md). + [Generating and updating projects with fastro](../user-guide/fastro.md). 4. **Set up the environment file**: ```bash cp backend/.env.example backend/.env - # Edit backend/.env: set SECRET_KEY (`uv run --no-sync bp env gen-secret` prints one), + # Edit backend/.env: set SECRET_KEY (`uv run --no-sync fastro env secret` prints one), # change ADMIN_PASSWORD and the default DB password. ``` @@ -128,7 +128,7 @@ For development on your host machine. You provide PostgreSQL and Redis yourself. cd fastapi-boilerplate ``` - The repo is a [uv workspace](https://docs.astral.sh/uv/concepts/projects/workspaces/) — the deployable application lives in `backend/` and the developer CLI (`bp`) lives in `cli/`. Both share a single virtual environment at the repo root. + The repo is a [uv workspace](https://docs.astral.sh/uv/concepts/projects/workspaces/): the deployable application in `backend/` is its one member, and it shares a single virtual environment at the repo root with fastro and the dev tools. 2. **Install Python dependencies**: @@ -136,21 +136,21 @@ For development on your host machine. You provide PostgreSQL and Redis yourself. uv sync --all-packages --all-extras ``` - This syncs the whole workspace — backend, CLI, and dev tools — into one `.venv/` at the repo root. From here on, `uv run --no-sync ` works from any subdirectory; the flag skips uv's implicit sync, so a command starts immediately and leaves the environment and the lockfile alone. Re-running a plain `uv sync` without `--all-extras` is what removes ruff, mypy and pytest again. + This syncs the backend, fastro and the dev tools into one `.venv/` at the repo root. From here on, `uv run --no-sync ` works from any subdirectory; the flag skips uv's implicit sync, so a command starts immediately and leaves the environment and the lockfile alone. Re-running a plain `uv sync` without `--all-extras` is what removes ruff, mypy and pytest again. 3. **Set up environment variables**: ```bash cp backend/.env.example backend/.env # Edit backend/.env: point POSTGRES_SERVER and CACHE_REDIS_HOST at localhost, - # set a strong SECRET_KEY (or run `uv run --no-sync bp env gen-secret`), etc. + # set a strong SECRET_KEY (or run `uv run --no-sync fastro env secret`), etc. ``` - The CLI ships a few helpers for this step — see [CLI → Commands](../cli/commands.md): + fastro has a few helpers for this step; see [Generating and updating projects with fastro](../user-guide/fastro.md): ```bash - uv run --no-sync bp env gen-secret # print a fresh SECRET_KEY - uv run --no-sync bp env validate # audit the .env against the production validator + uv run --no-sync fastro env secret # print a fresh SECRET_KEY + uv run --no-sync fastro env validate # audit the .env against the production validator ``` 4. **Set up PostgreSQL** (if not already configured): @@ -276,7 +276,8 @@ After installing, verify everything works: 1. **API Docs**: 2. **Health Check**: `curl http://localhost:8000/health` -3. **Admin Panel**: +3. **Admin Panel**: , once `ADMIN_ENABLED=true` and both admin + credentials are set in `backend/.env`; it is off in the example, and unmounted until then 4. **Database**: check the app log for "Database connected" / no errors at startup ## Troubleshooting diff --git a/docs/index.md b/docs/index.md index 882b3ece..7d886d58 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,8 +1,8 @@ -# Fastro · The Benav Labs FastAPI Boilerplate +# FastAPI-boilerplate by Benav Labs

- Fastro - open-source FastAPI boilerplate - Fastro - open-source FastAPI boilerplate + FastAPI-boilerplate - open source + FastAPI-boilerplate - open source

@@ -101,7 +101,7 @@ Get up and running in less than 5 minutes. Pick whichever fits your workflow: git clone https://github.com/benavlabs/fastapi-boilerplate cd fastapi-boilerplate uv sync --all-packages --all-extras - uv run --no-sync bp deploy generate local # writes docker-compose.yml at the repo root + uv run --no-sync fastro make deploy local # writes docker-compose.yml at the repo root cp backend/.env.example backend/.env # then edit values as needed docker compose up ``` @@ -130,7 +130,7 @@ Your API will be available at `http://localhost:8000/docs` ## Building a complete SaaS? Meet FastroAI -Fastro is the free **foundation**. **[FastroAI](https://fastro.ai)** builds on the same base for shipping a full SaaS - Stripe billing (subscriptions, credits, discounts), entitlements, transactional email, a frontend, and AI agents - all wired together, so you don't build them from scratch. +FastAPI-boilerplate is the free **foundation**. **[FastroAI](https://fastro.ai)** builds on the same base for shipping a full SaaS - Stripe billing (subscriptions, credits, discounts), entitlements, transactional email, a frontend, and AI agents - all wired together, so you don't build them from scratch.

diff --git a/docs/user-guide/admin-panel/configuration.md b/docs/user-guide/admin-panel/configuration.md index d5d7466d..b1a48b9e 100644 --- a/docs/user-guide/admin-panel/configuration.md +++ b/docs/user-guide/admin-panel/configuration.md @@ -20,10 +20,11 @@ That's the whole admin-specific config. Everything else (engine, models, mount p ### Backing Settings Classes -The variables map to two settings classes in `src/infrastructure/config/settings.py`: +The variables map to three settings classes: -- **`AdminSettings`** — `ADMIN_NAME`, `ADMIN_EMAIL`, `ADMIN_USERNAME`, `ADMIN_PASSWORD`, `DEFAULT_TIER_NAME`. Used by both the admin panel login *and* `scripts/setup_initial_data.py` to bootstrap the first superuser. -- **`SQLAdminSettings`** — `ADMIN_ENABLED`. Single toggle for the admin panel. +- **`FirstSuperuserSettings`** in `src/infrastructure/auth/settings.py`: `ADMIN_NAME`, `ADMIN_EMAIL`, `ADMIN_USERNAME`, `ADMIN_PASSWORD`. Used by both the admin panel login *and* `scripts/setup_initial_data.py` to bootstrap the first superuser. +- **`TierSettings`** in `src/modules/tier/settings.py`: `DEFAULT_TIER_NAME`, the tier `scripts/setup_initial_data.py` creates and a new account is given. +- **`SQLAdminSettings`** in `src/interfaces/admin/settings.py`: `ADMIN_ENABLED`. Single toggle for the admin panel. ## What Happens at Startup @@ -222,17 +223,18 @@ For production behind HTTPS, you'll typically want to: ### Development -The default `.env.example` is already development-ready: +The default `.env.example` leaves the panel off: ```env ENVIRONMENT=development -ADMIN_ENABLED=true +ADMIN_ENABLED=false ADMIN_USERNAME=admin ADMIN_PASSWORD=Change-Me-Now-1! SECRET_KEY=insecure-secret-key-change-this-in-production ``` -Open , log in, and you have access to Users and Tiers. +Set `ADMIN_ENABLED=true` in your `.env`, restart, then open , log in, +and you have access to Users and Tiers. ### Production Hardening diff --git a/docs/user-guide/admin-panel/user-management.md b/docs/user-guide/admin-panel/user-management.md index 4c37e91d..9b099b84 100644 --- a/docs/user-guide/admin-panel/user-management.md +++ b/docs/user-guide/admin-panel/user-management.md @@ -168,7 +168,7 @@ For richer auditing, write to a dedicated log stream or push events to a SIEM. |-----------|----------| | Admin auth backend | `backend/src/interfaces/admin/auth.py` | | Admin app factory | `backend/src/interfaces/admin/initialize.py` | -| Settings classes | `backend/src/infrastructure/config/settings.py` (`AdminSettings`, `SQLAdminSettings`) | +| Settings classes | `backend/src/infrastructure/auth/settings.py` (`FirstSuperuserSettings`), `backend/src/interfaces/admin/settings.py` (`SQLAdminSettings`) | | Initial data script | `backend/scripts/setup_initial_data.py` | ## Next Steps diff --git a/docs/user-guide/authentication/index.md b/docs/user-guide/authentication/index.md index 1bb32d79..46f70498 100644 --- a/docs/user-guide/authentication/index.md +++ b/docs/user-guide/authentication/index.md @@ -277,7 +277,7 @@ curl -X POST http://localhost:8000/api/v1/auth/password/reset-confirm \ ### Login Lockout -`crudauth` throttles the login endpoint internally with an escalating per-IP / per-identifier lockout, whose thresholds are the `LOGIN_*` settings ([Authentication & Security](../configuration/environment-variables.md#authentication--security)). When the limit is hit, `POST /api/v1/auth/login` returns `429 Too Many Requests` with a `Retry-After` header telling the client how long to wait. Behind a reverse proxy, set `TRUSTED_PROXY_HOPS` so the lockout keys on the real client IP rather than the proxy's. +`crudauth` throttles the login endpoint internally with an escalating per-IP / per-identifier lockout, whose thresholds are the `LOGIN_*` settings ([Authentication & Security](../configuration/environment-variables.md#authentication-security)). When the limit is hit, `POST /api/v1/auth/login` returns `429 Too Many Requests` with a `Retry-After` header telling the client how long to wait. Behind a reverse proxy, set `TRUSTED_PROXY_HOPS` so the lockout keys on the real client IP rather than the proxy's. The per-identifier half counts failures from every address and applies before the password is checked, so anybody who knows a username, an admin's included, can keep that account out by failing diff --git a/docs/user-guide/authentication/sessions.md b/docs/user-guide/authentication/sessions.md index ec50ad62..9c56b383 100644 --- a/docs/user-guide/authentication/sessions.md +++ b/docs/user-guide/authentication/sessions.md @@ -545,7 +545,7 @@ entries, Redis keeps a per-user index, and the database store has a `user_id` co | Refused-login and lockout hooks | `backend/src/infrastructure/auth/audit.py` | | Session management routes | crudauth's `build_session_management_router`, mounted in `routes.py` | | HTTP exceptions (fastcrud re-export) | `backend/src/infrastructure/http_exceptions.py` | -| Auth settings | `backend/src/infrastructure/config/settings.py` (`AuthSettings`) | +| Auth settings | `backend/src/infrastructure/auth/settings.py` (`AuthSettings`) | Session storage, CSRF, and lockout themselves live in the `crudauth` library, not the boilerplate. diff --git a/docs/user-guide/background-tasks/index.md b/docs/user-guide/background-tasks/index.md index 5756da65..c1deca12 100644 --- a/docs/user-guide/background-tasks/index.md +++ b/docs/user-guide/background-tasks/index.md @@ -243,7 +243,7 @@ cd backend uv run --no-sync taskiq scheduler src.infrastructure.taskiq.scheduler:scheduler ``` -`bp deploy generate` writes it as a `scheduler` service alongside the worker, for a project that +`fastro make deploy` writes it as a `scheduler` service alongside the worker, for a project that carries the taskiq feature. **Run exactly one scheduler.** Each one fires every schedule it finds, so a second replica means @@ -473,7 +473,7 @@ async def rebuild_widget_index(owner_id: int, db: DBSession) -> dict[str, Any]: | Broker lifecycle (API) | `backend/src/infrastructure/taskiq/lifecycle.py` | | DB dependency | `backend/src/infrastructure/taskiq/deps.py` | | Registered task modules | `backend/src/wiring/tasks.py` | -| Settings | `backend/src/infrastructure/config/settings.py` (`TaskiqSettings`) | +| Settings | `backend/src/infrastructure/taskiq/settings.py` (`TaskiqSettings`) | ## Next Steps diff --git a/docs/user-guide/caching/client-cache.md b/docs/user-guide/caching/client-cache.md index 589ebe68..47ad458c 100644 --- a/docs/user-guide/caching/client-cache.md +++ b/docs/user-guide/caching/client-cache.md @@ -197,7 +197,7 @@ Raise `CLIENT_CACHE_MAX_AGE`, or set per-asset headers in the handler / proxy. B |-----------------------|-------------------------------------------------------| | Middleware | `backend/src/infrastructure/middleware.py` | | Wiring | `backend/src/infrastructure/app_factory.py` | -| Settings | `backend/src/infrastructure/config/settings.py` (`CacheSettings`) | +| Settings | `backend/src/infrastructure/config/base.py` (`ClientCacheSettings`) | ## Next Steps diff --git a/docs/user-guide/caching/index.md b/docs/user-guide/caching/index.md index d5031dd5..8bbe74e0 100644 --- a/docs/user-guide/caching/index.md +++ b/docs/user-guide/caching/index.md @@ -130,7 +130,7 @@ If the cache backend becomes unavailable, the decorator catches the error and fa | Decorator | `backend/src/infrastructure/cache/decorator.py` | | Provider API | `backend/src/infrastructure/cache/provider.py` | | Backends | `backend/src/infrastructure/cache/backends/` | -| Settings | `backend/src/infrastructure/config/settings.py` (`CacheSettings`) | +| Settings | `backend/src/infrastructure/cache/settings.py` (`CacheSettings`) | | Client-cache middleware | `backend/src/infrastructure/middleware.py` | ## Next Steps diff --git a/docs/user-guide/caching/redis-cache.md b/docs/user-guide/caching/redis-cache.md index 567ef687..48db2460 100644 --- a/docs/user-guide/caching/redis-cache.md +++ b/docs/user-guide/caching/redis-cache.md @@ -370,7 +370,7 @@ You're keying by resource ID without including the user. See "Don't Cache Person | Provider API | `backend/src/infrastructure/cache/provider.py` | | Redis backend | `backend/src/infrastructure/cache/backends/redis.py` | | Memcached backend | `backend/src/infrastructure/cache/backends/memcached.py` | -| Settings | `backend/src/infrastructure/config/settings.py` (`CacheSettings`) | +| Settings | `backend/src/infrastructure/cache/settings.py` (`CacheSettings`) | ## Next Steps diff --git a/docs/user-guide/composable-features.md b/docs/user-guide/composable-features.md index 9d05a6e2..175459f5 100644 --- a/docs/user-guide/composable-features.md +++ b/docs/user-guide/composable-features.md @@ -29,6 +29,8 @@ plain objects at stable paths, and one package collects them. | `tables.py` | `TABLE_MODULES`, the modules outside `src/modules` that declare tables on `Base.metadata` | | `transports.py` | `EXTRA_TRANSPORTS`, the authentication transports registered beside the session one | | `cache.py` | `cached`, the decorator a route caches its response with, re-exported so a route never imports the cache feature | +| `scope.py` | `SCOPE_FINGERPRINT`, which accounts contributes so the cache keys a scoped credential apart from its account without importing accounts; `None` without it | +| `signup.py` | `NEW_ACCOUNT_FIELDS`, the columns features set on an account as it is created, on the signup route and on a provider's first sign-in: tiers gives it the tier `DEFAULT_TIER_NAME` names | Two more live beside the code they drive: `backend/scripts/seeders.py` lists `SEEDERS`, and `backend/tests/wiring.py` lists the fixture modules pytest loads. @@ -109,14 +111,15 @@ the project's dependencies) and with Docker up (the tests use a Postgres contain RabbitMQ one where the taskiq feature is present): ```sh -uv run --no-sync python tools/removal_drill.py # every preset -uv run --no-sync python tools/removal_drill.py accounts-only # one of them -uv run --no-sync python tools/removal_drill.py --keep # keep the scratch copies +uv run --no-sync fastro blueprint verify # every set +uv run --no-sync fastro blueprint verify accounts-only # one of them +uv run --no-sync fastro blueprint verify --keep # keep the builds ``` -The presets run in CI as a matrix: +CI runs it once for each set, one job each: the `[verify.sets]` and `everything`, below, and +the presets `minimal`, `standard` and `full`. -| Preset | What it proves | +| Set | What it proves | |--------|----------------| | `core-only` | every feature can go at once | | `core-taskiq` | the worker runs with no accounts feature, so it registers no account mail | @@ -128,16 +131,19 @@ The presets run in CI as a matrix: | `accounts-cache-taskiq` | the infrastructure features stand alone | | `everything` | a regenerated wiring reproduces this repository | -The drill is also how a misplaced test gets caught: a test that quietly depends on -a feature it doesn't own fails in the preset that removes it. +Verify is also how a misplaced test gets caught: a test that quietly depends on a feature it +doesn't own fails in the set that removes it. ## Writing a feature that can be removed -1. Keep everything the feature owns under its own paths, and add those paths to the - drill's manifest. +1. Keep everything the feature owns under its own paths, and list those paths in its + `[features.]` table in `blueprint.toml`. A file that only makes sense beside another + feature, such as the feature's `admin.py`, goes in a `[[features..when]]` block with + `if = ""`, together with what it contributes. 2. Import another feature only if the table above says you need it. 3. To reach into another feature, contribute to a hook rather than importing it. 4. Put the feature's settings in its own `settings.py` and its fixtures in `tests/fixtures/`, then list both in the wiring. -5. Run the drill. If a preset that excludes your feature fails, something of yours - is in a path the drill doesn't delete. +5. Run `fastro blueprint verify`. If a set that excludes your feature fails, something of + yours is in a path its table doesn't list. If a set that keeps your feature and drops one + it reaches into fails, a file of yours belongs in a `when` block. diff --git a/docs/user-guide/configuration/docker-setup.md b/docs/user-guide/configuration/docker-setup.md index 2191936d..43c719e1 100644 --- a/docs/user-guide/configuration/docker-setup.md +++ b/docs/user-guide/configuration/docker-setup.md @@ -2,20 +2,20 @@ This page walks through running the boilerplate in containers. The Python project lives at `backend/`, and the image builds from the repository root: it needs the workspace's -`pyproject.toml`, `uv.lock` and `cli/pyproject.toml` as well as `backend/`. You run -`docker compose` from the repository root too. +`pyproject.toml` and `uv.lock` as well as `backend/`. You run `docker compose` from the +repository root too. !!! info "The compose file is generated, not shipped" - No compose file is committed. `bp deploy generate local` writes one at the repository root, + No compose file is committed. `fastro make deploy local` writes one at the repository root, where it is gitignored, so regenerating it never conflicts with the repo. `prod` and `nginx` - write the other two stacks. See [CLI commands](../../cli/commands.md#bp-deploy-generate-mode). + write the other two stacks. See [`fastro make deploy`](../fastro.md#writing-the-compose-files-fastro-make-deploy). ## Quick Start ```bash cp backend/.env.example backend/.env # edit backend/.env (set SECRET_KEY, change default DB password, etc.) -uv run --no-sync bp deploy generate local +uv run --no-sync fastro make deploy local docker compose up --build ``` @@ -31,7 +31,7 @@ docker compose up --build | `migrate` | Adds `migrations/` and `alembic.ini`. Default command is `alembic upgrade head`. Useful as a one-off job before the prod app starts. | | `prod` | Same as base, runs as non-root, starts with `fastapi run interfaces/main.py --host 0.0.0.0 --port 8000 --workers $WORKERS` (defaults to 1). | -You select a stage with `--target` when building. The context is the repository root, because the Dockerfile copies `pyproject.toml`, `uv.lock`, `backend/` and `cli/pyproject.toml` from there: +You select a stage with `--target` when building. The context is the repository root, because the Dockerfile copies `pyproject.toml`, `uv.lock` and `backend/` from there: ```bash docker build --target dev -t fastapi-boilerplate:dev -f backend/Dockerfile . @@ -39,7 +39,7 @@ docker build --target prod -t fastapi-boilerplate:prod -f backend/Dockerfile . docker build --target migrate -t fastapi-boilerplate:migrate -f backend/Dockerfile . ``` -## What `bp deploy generate local` Writes +## What `fastro make deploy local` Writes Four services, named `api`, `worker`, `postgres` and `redis`, with the API and the worker built from the `dev` stage and the source mounted for reload: @@ -260,10 +260,10 @@ docker compose down -v For a more production-like local stack: -1. **Generate the `prod` stack**: `bp deploy generate prod` builds the `prod` stage, drops the +1. **Generate the `prod` stack**: `fastro make deploy prod` builds the `prod` stage, drops the source mounts and runs `fastapi run --workers`. 2. **Run migrations as a separate job** (the `migrate` service above) before the app starts. -3. **Set the worker count**: `bp deploy generate prod --workers 4`, or `WORKERS=4` in +3. **Set the worker count**: `fastro make deploy prod --workers 4`, or `WORKERS=4` in `backend/.env` (the `prod` command reads it). 5. **Add a reverse proxy** if you need TLS — Caddy or Traefik are simpler to configure than nginx for single-host setups. diff --git a/docs/user-guide/configuration/environment-variables.md b/docs/user-guide/configuration/environment-variables.md index 624522bd..79d4a07c 100644 --- a/docs/user-guide/configuration/environment-variables.md +++ b/docs/user-guide/configuration/environment-variables.md @@ -281,7 +281,7 @@ FORWARDED_ALLOW_IPS=172.31.240.0/24 and the access logs report. Because uvicorn reads it from its own process environment, it reaches the server through compose's `env_file` (or whatever exports it where uvicorn starts) rather than through the app's settings — a value in `backend/.env` only applies if that file is the container's -`env_file`. `bp deploy generate nginx` writes it for you, set to `--internal-subnet`. +`env_file`. `fastro make deploy nginx` writes it for you, set to `--internal-subnet`. Leave it unset when nothing sits in front of the app. A wildcard (`*`) lets any client claim any address, and `TRUSTED_PROXY_HOPS` then counts hops in a header the client controls. @@ -385,6 +385,10 @@ The default tier name is also configurable (defaults to `free`): DEFAULT_TIER_NAME=free ``` +With the tiers feature, every new account is given this tier: one made on the signup route, and +one a provider's first sign-in makes. While no tier has this name, or the one that had it is +deleted, a new account has no tier. + ## Logging ```env diff --git a/docs/user-guide/configuration/index.md b/docs/user-guide/configuration/index.md index 00cf9825..9b2102ed 100644 --- a/docs/user-guide/configuration/index.md +++ b/docs/user-guide/configuration/index.md @@ -62,12 +62,12 @@ SECRET_KEY=your-secret-key Pydantic `BaseSettings` classes in `src/infrastructure/config/settings.py` validate and structure config: ```python -class DatabaseSettings(BaseSettings): - POSTGRES_USER: str = config("POSTGRES_USER", default="postgres") - POSTGRES_PASSWORD: str = config("POSTGRES_PASSWORD", default="postgres") - POSTGRES_SERVER: str = config("POSTGRES_SERVER", default="localhost") - POSTGRES_PORT: int = config("POSTGRES_PORT", default=5432) - POSTGRES_DB: str = config("POSTGRES_DB", default="postgres") +class DatabaseSettings(EnvSettings): + POSTGRES_USER: str = "postgres" + POSTGRES_PASSWORD: str = "postgres" + POSTGRES_SERVER: str = "localhost" + POSTGRES_PORT: int = 5432 + POSTGRES_DB: str = "postgres" ``` A single composite `Settings` class combines them all. @@ -222,8 +222,8 @@ To run a Taskiq worker, add a worker service to your Compose file with the comma The boilerplate already exposes toggles like `CACHE_ENABLED`, `RATE_LIMITER_ENABLED`, `ADMIN_ENABLED`, and `CSRF_ENABLED`. You can add your own in a settings class: ```python -class FeatureSettings(BaseSettings): - ENABLE_ANALYTICS: bool = config("ENABLE_ANALYTICS", default=False, cast=bool) +class FeatureSettings(EnvSettings): + ENABLE_ANALYTICS: bool = False ``` Then use it: diff --git a/docs/user-guide/configuration/settings-classes.md b/docs/user-guide/configuration/settings-classes.md index 0876017c..6cc22257 100644 --- a/docs/user-guide/configuration/settings-classes.md +++ b/docs/user-guide/configuration/settings-classes.md @@ -1,46 +1,32 @@ # Settings Classes -Settings live in `backend/src/infrastructure/config/settings.py` and are organized as Pydantic `BaseSettings` classes — each class groups related variables, and a single `Settings` class composes them all. Defaults come from `backend/.env` via Starlette's `Config()` loader. +Settings are organized as Pydantic `BaseSettings` classes: the core ones in `src/infrastructure/config/base.py`, and each feature's next to the feature. Each class groups related variables, and a single `Settings` class composes the ones the project's features bring. Each class derives from `EnvSettings` in `src/infrastructure/config/base.py`, which reads the environment and `backend/.env` when the class is built: a variable set in the environment wins over the file, and the field's own default applies when neither sets it. ## Settings Architecture ```python -# src/infrastructure/config/settings.py -from pydantic_settings import BaseSettings -from starlette.config import Config - -config = Config(env_path) # reads backend/.env +# src/wiring/settings.py, which `fastro sync` writes for the features a project selected class Settings( - EnvironmentSettings, - DatabaseSettings, - CacheSettings, - RateLimiterSettings, - CORSSettings, - CompressionSettings, - APIDocSettings, - AuthSettings, - APISettings, - AppSettings, - AdminSettings, + AccountsSettings, + RateLimitSettings, + TierSettings, + APIKeySettings, SQLAdminSettings, - SecuritySettings, - LoggingSettings, + CacheSettings, TaskiqSettings, + CoreSettings, ): - """Main settings class that combines all setting categories.""" - - pass + """The settings of every selected feature, on top of the core.""" settings = Settings() - - -def get_settings() -> Settings: - return settings ``` +`src/infrastructure/config/settings.py` imports `Settings` and `settings` from there and adds +`get_settings()`, so code imports them from it whatever features are installed. + Anywhere in the app: ```python @@ -52,21 +38,23 @@ print(settings.APP_NAME) ## Built-in Settings Groups -The actual classes that ship with the boilerplate, all in `src/infrastructure/config/settings.py`: +The classes that ship with the boilerplate: | Class | Covers | |-------|--------| | `EnvironmentSettings` | `ENVIRONMENT` (production/staging/development/local) | | `DatabaseSettings` | All `POSTGRES_*` vars + `DATABASE_URL` computed property | | `CacheSettings` | `CACHE_*` (Redis + Memcached + client-side) | -| `RateLimiterSettings` | `RATE_LIMITER_*` (Redis + Memcached + defaults) | +| `RateLimitSettings` | `RATE_LIMITER_ENABLED`, `DEFAULT_RATE_LIMIT_LIMIT`, `DEFAULT_RATE_LIMIT_PERIOD` | +| `LimiterBackendSettings` | `RATE_LIMITER_BACKEND`, `RATE_LIMITER_REDIS_*` (the limiter login lockout uses) | | `CORSSettings` | `CORS_*` | | `CompressionSettings` | `GZIP_*` | | `APIDocSettings` | `ENABLE_DOCS_IN_PRODUCTION`, `OPENAPI_PREFIX`, `DOCS_URL`, `REDOC_URL`, `OPENAPI_URL`, and the `API_*` document metadata (title, summary, description, version, terms, contact, licence, tags) | -| `AuthSettings` | `SECRET_KEY`, `SESSION_*`, `CSRF_ENABLED`, `TRUSTED_PROXY_HOPS`, `OAUTH_*` | +| `AuthSettings` | `SESSION_*`, `CSRF_ENABLED`, `TRUSTED_PROXY_HOPS`, `OAUTH_*` | | `APISettings` | `API_PREFIX` | | `AppSettings` | `APP_NAME`, `APP_DESCRIPTION`, `VERSION`, `DEBUG` | -| `AdminSettings` | `ADMIN_NAME`, `ADMIN_EMAIL`, `ADMIN_USERNAME`, `ADMIN_PASSWORD`, `DEFAULT_TIER_NAME` | +| `FirstSuperuserSettings` | `ADMIN_NAME`, `ADMIN_EMAIL`, `ADMIN_USERNAME`, `ADMIN_PASSWORD` | +| `TierSettings` | `DEFAULT_TIER_NAME` | | `SQLAdminSettings` | `ADMIN_ENABLED` | | `SecuritySettings` | `SECRET_KEY`, `PRODUCTION_SECURITY_VALIDATION_ENABLED`, `SECURITY_HEADERS_ENABLED` | | `LoggingSettings` | All `LOG_*` | @@ -78,19 +66,32 @@ The actual classes that ship with the boilerplate, all in `src/infrastructure/co A typical class: ```python -class DatabaseSettings(BaseSettings): +class DatabaseSettings(EnvSettings): """Database-related settings.""" - POSTGRES_USER: str = config("POSTGRES_USER", default="postgres") - POSTGRES_PASSWORD: str = config("POSTGRES_PASSWORD", default="postgres") - POSTGRES_SERVER: str = config("POSTGRES_SERVER", default="localhost") - POSTGRES_PORT: int = config("POSTGRES_PORT", default=5432) - POSTGRES_DB: str = config("POSTGRES_DB", default="postgres") - POSTGRES_ASYNC_PREFIX: str = config("POSTGRES_ASYNC_PREFIX", default="postgresql+asyncpg://") - CREATE_TABLES_ON_STARTUP: bool = config( - "CREATE_TABLES_ON_STARTUP", default=_creates_tables_by_default(), cast=bool - ) - POSTGRES_POOL_SIZE: int = config("POSTGRES_POOL_SIZE", default=20, cast=int) + POSTGRES_USER: str = "postgres" + POSTGRES_PASSWORD: str = "postgres" + POSTGRES_SERVER: str = "localhost" + POSTGRES_PORT: int = 5432 + POSTGRES_DB: str = "postgres" + POSTGRES_ASYNC_PREFIX: str = "postgresql+asyncpg://" + CREATE_TABLES_ON_STARTUP: bool = Field(default_factory=_creates_tables_by_default) + POSTGRES_POOL_SIZE: int = 20 + + DATABASE_URL_OVERRIDE: str | None = Field(default=None, validation_alias="DATABASE_URL") + + @model_validator(mode="before") + @classmethod + def _tables_follow_the_environment(cls, values: Any) -> Any: + """Default ``CREATE_TABLES_ON_STARTUP`` from the ``ENVIRONMENT`` these settings are built with.""" + if not isinstance(values, dict) or "CREATE_TABLES_ON_STARTUP" in values: + return values + try: + creates = _creates_tables_by_default(values.get("ENVIRONMENT")) + except ValueError: + return values + + return {**values, "CREATE_TABLES_ON_STARTUP": creates} @property def DATABASE_URL(self) -> str: @@ -98,9 +99,8 @@ class DatabaseSettings(BaseSettings): Falls back to assembling from POSTGRES_* if DATABASE_URL is not set. """ - direct_url = config("DATABASE_URL", default=None) - if direct_url: - return direct_url + if self.DATABASE_URL_OVERRIDE: + return self.DATABASE_URL_OVERRIDE return ( f"{self.POSTGRES_ASYNC_PREFIX}{self.POSTGRES_USER}:" f"{self.POSTGRES_PASSWORD}@{self.POSTGRES_SERVER}:" @@ -110,8 +110,11 @@ class DatabaseSettings(BaseSettings): Key points: -- Each field uses `config("VAR_NAME", default=..., cast=...)`. The `Config()` instance is initialized with `backend/.env` so values are loaded at import time. -- For typed conversion, pass `cast=int`, `cast=bool`, etc. +- Each field is named after its variable and carries its default; the field's type is what the value is parsed to (`int`, `bool`, an enum). +- A `bool` written as text is `true`, `false`, `1` or `0` in any case, and an `int` written as text is whatever `int()` reads, so `yes` and `1.0` are refused rather than guessed at. +- Values are read when a settings class is built, so a test that sets or deletes a variable sees the change in the next `Settings()` it builds. +- A default that depends on another variable is set by a `mode="before"` model validator, which sees every value the settings are built with: `CREATE_TABLES_ON_STARTUP` follows the `ENVIRONMENT` given to the constructor or read from the environment. The `default_factory` only answers for settings built without validation. +- The environment file is read as it always was: one `NAME=value` a line, names exactly as written, values literally (no `${...}` expansion, and a `#` is part of the value). - Use `@property` for derived values (like `DATABASE_URL`) — no need for `@computed_field` since callers always go through `get_settings()`. ## Adding Custom Settings @@ -119,20 +122,22 @@ Key points: ### Basic Custom Group ```python -# backend/src/infrastructure/config/settings.py +# your module's settings.py +from src.infrastructure.config.base import EnvSettings + -class StorageSettings(BaseSettings): +class StorageSettings(EnvSettings): """File-storage settings.""" - STORAGE_BACKEND: str = config("STORAGE_BACKEND", default="local") # "local" or "s3" - LOCAL_STORAGE_PATH: str = config("LOCAL_STORAGE_PATH", default="./uploads") + STORAGE_BACKEND: str = "local" # "local" or "s3" + LOCAL_STORAGE_PATH: str = "./uploads" - AWS_ACCESS_KEY_ID: str = config("AWS_ACCESS_KEY_ID", default="") - AWS_SECRET_ACCESS_KEY: str = config("AWS_SECRET_ACCESS_KEY", default="") - AWS_BUCKET_NAME: str = config("AWS_BUCKET_NAME", default="") - AWS_REGION: str = config("AWS_REGION", default="us-east-1") + AWS_ACCESS_KEY_ID: str = "" + AWS_SECRET_ACCESS_KEY: str = "" + AWS_BUCKET_NAME: str = "" + AWS_REGION: str = "us-east-1" - MAX_UPLOAD_SIZE_BYTES: int = config("MAX_UPLOAD_SIZE_BYTES", default=10_485_760, cast=int) + MAX_UPLOAD_SIZE_BYTES: int = 10_485_760 class Settings( @@ -149,11 +154,11 @@ Then add the matching variables to `backend/.env.example` so they're discoverabl ### Computed / Derived Values ```python -class StorageSettings(BaseSettings): - STORAGE_BACKEND: str = config("STORAGE_BACKEND", default="local") - AWS_ACCESS_KEY_ID: str = config("AWS_ACCESS_KEY_ID", default="") - AWS_SECRET_ACCESS_KEY: str = config("AWS_SECRET_ACCESS_KEY", default="") - AWS_BUCKET_NAME: str = config("AWS_BUCKET_NAME", default="") +class StorageSettings(EnvSettings): + STORAGE_BACKEND: str = "local" + AWS_ACCESS_KEY_ID: str = "" + AWS_SECRET_ACCESS_KEY: str = "" + AWS_BUCKET_NAME: str = "" @property def s3_configured(self) -> bool: @@ -176,9 +181,9 @@ For richer validation, switch a field's value to use Pydantic validators: from pydantic import field_validator, model_validator -class StorageSettings(BaseSettings): - STORAGE_BACKEND: str = config("STORAGE_BACKEND", default="local") - MAX_UPLOAD_SIZE_BYTES: int = config("MAX_UPLOAD_SIZE_BYTES", default=10_485_760, cast=int) +class StorageSettings(EnvSettings): + STORAGE_BACKEND: str = "local" + MAX_UPLOAD_SIZE_BYTES: int = 10_485_760 @field_validator("MAX_UPLOAD_SIZE_BYTES") @classmethod @@ -216,8 +221,8 @@ class StorageBackend(StrEnum): from .enums import StorageBackend -class StorageSettings(BaseSettings): - STORAGE_BACKEND: str = config("STORAGE_BACKEND", default=StorageBackend.LOCAL.value) +class StorageSettings(EnvSettings): + STORAGE_BACKEND: str = StorageBackend.LOCAL.value ``` The boilerplate already does this for `CacheBackend`, `LogFormat`, `LogLevel`, `SessionBackend`, `TaskiqBrokerType`, and `EnvironmentOption`. @@ -236,7 +241,7 @@ class Settings( AppSettings, LoggingSettings, # CacheSettings — removed - # RateLimiterSettings — removed + # RateLimitSettings — removed # TaskiqSettings — removed ): pass diff --git a/docs/user-guide/database/migrations.md b/docs/user-guide/database/migrations.md index 8be1f0d6..bc360aa7 100644 --- a/docs/user-guide/database/migrations.md +++ b/docs/user-guide/database/migrations.md @@ -31,6 +31,12 @@ Tracked, reviewable, reversible schema changes — what you want for anything be want ([Composable Features](../composable-features.md)), then generate the baseline for what's left. + **The script does all of this.** `uv run --no-sync python -m scripts.baseline` starts a + throwaway Postgres, autogenerates the revision against it, checks that applying it recreates + exactly what the models declare, and leaves it in `migrations/versions/` to commit; `--check` + deletes it again. The rest of this section is the same thing by hand, for when Docker isn't + there. + **Generate it against a database with nothing in it.** Autogenerate writes the difference between the models and the database it connects to, so pointing it at a database that already has the schema — a dev stack, which `CREATE_TABLES_ON_STARTUP` built with `create_all` — writes @@ -447,7 +453,7 @@ ENVIRONMENT=production CONFIRM_PRODUCTION_MIGRATION=yes uv run --no-sync alembic ### Docker Migration Job -`bp deploy generate prod` (and `nginx`) writes a `migrate` service for this, built from the `migrate` +`fastro make deploy prod` (and `nginx`) writes a `migrate` service for this, built from the `migrate` stage in `backend/Dockerfile`, which runs `alembic upgrade head` and exits. It sits behind a compose profile, and nothing waits on it: diff --git a/docs/user-guide/database/neon.md b/docs/user-guide/database/neon.md index 699b9e0b..75ddfb6d 100644 --- a/docs/user-guide/database/neon.md +++ b/docs/user-guide/database/neon.md @@ -3,7 +3,7 @@ [Neon](https://neon.com) is serverless Postgres — a managed database that scales compute to zero when idle and lets you branch a database like you branch code. It's a drop-in replacement for the local Postgres container: the boilerplate needs **one environment variable**, no code changes. !!! info "Neon sponsors this project" - Neon supports Fastro · The Benav Labs FastAPI Boilerplate with database credits for our open-source infrastructure. It's one option among many — the boilerplate runs on any Postgres 14+ (local, RDS, Cloud SQL, Supabase, your own box) — but it's the one we use and the one these instructions are tested against. + Neon supports FastAPI-boilerplate by Benav Labs with database credits for our open-source infrastructure. It's one option among many — the boilerplate runs on any Postgres 14+ (local, RDS, Cloud SQL, Supabase, your own box) — but it's the one we use and the one these instructions are tested against. ## When it's a good fit @@ -131,7 +131,7 @@ services: condition: service_healthy ``` -Redis still runs locally — Neon replaces Postgres only. Regenerating with `uv run --no-sync bp deploy generate local` brings the Postgres service back, so keep the edit in mind after a regen. +Redis still runs locally; Neon replaces Postgres only. Regenerating with `uv run --no-sync fastro make deploy local` brings the Postgres service back, so keep the edit in mind after a regen. ## Database branching for previews diff --git a/docs/user-guide/development.md b/docs/user-guide/development.md index 25c0e10b..eb099b26 100644 --- a/docs/user-guide/development.md +++ b/docs/user-guide/development.md @@ -95,28 +95,29 @@ field reads as an error. ## Pre-Commit -The repo's `.pre-commit-config.yaml` runs what CI runs, and nothing that fights it: +The repo's `.pre-commit-config.yaml` runs these hooks. A row that names CI says what CI runs for it; the other hooks are no CI step: | Hook | What it does | |------|--------------| -| `ruff-check --fix`, `ruff-format` | the same lint and format CI checks | +| `ruff-check --fix`, `ruff-format` | lint and format the files a commit stages, fixing what they can; CI runs `ruff check` and `ruff format --check` | | `pyupgrade` | rewrites to Python 3.11+ syntax | | `yesqa` | removes a `noqa` nothing needs any more | -| hygiene hooks | final newlines, trailing whitespace, YAML, large files, private keys, merge markers | -| `mypy_backend`, `mypy_cli` | local hooks, the same invocations CI uses | -| `unit_test` | local, manual stage: `pytest tests/unit` | +| `end-of-file-fixer`, `trailing-whitespace`, `check-yaml`, `check-executables-have-shebangs`, `check-case-conflict`, `check-added-large-files`, `detect-private-key`, `check-merge-conflict` | final newlines, trailing whitespace, YAML, shebangs on executables, file names that differ only in case, large files, private keys, merge markers | +| `mypy_backend` | local hook, the same invocation CI uses | +| `fastro_sync_check` | local: `uv run --no-sync fastro sync --check`, on a commit that touches `blueprint.toml`, `fastro.toml`, the wiring, the root `pyproject.toml` or `uv.lock`; CI runs the same command | +| `unit_test` | local, manual stage: `uv run --no-sync pytest tests/unit` in `backend/`; CI runs these tests with the rest, as `uv run --no-sync pytest` in `backend/` | -`unit_test` runs the unit tests only — they need no container and finish in seconds. The -integration suite, which starts Postgres through testcontainers, runs in CI and when you run -`pytest` yourself. +`unit_test` runs the unit tests only. Some of them start containers through `testcontainers`, and +every test that starts a container skips when Docker isn't running, so the hook passes without +Docker. The integration suite runs in CI and when you run `pytest` yourself. There are no docstring- or markdown-formatting hooks: `ruff-format` owns formatting, and the two documentation hooks this repo used to carry damaged what they touched — `mdformat` broke MkDocs content tabs, and `blacken-docs` rewrote code samples into different code. -`check-docstring-first` is left out for the same reason. This project documents a module-level -name with an attribute docstring under it, which the hook reads as a second module docstring, so -it refused 40 files. +`check-docstring-first` is left out too. This project documents a module-level name with an +attribute docstring under it, which the hook reads as a second module docstring, so it refuses +those files. `pre-commit` ships in the `dev` extra, so `uv sync --all-packages --all-extras` installs it. Install the git hook once: @@ -394,8 +395,11 @@ Settings live in `backend/src/infrastructure/config/settings.py`. To add a new e 1. Add the field to the relevant settings class (or create a new one): ```python - class WidgetSettings(BaseSettings): - WIDGET_BATCH_SIZE: int = config("WIDGET_BATCH_SIZE", default=100, cast=int) + from src.infrastructure.config.base import EnvSettings + + + class WidgetSettings(EnvSettings): + WIDGET_BATCH_SIZE: int = 100 ``` 2. Add it to the composed `Settings` mixin list at the bottom of `settings.py`. 3. Document the env var in `backend/.env.example`. diff --git a/docs/user-guide/fastro.md b/docs/user-guide/fastro.md new file mode 100644 index 00000000..bb7ef090 --- /dev/null +++ b/docs/user-guide/fastro.md @@ -0,0 +1,95 @@ +# Generating and updating projects with fastro + +fastro is the tool that reads this repository's `blueprint.toml`. The root dev group installs it, +so after `uv sync --all-packages --all-extras` every command below runs from the repository root +through `uv run --no-sync`. Every command has `--help`. + +## Writing the compose files: `fastro make deploy` + +```bash +uv run --no-sync fastro make deploy local +``` + +`fastro make deploy` renders `[generators.deploy]` from `blueprint.toml`: `docker-compose.yml` for +the mode it is given, and for `nginx` also `nginx/default.conf`, at the repository root unless +`--output-dir` says otherwise. Each file starts with a header naming the command that wrote it, +and the compose project is named after the project's slug, `fastapi-boilerplate` here. Apart from +the header and the project name, the files are byte for byte what the legacy deploy command wrote. + +It runs in the blueprint repository. In a project fastro created it exits 2 for now. +`bp deploy generate` exits 2 too, in a project made before fastro. + +| Mode | Stack | Files | +|---|---|---| +| `local` | The API from the `dev` stage, source mounted, hot reload, with Postgres and Redis | `docker-compose.yml` | +| `prod` | The API from the `prod` stage with `WORKERS` workers, with Postgres and Redis and a `migrate` one-shot | `docker-compose.yml` | +| `nginx` | The API from the `prod` stage, with Postgres and Redis and a `migrate` one-shot, behind an nginx reverse proxy on port 80 | `docker-compose.yml`, `nginx/default.conf` | + +A project with the taskiq feature also gets a `worker` and one `scheduler` in every mode. +[Docker Setup](configuration/docker-setup.md) walks through what `local` writes, and +[Migrations](database/migrations.md) how a deploy runs the `migrate` service. + +| Option | Default | What it sets | +|---|---|---| +| `--output-dir`, `-o` | the repository root | Where the files are written | +| `--api-port` | `8000` | The host port the API is published on, for `local` and `prod` | +| `--workers` | `4` | API workers, for `prod` and `nginx` | +| `--internal-subnet` | `172.31.240.0/24` | The compose network, and the only peers uvicorn takes forwarded headers from, for `nginx` | +| `--force`, `-f` | | Replace a file that differs without asking | +| `--yes`, `-y` | | The same as `--force` | +| `--dry-run` | | Name each file it would write, and write nothing | + +```bash +uv run --no-sync fastro make deploy prod --workers 8 --api-port 9000 +uv run --no-sync fastro make deploy nginx --output-dir /tmp/scratch --dry-run +uv run --no-sync fastro make deploy nginx --internal-subnet 10.89.0.0/24 +``` + +It prints one line per file: `wrote X`, `unchanged X` when the file already holds what it would +write, or `kept X` when you decline to replace it. With `--dry-run` it prints `would write X (N +bytes)` for each file it would write, and writes nothing. A file that differs is replaced only once you confirm, or with `--force` or +`--yes`; with no terminal to ask on, it is kept and named, and the exit is still 0. + +`--internal-subnet` has to name a network of `/8` or smaller for IPv4, and `/48` or smaller for +IPv6. For `nginx` it is written as the compose network's subnet and as `FORWARDED_ALLOW_IPS` for +the API container. Every value is checked in every mode, so a value with host bits set +(`172.31.240.1/24`), a wildcard, or a wider range exits 2 before any file is written. `local` and +`prod` always use the default network. + +## Preparing the environment: `fastro env` + +### `fastro env secret` + +```bash +uv run --no-sync fastro env secret +uv run --no-sync fastro env secret --bytes 16 +uv run --no-sync fastro env secret | gh secret set SECRET_KEY --repo my-org/my-app +``` + +Prints a hex key for `SECRET_KEY`: `--bytes` random bytes, from `16` to `128`, `32` by default, +so 64 hex characters. It is built in, so it prints a token anywhere. In this repository it runs +`scripts.gen_secret` instead, which draws again while the app's secret-key rules would refuse the +key. + +### `fastro env validate` + +```bash +uv run --no-sync fastro env validate +``` + +In this repository it runs `scripts.validate_env`: the production security validator the app runs +at startup, against your settings as if `ENVIRONMENT` were `production`, whatever it is set to. It +prints what it finds, critical findings first, and exits 1 when anything is critical and 0 +otherwise, so a deploy job can run it as a gate. The checks themselves are in +[The Production Validator](production.md#the-production-validator). + +Anywhere else it exits 2 and says why: outside a project, and in a project fastro created, for now, +or in a blueprint repository whose selection declares no `env validate`. + +## In the blueprint repository: `fastro sync` and `fastro blueprint` + +`fastro sync` regenerates the wiring files that `blueprint.toml`'s `[[wiring]]` tables list, most +of them under `backend/src/wiring/`, from `blueprint.toml` and `fastro.toml`, and +`fastro sync --check` fails when the two have drifted. `fastro blueprint lint` +checks the catalog, and `fastro blueprint verify` builds projects from it and runs their checks. +These are for working on FastAPI-boilerplate itself. diff --git a/docs/user-guide/observability.md b/docs/user-guide/observability.md index ee96e657..1ae6e926 100644 --- a/docs/user-guide/observability.md +++ b/docs/user-guide/observability.md @@ -44,10 +44,10 @@ from .config.settings import settings from .database.session import get_engine -def configure_tracing() -> None: +def configure_tracing(service_name: str = "api") -> None: """Configure Logfire and instrument the clients this app talks through.""" logfire.configure( - service_name="api", + service_name=service_name, environment=settings.ENVIRONMENT.value, send_to_logfire="if-token-present", console=False, @@ -59,33 +59,35 @@ def configure_tracing() -> None: def install(app: FastAPI) -> None: - """Trace every request this app serves, except the probes.""" + """Configure tracing, then trace every request this app serves, except the probes.""" + configure_tracing() logfire.instrument_fastapi(app, excluded_urls=["/health", "/health/ready"]) ``` -Then wire it where this app is composed, in `src/interfaces/main.py`: +Then register the installer in the project's `fastro.toml`, and regenerate the wiring: -```python -from ..infrastructure.observability import configure_tracing, install as tracing_install - -configure_tracing() - -app = create_application( - router=router, - settings=settings, - lifespan=lifespan_with_security, - root_routers=ROOT_ROUTERS, - installers=(*INSTALLERS, tracing_install), - docs_guard=DOCS_GUARD, -) +```toml +[app] +paths = ["backend/src/infrastructure/observability.py"] + +[app.contributes] +installers = ["src.infrastructure.observability:install as tracing_install"] +``` + +```bash +fastro sync ``` -Not `src/wiring/app.py`. The removal drill generates the wiring modules from -`tools/removal_drill.py`, and `tests/unit/test_removal_drill.py` compares what it generates with -what the project committed, so an installer written into `INSTALLERS` by hand fails that test. -`main.py` is the composition root, and nothing regenerates it. A project that would rather have -the generator know about this one makes it a feature -([below](#if-you-turn-this-into-a-feature)). +`fastro sync` adds `tracing_install` to `INSTALLERS` in `src/wiring/app.py`, after the features' +installers, and the app calls it as it's built. Don't write it into `src/wiring/app.py` by hand: +fastro generates that file from `fastro.toml`, so `fastro sync --check` fails on a hand edit and +the next `fastro sync` undoes it. `[app].paths` marks the module as your own code. + +In a generated project, `fastro sync` and `fastro sync --check` need a fastro release with +project-mode sync, so until one ships, add +`from ..infrastructure.observability import install as tracing_install` to `src/interfaces/main.py` +and change its `installers=INSTALLERS,` line to `installers=(*INSTALLERS, tracing_install),`, then +undo that edit the first time you run `fastro sync`, or the app installs tracing twice. `send_to_logfire="if-token-present"` is what keeps it off: with no `LOGFIRE_TOKEN` in the environment, nothing leaves the process, which is the same rule every other optional thing in this @@ -95,10 +97,10 @@ are defaults a deployment can override without touching the code. !!! note "The worker is a second process" `taskiq worker src.infrastructure.taskiq.worker:default_broker` never imports `main.py`, - so none of the above runs there. Call `configure_tracing()` in - `src/infrastructure/taskiq/worker.py` as well, with `service_name="worker"`, and the two - processes report separately. A task enqueued by a request is not joined to that request's trace - unless you propagate the context yourself (`logfire.propagate`). + so none of the above runs there. Call `configure_tracing(service_name="worker")` in + `src/infrastructure/taskiq/worker.py` as well, and the two processes report separately. A task + enqueued by a request is not joined to that request's trace unless you propagate the context + yourself (`logfire.propagate`). ## What not to send @@ -148,9 +150,10 @@ proxy's own access logs already cover whether the app is up and how fast it answ ## If you turn this into a feature -A project that wants observability to be removable like the others gives it a `FEATURES` entry in -`tools/removal_drill.py` — the `observability` module, its tests, and its contribution to -`src/wiring/app.py` — and settings that are off when unset. See +In a project, the module above is your own code, under `[app]`. Observability becomes a removable +feature only in FastAPI-boilerplate itself, as a `[features.observability]` table in its +`blueprint.toml`: its `paths` own the module and its tests, `[features.observability.contributes]` +lists the installer, and its settings are off when unset. See [Composable Features](composable-features.md). ## Key Files @@ -162,8 +165,8 @@ A project that wants observability to be removable like the others gives it a `F | Refused-login audit hooks | `backend/src/infrastructure/auth/audit.py` | | API-key usage rows | `backend/src/modules/api_keys/usage.py` | | The catch-all handler and its support id | `backend/src/modules/common/utils/error_handler.py` | -| Where this recipe wires its installer | `backend/src/interfaces/main.py` | -| Where a feature's installer is wired | `backend/src/wiring/app.py` | +| Where this recipe registers its installer | `fastro.toml`, under `[app.contributes]` | +| Where every installer is wired, generated by `fastro sync` | `backend/src/wiring/app.py` | --- diff --git a/docs/user-guide/production.md b/docs/user-guide/production.md index 9b1b61ed..a68d2e11 100644 --- a/docs/user-guide/production.md +++ b/docs/user-guide/production.md @@ -18,11 +18,11 @@ The app **will not start** if any of these is true: those is measured as a share of the whole value, so a generated key that happens to spell a word still passes. Two rules are absolute: a run of eight consecutive code points, and under 64 bits of entropy. The tests sweep 100,000 keys of each shape a generator produces — the hex keys - `bp env gen-secret` prints (`secrets.token_hex(16/32)`) and `secrets.token_urlsafe(24/32)` keys + `fastro env secret` prints (`secrets.token_hex(16/32)`) and `secrets.token_urlsafe(24/32)` keys from whatever else you might use — from a fixed seed, and none of the 400,000 is refused. A random key can still trip a rule: one hex key in 12.6 million runs through eight consecutive digits, and a `token_urlsafe` key walks the keyboard at around one in ten million. Run inside a - project, `bp env gen-secret` checks each draw against those rules and draws again while they + project, `fastro env secret` checks each draw against those rules and draws again while they would refuse it. - **The database password is `postgres`** (the well-known default). Attackers try this first. - **The database password is empty.** Database is unprotected. @@ -260,7 +260,7 @@ The proxy must: Set `TRUSTED_PROXY_HOPS` to the number of reverse proxies you've put in front of the app (1 for a single nginx/Caddy, 2 if Cloudflare is also in front). crudauth uses it to read the real client IP from the last trusted hop of `X-Forwarded-For` when applying login lockout — otherwise every request would appear to come from the proxy and the lockout would key on a single IP. -Set `FORWARDED_ALLOW_IPS` to your proxy's address or subnet. **uvicorn** reads it from its own process environment, not through the app's settings, and it decides what `request.client` and the access logs report. A wildcard makes uvicorn take the *leftmost* `X-Forwarded-For` entry, which is whatever the client sent, so any client can claim any address and say its request arrived over HTTPS. Named a subnet, uvicorn skips the entries from that subnet and reads the last one outside it. The generated nginx vhost also replaces `X-Forwarded-For` with the address nginx saw, so there is only ever one entry to read. The generated stack puts the containers on a fixed subnet and sets this to that CIDR; `bp deploy generate nginx --internal-subnet 10.20.30.0/24` changes both together, and refuses host bits, a wildcard, or a range wider than `/8` (IPv4) or `/48` (IPv6). +Set `FORWARDED_ALLOW_IPS` to your proxy's address or subnet. **uvicorn** reads it from its own process environment, not through the app's settings, and it decides what `request.client` and the access logs report. A wildcard makes uvicorn take the *leftmost* `X-Forwarded-For` entry, which is whatever the client sent, so any client can claim any address and say its request arrived over HTTPS. Named a subnet, uvicorn skips the entries from that subnet and reads the last one outside it. The generated nginx vhost also replaces `X-Forwarded-For` with the address nginx saw, so there is only ever one entry to read. The generated stack puts the containers on a fixed subnet and sets this to that CIDR; `fastro make deploy nginx --internal-subnet 10.20.30.0/24` changes both together, and refuses host bits, a wildcard, or a range wider than `/8` (IPv4) or `/48` (IPv6). !!! warning "nginx is the only hop in the generated stack" diff --git a/docs/user-guide/project-structure.md b/docs/user-guide/project-structure.md index cd6fcd2a..74d7d3e1 100644 --- a/docs/user-guide/project-structure.md +++ b/docs/user-guide/project-structure.md @@ -29,16 +29,19 @@ backend/ │ ├── script.py.mako │ └── versions/ ├── scripts/ # Setup and maintenance scripts +│ ├── baseline.py # Writes the project's first migration, checked against the models │ ├── canonicalize_emails.py │ ├── cleanup_api_key_json.py │ ├── create_first_superuser.py │ ├── create_first_tier.py │ ├── create_tables.py +│ ├── gen_secret.py # Prints a SECRET_KEY the project's own rules accept │ ├── prune_key_usage.py # The usage prune, for a project with no worker to schedule it │ ├── revoke_scrypt_api_keys.py │ ├── seeders.py # The seeders the selected features contribute │ ├── setup_initial_data.py -│ └── unlock_account.py +│ ├── unlock_account.py +│ └── validate_env.py # Audits the environment the way production would ├── src/ # Application source (the three layers below) └── tests/ # Test suite (unit + integration) ``` @@ -176,6 +179,8 @@ wiring/ ├── tables.py # TABLE_MODULES, declaring tables outside src/modules ├── transports.py # EXTRA_TRANSPORTS, registered beside the session transport ├── cache.py # cached, the decorator a route caches its response with +├── scope.py # SCOPE_FINGERPRINT, which keeps a scoped credential's cached responses its own +├── signup.py # NEW_ACCOUNT_FIELDS, the columns features set on a new account └── admin.py # ADMIN_VIEWS (absent without the admin feature) ``` @@ -205,9 +210,12 @@ scripts/ ├── create_first_superuser.py # Just the admin user ├── create_first_tier.py # Just the default tier ├── create_tables.py # Just the database tables +├── baseline.py # Writes the project's first migration, checked against the models ├── cleanup_api_key_json.py # One-off repair for legacy API key rows ├── canonicalize_emails.py # One-off repair for addresses stored with case or spaces ├── unlock_account.py # Clears the login lockout one account is held in +├── gen_secret.py # Prints a SECRET_KEY the project's own rules accept +├── validate_env.py # Audits the environment the way production would ├── revoke_scrypt_api_keys.py # Names the API keys still stored as scrypt, revokes them on request └── prune_key_usage.py # Deletes the API-key usage rows past KEY_USAGE_RETENTION_DAYS ``` @@ -340,7 +348,7 @@ The recommended flow: 6. **Expose routes**: `backend/src/modules/widgets/routes.py` 7. **Register the router**: add a `RouterMount` to `ROUTER_MOUNTS` in `backend/src/wiring/app.py` 8. **Wire the rest of it**: its settings mixin in `wiring/settings.py`, its hook contributions in `wiring/hooks.py`, its admin views in `wiring/admin.py`, its fixtures in `tests/wiring.py` — whichever it has -9. **Add it to the removal drill**: list its paths in `tools/removal_drill.py` so a build without it is checked +9. **Declare it in the catalog**: list its paths under its feature's table in `blueprint.toml`, so `fastro blueprint verify` checks a build without it 10. **Generate a migration**: `uv run --no-sync alembic revision --autogenerate -m "add widgets"` 11. **Apply**: `uv run --no-sync alembic upgrade head` diff --git a/docs/user-guide/rate-limiting/index.md b/docs/user-guide/rate-limiting/index.md index 3aaae4bd..19a84f01 100644 --- a/docs/user-guide/rate-limiting/index.md +++ b/docs/user-guide/rate-limiting/index.md @@ -325,7 +325,7 @@ closed). Fix the Redis connection, or take the limiter out of the path entirely | Resolver + dependency | `backend/src/infrastructure/auth/setup.py` | | RateLimit model | `backend/src/modules/rate_limit/models.py` | | Rate-limit routes | `backend/src/modules/rate_limit/routes.py` | -| Settings | `backend/src/infrastructure/config/settings.py` (`RateLimiterSettings`) | +| Settings | `backend/src/infrastructure/ratelimit/settings.py` (`RateLimitSettings`), `backend/src/infrastructure/auth/settings.py` (`LimiterBackendSettings`) | ## Next Steps diff --git a/docs/user-guide/testing.md b/docs/user-guide/testing.md index 920959ad..7f3da53f 100644 --- a/docs/user-guide/testing.md +++ b/docs/user-guide/testing.md @@ -354,10 +354,10 @@ uv run --no-sync pytest --cov=src --cov-report=term-missing ## Continuous Integration The repo's `.github/workflows/tests.yml` runs the test suite on PRs, along with the linting and -type-checking workflows and a matrix job that runs `tools/removal_drill.py` for every preset. The -workflows install the workspace from the repo root with `uv sync --all-packages --all-extras ---locked`, then `cd backend` for the suite, so the same `uv run --no-sync pytest` works there as -locally. +type-checking workflows and a matrix job that runs `fastro blueprint verify` for each set it +builds: the catalog's `[verify.sets]`, the presets and `everything`, one job each. The workflows +install the workspace from the repo root with `uv sync --all-packages --all-extras --locked`, +then `cd backend` for the suite, so the same `uv run --no-sync pytest` works there as locally. CI runs the whole suite, integration tests included: `.github/workflows/tests.yml` syncs the workspace and runs `pytest` on an `ubuntu-latest` runner, where Docker is available, so diff --git a/fastro.toml b/fastro.toml new file mode 100644 index 00000000..07e5abf0 --- /dev/null +++ b/fastro.toml @@ -0,0 +1,10 @@ +source = true +features = ["accounts", "rbac", "ratelimit", "tiers", "tier_limits", "api_keys", "admin", "cache", "taskiq"] +blueprint = { name = "fastapi-boilerplate", version = "0.20.0" } + +[project] +name = "fastapi-boilerplate" + +[options] +"cache.backend" = "redis" +"taskiq.broker" = "redis" diff --git a/pyproject.toml b/pyproject.toml index 7aa03036..fbdef785 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,28 +1,37 @@ # Workspace root. # -# This file exists so `uv` recognizes the repo as a workspace and can resolve -# both the `backend/` (deployable application) and `cli/` (developer/operator -# tool) packages from a single venv. It is NOT a deployable package itself — -# nothing here ships to production. +# This file exists so `uv` resolves the repo as a workspace whose one member is `backend/` +# (the deployable application), and installs the blueprint's own tools, fastro among them, +# into the same venv. It is NOT a deployable package itself: nothing here ships to production. # # Most commands work from anywhere in the repo: # -# uv sync --all-packages --all-extras # one venv shared by all members -# uv run bp ... # runs the CLI from cli/, from any cwd +# uv sync --all-packages --all-extras # one venv: the backend and the root's dev group +# uv run --no-sync fastro ... # runs fastro, from any cwd # cd backend && uv run --no-sync pytest # runs the backend test suite +# uv run --no-sync pytest # runs the blueprint's own tests # -# To install `bp` machine-wide so it works outside this repo: -# -# uv tool install --editable ./cli +# The backend's tests run under their own root: `backend/tests/conftest.py` declares +# `pytest_plugins`, which pytest only reads from the root's top-level conftest. So the root's +# testpaths name the blueprint's tests and nothing else. [project] name = "fastapi-boilerplate-workspace" version = "0" -description = "Workspace root — see backend/ and cli/ for actual packages." +description = "Workspace root; the application is in backend/." requires-python = ">=3.11" +[dependency-groups] +dev = ["fastro", "packaging>=24.0", "pyyaml>=6.0.2", "types-pyyaml>=6.0.12"] + [tool.uv.workspace] -members = ["backend", "cli"] +members = ["backend"] + +[tool.uv.sources] +fastro = { git = "https://github.com/benavlabs/fastro", rev = "640caae2d6f7c129ab0f03ee6a34088d4dede65f" } + +[tool.pytest.ini_options] +testpaths = ["blueprint/tests"] [tool.ruff] line-length = 128 diff --git a/tools/removal_drill.py b/tools/removal_drill.py deleted file mode 100644 index 334d1a06..00000000 --- a/tools/removal_drill.py +++ /dev/null @@ -1,808 +0,0 @@ -"""Prove a feature can be removed: build a project without it and check it holds up. - -Copies the repository to a scratch directory, deletes the paths of every feature -the preset leaves out, regenerates ``src/wiring/*``, ``scripts/seeders.py`` and -``tests/wiring.py`` for what remains, then checks that the app imports, that ruff -passes and that the remaining tests pass. - - python tools/removal_drill.py # every preset - python tools/removal_drill.py accounts-only # one of them - python tools/removal_drill.py --keep # leave the scratch copies behind - -A failing check, or a build that raises, prints the end of what it printed and leaves -its scratch copy on disk whether or not ``--keep`` was passed. -""" - -from __future__ import annotations - -import argparse -import shutil -import subprocess -import sys -import tempfile -from dataclasses import dataclass, field -from pathlib import Path - -REPO = Path(__file__).resolve().parent.parent - - -@dataclass(frozen=True) -class Feature: - """What a feature owns, and what it contributes to the wiring.""" - - paths: tuple[str, ...] = () - combination_paths: dict[str, tuple[str, ...]] = field(default_factory=dict) - - -FEATURES: dict[str, Feature] = { - "accounts": Feature( - paths=( - "backend/src/infrastructure/auth", - "backend/src/modules/user", - "backend/scripts/create_first_superuser.py", - "backend/scripts/canonicalize_emails.py", - "backend/scripts/unlock_account.py", - "backend/tests/unit/scripts/test_create_first_superuser.py", - "backend/tests/unit/scripts/test_unlock_account.py", - "backend/tests/unit/scripts/test_setup_initial_data.py", - "backend/tests/unit/scripts/test_canonicalize_emails.py", - "backend/tests/fixtures/accounts.py", - "backend/tests/integration/auth", - "backend/tests/integration/api/v1/users", - "backend/tests/integration/accounts", - "backend/tests/unit/infrastructure/auth", - "backend/tests/unit/modules/user", - ), - ), - "rbac": Feature( - paths=( - "backend/src/modules/role", - "backend/tests/unit/modules/role", - "backend/tests/integration/rbac", - ), - ), - "ratelimit": Feature( - paths=( - "backend/src/infrastructure/ratelimit", - "backend/tests/unit/infrastructure/ratelimit", - "backend/tests/integration/ratelimit", - ), - ), - "tiers": Feature( - paths=( - "backend/src/modules/tier", - "backend/scripts/create_first_tier.py", - "backend/tests/fixtures/tiers.py", - "backend/tests/unit/modules/tier", - "backend/tests/integration/tiers", - ), - combination_paths={ - "admin": ( - "backend/src/modules/tier/admin.py", - "backend/tests/unit/modules/tier/test_admin.py", - ) - }, - ), - "tier_limits": Feature( - paths=( - "backend/src/modules/rate_limit", - "backend/tests/unit/modules/rate_limit", - "backend/tests/integration/tier_limits", - ), - ), - "api_keys": Feature( - paths=( - "backend/src/modules/api_keys", - "backend/scripts/cleanup_api_key_json.py", - "backend/scripts/prune_key_usage.py", - "backend/scripts/revoke_scrypt_api_keys.py", - "backend/tests/unit/modules/api_keys", - "backend/tests/integration/api/v1/api_keys", - ), - combination_paths={ - "taskiq": ( - "backend/src/modules/api_keys/tasks.py", - "backend/tests/unit/modules/api_keys/test_tasks.py", - ), - "rbac": ("backend/tests/integration/api_keys_rbac",), - "ratelimit": ("backend/tests/integration/api_keys_ratelimit",), - "tier_limits": ("backend/tests/integration/api_keys_tiers",), - }, - ), - "admin": Feature( - paths=( - "backend/src/interfaces/admin", - "backend/tests/unit/interfaces/admin", - "backend/src/wiring/admin.py", - ), - combination_paths={ - "accounts": ( - "backend/src/modules/user/admin.py", - "backend/tests/unit/modules/user/test_admin.py", - ), - "tiers": ( - "backend/src/modules/tier/admin.py", - "backend/tests/unit/modules/tier/test_admin.py", - ), - "rbac": ( - "backend/src/modules/role/admin.py", - "backend/tests/unit/modules/role/test_admin.py", - ), - }, - ), - "cache": Feature( - paths=( - "backend/src/infrastructure/cache", - "backend/tests/unit/infrastructure/cache", - ), - ), - "taskiq": Feature( - paths=( - "backend/src/infrastructure/taskiq", - "backend/tests/unit/infrastructure/taskiq", - ), - combination_paths={ - "accounts": ( - "backend/src/infrastructure/taskiq/email.py", - "backend/tests/unit/infrastructure/taskiq/test_email.py", - ), - }, - ), -} - -REQUIRES = { - "rbac": ("accounts",), - "ratelimit": ("accounts",), - "tiers": ("accounts",), - "tier_limits": ("tiers", "ratelimit"), - "api_keys": ("accounts",), - "admin": ("accounts",), -} - -PRESETS: dict[str, tuple[str, ...]] = { - "core-only": (), - "core-taskiq": ("taskiq",), - "accounts-only": ("accounts",), - "accounts-rbac": ("accounts", "rbac"), - "accounts-admin": ("accounts", "admin"), - "accounts-api-keys": ("accounts", "api_keys"), - "accounts-rbac-tiers": ("accounts", "rbac", "tiers", "ratelimit"), - "accounts-cache-taskiq": ("accounts", "cache", "taskiq"), - "everything": tuple(FEATURES), -} - - -COPY_EXCLUDES = ( - ".git", - ".venv", - ".env", - "bp-and-fastro", - "site", - "__pycache__", - ".mypy_cache", - ".ruff_cache", -) - - -def _selected_from(features: tuple[str, ...]) -> set[str]: - """``features`` and everything they need, all the way down.""" - chosen = set(features) - pending = list(chosen) - while pending: - for required in REQUIRES.get(pending.pop(), ()): - if required not in chosen: - chosen.add(required) - pending.append(required) - - return chosen - - -def _selected(preset: str) -> set[str]: - """The preset's features, and everything they need.""" - return _selected_from(PRESETS[preset]) - - -def _wiring_settings(chosen: set[str]) -> str: - mixins = [ - ( - "accounts", - "from ..infrastructure.auth.settings import AccountsSettings", - "AccountsSettings", - ), - ( - "ratelimit", - "from ..infrastructure.ratelimit.settings import RateLimitSettings", - "RateLimitSettings", - ), - ("tiers", "from ..modules.tier.settings import TierSettings", "TierSettings"), - ( - "api_keys", - "from ..modules.api_keys.settings import APIKeySettings", - "APIKeySettings", - ), - ( - "admin", - "from ..interfaces.admin.settings import SQLAdminSettings", - "SQLAdminSettings", - ), - ( - "cache", - "from ..infrastructure.cache.settings import CacheSettings", - "CacheSettings", - ), - ( - "taskiq", - "from ..infrastructure.taskiq.settings import TaskiqSettings", - "TaskiqSettings", - ), - ] - imports = ["from ..infrastructure.config.base import CoreSettings"] - bases = [] - for feature, line, name in mixins: - if feature in chosen: - imports.append(line) - bases.append(name) - bases.append("CoreSettings") - body = ",\n ".join(bases) - return ( - '"""The project\'s settings: each selected feature\'s mixin on top of the core."""\n\n' - + "\n".join(sorted(imports)) - + f"\n\n\nclass Settings(\n {body},\n):\n" - ' """The settings of every selected feature, on top of the core."""\n\n\nsettings = Settings()\n' - ) - - -def _wiring_app(chosen: set[str]) -> str: - fastapi_names = "APIRouter, Depends, FastAPI" if "ratelimit" in chosen else "APIRouter, FastAPI" - imports = [ - "from collections.abc import Callable", - "from typing import Any", - "", - f"from fastapi import {fastapi_names}", - "", - "from ..infrastructure.composition import Lifecycle, RouterMount", - ] - root_routers = "()" - throttle = "()" - lifecycles: list[str] = [] - installers: list[str] = [] - docs_guard = "None" - - user_mounts: list[str] = [] - collection_mounts: list[str] = [] - - if "accounts" in chosen: - imports += [ - "from ..infrastructure.auth.dependencies import get_current_superuser", - "from ..infrastructure.auth.install import install as accounts_install", - "from ..infrastructure.auth.routes import root_routers as accounts_root_routers", - "from ..infrastructure.auth.routes import router as auth_router", - "from ..infrastructure.auth.setup import lifecycle as accounts_lifecycle", - "from ..modules.user.routes import router as users_router", - ] - user_mounts.append('RouterMount(users_router, "/users", throttled=True)') - root_routers = "accounts_root_routers" - lifecycles.append("accounts_lifecycle") - installers.append("accounts_install") - docs_guard = "get_current_superuser" - if "ratelimit" in chosen: - imports.append("from ..infrastructure.ratelimit.dependency import api_rate_limit_dependency") - throttle = "(Depends(api_rate_limit_dependency),)" - if "tiers" in chosen: - imports += [ - "from ..modules.tier.routes import router as tiers_router", - "from ..modules.tier.routes import user_tier_router", - ] - user_mounts.append('RouterMount(user_tier_router, "/users", throttled=True)') - collection_mounts.append('RouterMount(tiers_router, "/tiers", throttled=True)') - if "tier_limits" in chosen: - imports += [ - "from ..modules.rate_limit.routes import router as rate_limits_router", - "from ..modules.rate_limit.routes import user_rate_limits_router", - ] - user_mounts.append('RouterMount(user_rate_limits_router, "/users", throttled=True)') - collection_mounts.append('RouterMount(rate_limits_router, "/rate-limits", throttled=True)') - if "accounts" in chosen: - collection_mounts.append('RouterMount(auth_router, "/auth", throttled=False)') - if "api_keys" in chosen: - imports.append("from ..modules.api_keys.install import install as api_keys_install") - imports.append("from ..modules.api_keys.routes import router as api_keys_router") - collection_mounts.append('RouterMount(api_keys_router, "/api-keys", throttled=True)') - installers.append("api_keys_install") - if "rbac" in chosen: - imports.append("from ..modules.role.routes import permissions_router, user_roles_router") - imports.append("from ..modules.role.routes import router as roles_router") - user_mounts.append('RouterMount(user_roles_router, "/users", throttled=True)') - collection_mounts.append('RouterMount(permissions_router, "/permissions", throttled=True)') - collection_mounts.append('RouterMount(roles_router, "/roles", throttled=True)') - if "cache" in chosen: - imports.append("from ..infrastructure.cache.initialize import lifecycle as cache_lifecycle") - lifecycles.append("cache_lifecycle") - if "taskiq" in chosen: - imports.append("from ..infrastructure.taskiq.lifecycle import lifecycle as taskiq_lifecycle") - lifecycles.append("taskiq_lifecycle") - elif "accounts" in chosen: - imports.append("from ..infrastructure.handover import lifecycle as handover_lifecycle") - lifecycles.append("handover_lifecycle") - if "admin" in chosen: - imports.append("from ..interfaces.admin.initialize import install as admin_install") - installers.append("admin_install") - - mounts = user_mounts + collection_mounts - - def tuple_of(items: list[str]) -> str: - return "(\n " + ",\n ".join(items) + ",\n)" if items else "()" - - return ( - '"""The composition root: what the app mounts, starts and installs."""\n\n' - + "\n".join(imports) - + f"\n\nROUTER_MOUNTS: tuple[RouterMount, ...] = {tuple_of(mounts)}\n" - f"ROOT_ROUTERS: tuple[APIRouter, ...] = {root_routers}\n" - f"API_THROTTLE: tuple[Any, ...] = {throttle}\n" - f"LIFECYCLES: tuple[Lifecycle, ...] = {tuple_of(lifecycles)}\n" - f"INSTALLERS: tuple[Callable[[FastAPI], None], ...] = {tuple_of(installers)}\n" - f"DOCS_GUARD: Callable[..., Any] | None = {docs_guard}\n" - ) - - -def _wiring_hooks(chosen: set[str]) -> str: - imports = [ - "from ..infrastructure.composition import (\n" - " PermissionSource,\n" - " RateLimitResolver,\n" - " ReadinessCheck,\n" - " TierDeleteGuard,\n" - " TierDeleteRelease,\n" - ")", - "from ..infrastructure.database.health import readiness as database_readiness", - "from ..infrastructure.database.health import schema_readiness", - ] - sources = "()" - resolvers = "()" - guards = "()" - releases = "()" - critical = ["database_readiness", "schema_readiness"] - informational: list[str] = [] - - if "rbac" in chosen: - imports.append("from ..modules.role.sources import role_permissions") - sources = "(role_permissions,)" - if "tier_limits" in chosen: - imports.append( - "from ..modules.rate_limit.hooks import rate_limits_reference_tier, release_deleted_rate_limits, tier_rate_limit" - ) - resolvers = "(tier_rate_limit,)" - guards = "(rate_limits_reference_tier,)" - releases = "(release_deleted_rate_limits,)" - if "accounts" in chosen: - imports.append("from ..infrastructure.auth.health import limiter_readiness, sessions_readiness") - critical.extend(["limiter_readiness", "sessions_readiness"]) - if "cache" in chosen: - imports.append("from ..infrastructure.cache.health import readiness as cache_readiness") - informational.append("cache_readiness") - if "taskiq" in chosen: - imports.append("from ..infrastructure.taskiq.health import readiness as broker_readiness") - informational.append("broker_readiness") - - critical_checks = "(" + ", ".join(critical) + ",)" - informational_checks = ("(" + ", ".join(informational) + ",)") if informational else "()" - - return ( - '''"""The contributions features make to each other\'s extension points."""\n\n''' - + "\n".join(sorted(imports)) - + f"\n\nPERMISSION_SOURCES: tuple[PermissionSource, ...] = {sources}\n" - f"RATE_LIMIT_RESOLVERS: tuple[RateLimitResolver, ...] = {resolvers}\n" - f"TIER_DELETE_GUARDS: tuple[TierDeleteGuard, ...] = {guards}\n" - f"TIER_DELETE_RELEASES: tuple[TierDeleteRelease, ...] = {releases}\n" - f"CRITICAL_READINESS_CHECKS: tuple[ReadinessCheck, ...] = {critical_checks}\n" - f"INFORMATIONAL_READINESS_CHECKS: tuple[ReadinessCheck, ...] = {informational_checks}\n" - ) - - -def _wiring_tasks(chosen: set[str]) -> str: - """The modules whose background tasks the worker registers.""" - declared = [ - ("accounts", "src.infrastructure.taskiq.email"), - ("api_keys", "src.modules.api_keys.tasks"), - ] - registered = tuple(module for feature, module in declared if {feature, "taskiq"} <= chosen) - modules = repr(registered) if registered else "()" - - return f'"""The modules whose background tasks the worker registers."""\n\nTASK_MODULES: tuple[str, ...] = {modules}\n' - - -def _wiring_email(chosen: set[str]) -> str: - """The sender the account emails go out through: queued where there is a worker. - - Either way the request does not wait for it: without a queue the message is handed - over to be delivered after the answer. - """ - if {"accounts", "taskiq"} <= chosen: - source = "from ..infrastructure.taskiq.email import queued_sender" - sender = "queued_sender" - else: - source = ( - "from ..infrastructure.email.factory import build_sender\n" - "from ..infrastructure.email.senders import HandingOverSender" - ) - sender = "HandingOverSender(build_sender())" - - return ( - '"""The sender the account emails go out through."""\n\n' - "from crudauth import EmailSender\n\n" - f"{source}\n\n" - f"EMAIL_SENDER: EmailSender = {sender}\n" - ) - - -def _wiring_tables(chosen: set[str]) -> str: - """The modules outside ``src/modules`` whose tables belong on ``Base.metadata``.""" - docstring = '"""Modules outside ``src/modules`` that declare tables on ``Base.metadata``."""\n\n' - modules = ['"src.infrastructure.auth.store"'] if "accounts" in chosen else [] - listed = f"({modules[0]},)" if modules else "()" - - return f"{docstring}TABLE_MODULES: tuple[str, ...] = {listed}\n" - - -def _wiring_transports(chosen: set[str]) -> str: - """The authentication transports registered beside the session one.""" - docstring = '"""The authentication transports this project registers beside the session one."""\n\n' - if "api_keys" not in chosen: - return f"{docstring}from crudauth import Transport\n\nEXTRA_TRANSPORTS: tuple[Transport, ...] = ()\n" - - return ( - f"{docstring}" - "from crudauth import Transport\n\n" - "from ..modules.api_keys.transport import APIKeyTransport\n\n" - "EXTRA_TRANSPORTS: tuple[Transport, ...] = (APIKeyTransport(),)\n" - ) - - -def _wiring_cache(chosen: set[str]) -> str: - """The decorator a route caches its response with: the real one where there is a cache.""" - if "cache" in chosen: - source = "from ..infrastructure.cache.decorator import cache as cached" - else: - source = "from ..infrastructure.uncached import cached" - - return f'"""The decorator a route caches its response with."""\n\n{source}\n\n__all__ = ["cached"]\n' - - -def _wiring_models(chosen: set[str]) -> str: - imports: list[str] = [] - model_bases, schema_bases = [], [] - if "rbac" in chosen: - imports.append("from ..modules.role.contrib import UserRoleColumns") - model_bases.append("UserRoleColumns") - if "tiers" in chosen: - imports.append("from ..modules.tier.contrib import UserTierColumns, UserTierFields") - model_bases.append("UserTierColumns") - schema_bases.append("UserTierFields") - model_line = ", ".join(model_bases) if model_bases else "" - schema_line = ", ".join(schema_bases) if schema_bases else "BaseModel" - if not schema_bases: - imports.append("from pydantic import BaseModel") - return ( - '"""Extension points of the user model: what other features add to ``User``."""\n\n' - + "\n".join(sorted(imports)) - + f"\n\n\nclass UserModelExtensions({model_line}):\n" - ' """Columns and relationships other features add to ``User``."""\n\n\n' - f"class UserSchemaExtensions({schema_line}):\n" - ' """Fields other features add to the user read schemas."""\n' - ) - - -def _wiring_admin(chosen: set[str]) -> str: - imports, views = [], [] - if "accounts" in chosen: - imports.append("from ..modules.user.admin import UserAdmin") - views.append("UserAdmin") - if "tiers" in chosen: - imports.append("from ..modules.tier.admin import TierAdmin") - views.append("TierAdmin") - if "rbac" in chosen: - imports.append("from ..modules.role.admin import RoleAdmin, RolePermissionAdmin, UserRoleAdmin") - views.extend(["RoleAdmin", "RolePermissionAdmin", "UserRoleAdmin"]) - body = "(\n " + ",\n ".join(views) + ",\n)" if views else "()" - return ( - '"""The model views the admin panel registers."""\n\n' - + "\n".join(sorted(imports)) - + f"\n\nADMIN_VIEWS: tuple[type, ...] = {body}\n" - ) - - -def _seeders(chosen: set[str]) -> str: - imports, seeds = [], [] - if "tiers" in chosen: - imports.append("from scripts.create_first_tier import create_first_tier") - seeds.append("create_first_tier") - if "accounts" in chosen: - imports.append("from scripts.create_first_superuser import create_first_superuser") - seeds.append("create_first_superuser") - body = "(\n " + ",\n ".join(seeds) + ",\n)" if seeds else "()" - imports.append("from collections.abc import Awaitable, Callable") - return ( - '"""The initial-data steps ``scripts/setup_initial_data.py`` runs, in order."""\n\n' - + "\n".join(sorted(imports)) - + f"\n\nSEEDERS: tuple[Callable[[], Awaitable[None]], ...] = {body}\n" - ) - - -def _tests_wiring(chosen: set[str]) -> str: - plugins = [] - if "accounts" in chosen: - plugins.append('"tests.fixtures.accounts"') - if "tiers" in chosen: - plugins.append('"tests.fixtures.tiers"') - body = "[\n " + ",\n ".join(plugins) + ",\n]" if plugins else "[]" - return ( - '"""Fixture modules of the selected features, loaded by ``tests/conftest.py``."""\n\n' - f"PYTEST_PLUGINS: list[str] = {body}\n" - ) - - -def copy_repository(source: Path, project: Path) -> None: - """Copy ``source`` to ``project``, leaving out what a scratch build must not carry.""" - shutil.copytree( - source, - project, - ignore=shutil.ignore_patterns(*COPY_EXCLUDES), - ) - - -def build(preset: str, into: Path) -> Path: - """Copy the repo into ``into`` and strip it down to ``preset``.""" - chosen = _selected(preset) - project = into / preset - copy_repository(REPO, project) - - for name, feature in FEATURES.items(): - if name in chosen: - for partner, paths in feature.combination_paths.items(): - if partner not in chosen: - for path in paths: - _remove(project / path) - continue - for path in feature.paths: - _remove(project / path) - for paths in feature.combination_paths.values(): - for path in paths: - _remove(project / path) - - (project / "backend/src/wiring/settings.py").write_text(_wiring_settings(chosen)) - (project / "backend/src/wiring/app.py").write_text(_wiring_app(chosen)) - (project / "backend/src/wiring/hooks.py").write_text(_wiring_hooks(chosen)) - (project / "backend/src/wiring/email.py").write_text(_wiring_email(chosen)) - (project / "backend/src/wiring/tasks.py").write_text(_wiring_tasks(chosen)) - (project / "backend/src/wiring/tables.py").write_text(_wiring_tables(chosen)) - (project / "backend/src/wiring/transports.py").write_text(_wiring_transports(chosen)) - (project / "backend/src/wiring/cache.py").write_text(_wiring_cache(chosen)) - (project / "backend/src/wiring/models.py").write_text(_wiring_models(chosen)) - if "admin" in chosen: - (project / "backend/src/wiring/admin.py").write_text(_wiring_admin(chosen)) - (project / "backend/scripts/seeders.py").write_text(_seeders(chosen)) - (project / "backend/tests/wiring.py").write_text(_tests_wiring(chosen)) - - _format(project) - - return project - - -def _format(project: Path) -> None: - """A generator emits formatted code; so does this one.""" - generated = ["src/wiring", "scripts/seeders.py", "tests/wiring.py"] - for command in (["--fix", "-q"], ["--select", "I", "--fix", "-q"]): - subprocess.run( - [sys.executable, "-m", "ruff", "check", *command, *generated], - cwd=project / "backend", - capture_output=True, - ) - subprocess.run( - [sys.executable, "-m", "ruff", "format", "-q", *generated], - cwd=project / "backend", - capture_output=True, - ) - - -def _remove(path: Path) -> None: - if path.is_dir(): - shutil.rmtree(path) - elif path.exists(): - path.unlink() - - -_IMPORT_EVERY_MODULE = """ -import importlib, pathlib, sys - -broken = [] -for path in sorted(pathlib.Path("src").rglob("*.py")): - module = ".".join(path.with_suffix("").parts).removesuffix(".__init__") - try: - importlib.import_module(module) - except Exception as error: - broken.append(f"{module}: {type(error).__name__}: {error}") - -if broken: - sys.exit("modules left behind by the removed features: " + "; ".join(broken)) - -print("every module imports") -""" - - -_MIGRATION_BASELINE = r""" -import asyncio -import os -import subprocess -import sys -import warnings -from pathlib import Path - -warnings.simplefilter("ignore") -os.environ["TESTCONTAINERS_RYUK_DISABLED"] = "true" - -from testcontainers.postgres import PostgresContainer - -VERSIONS = Path("migrations/versions") - - -def alembic(*arguments): - return subprocess.run([sys.executable, "-m", "alembic", *arguments], capture_output=True, text=True) - - -async def schema_of(engine): - from sqlalchemy import inspect - - def read(sync): - inspector = inspect(sync) - - def indexes(table): - found = inspector.get_indexes(table) - - return sorted(index["name"] for index in found if not index.get("duplicates_constraint")) - - return {table: indexes(table) for table in sorted(inspector.get_table_names())} - - async with engine.connect() as connection: - return await connection.run_sync(read) - - -with PostgresContainer("postgres:16-alpine") as postgres: - os.environ.update( - POSTGRES_SERVER=postgres.get_container_host_ip(), - POSTGRES_PORT=str(postgres.get_exposed_port(5432)), - POSTGRES_USER=postgres.username, - POSTGRES_PASSWORD=postgres.password, - POSTGRES_DB=postgres.dbname, - ) - - from src.infrastructure.database.registry import import_models - from src.infrastructure.database.session import Base, build_engine - - import_models() - declared = { - name: sorted(index.name for index in table.indexes if index.name is not None) - for name, table in Base.metadata.tables.items() - } - declared["alembic_version"] = [] - - autogenerated = alembic("revision", "--autogenerate", "-m", "baseline") - if autogenerated.returncode != 0: - sys.exit("autogenerate failed:\n" + autogenerated.stdout + autogenerated.stderr) - - written = sorted(VERSIONS.glob("*.py")) - if len(written) != 1: - sys.exit(f"autogenerate wrote {len(written)} revisions") - - applied = alembic("upgrade", "head") - if applied.returncode != 0: - sys.exit("upgrade failed:\n" + applied.stdout + applied.stderr) - - engine = build_engine() - created = asyncio.run(schema_of(engine)) - asyncio.run(engine.dispose()) - - if created != declared: - sys.exit(f"the baseline left {created}, while the models declare {declared}") - - indexes = sum(len(names) for names in declared.values()) - print(f"a baseline of {len(declared) - 1} tables and {indexes} indexes applies to an empty database") -""" - - -@dataclass(frozen=True) -class Result: - """What one check printed, and whether it passed.""" - - name: str - ok: bool - last_line: str - output: str - - -REPORTED_LINES = 40 - - -def _report(result: Result) -> str: - """One check's line, followed by the end of what it printed when it failed.""" - line = f" {'PASS' if result.ok else 'FAIL'} {result.name:12} {result.last_line}" - if result.ok: - return line - - printed = result.output.splitlines() - dropped = len(printed) - REPORTED_LINES - kept = [f"... {dropped} earlier lines"] if dropped > 0 else [] - kept += printed[-REPORTED_LINES:] - - return "\n".join([line, *(f" {printed_line}" for printed_line in kept)]) - - -def check(project: Path, python: Path) -> list[Result]: - """Import the app and every module, lint it, run whatever tests are left, migrate. - - Importing every module matters: a file no feature imports any more still ships, - and would fail only whenever someone reached for it. The migration check - autogenerates this project's baseline against the models it kept and applies it to - an empty database. - """ - backend = project / "backend" - environment = { - "PATH": "/usr/bin:/bin", - "PYTHONPATH": str(backend), - "ENVIRONMENT": "local", - "SECRET_KEY": "drill-secret-key-with-32-bytes-at-least", - "SESSION_BACKEND": "memory", - "RATE_LIMITER_BACKEND": "memory", - "HOME": str(Path.home()), - } - quiet = "import warnings, logging; warnings.simplefilter('ignore'); logging.disable(50); " - steps = [ - ("app imports", [str(python), "-c", quiet + "import src.interfaces.main"]), - ("every module imports", [str(python), "-c", quiet + _IMPORT_EVERY_MODULE]), - ("ruff", [str(python), "-m", "ruff", "check", "src", "tests"]), - ("mypy", [str(python), "-m", "mypy", "src", "scripts", "migrations", "tests", "--config-file", "pyproject.toml"]), - ("tests", [str(python), "-m", "pytest", "tests", "-q", "-p", "no:randomly"]), - ("migrations", [str(python), "-c", _MIGRATION_BASELINE]), - ] - results = [] - for name, command in steps: - completed = subprocess.run(command, cwd=backend, env=environment, capture_output=True, text=True) - output = (completed.stdout + completed.stderr).strip() - lines = output.splitlines() - results.append(Result(name, completed.returncode == 0, lines[-1] if lines else "", output)) - return results - - -def main() -> int: - parser = argparse.ArgumentParser(description=__doc__) - parser.add_argument("presets", nargs="*", metavar="PRESET", help=f"one or more of: {', '.join(PRESETS)}") - parser.add_argument("--keep", action="store_true", help="leave the scratch copies on disk") - arguments = parser.parse_args() - - unknown = [preset for preset in arguments.presets if preset not in PRESETS] - if unknown: - parser.error(f"unknown preset(s) {', '.join(unknown)}; choose from {', '.join(PRESETS)}") - - python = Path(sys.executable) - scratch = Path(tempfile.mkdtemp(prefix="removal-drill-")) - failures = 0 - try: - for preset in arguments.presets or PRESETS: - project = build(preset, scratch) - print(f"\n=== {preset}: {', '.join(sorted(_selected(preset))) or 'core only'}") - for result in check(project, python): - print(_report(result)) - failures += not result.ok - except Exception: - failures += 1 - raise - finally: - if arguments.keep or failures: - print(f"\nscratch copies left in {scratch}") - else: - shutil.rmtree(scratch, ignore_errors=True) - - return 1 if failures else 0 - - -if __name__ == "__main__": - raise SystemExit(main()) diff --git a/uv.lock b/uv.lock index 897ebc29..d60774a7 100644 --- a/uv.lock +++ b/uv.lock @@ -1,5 +1,5 @@ version = 1 -revision = 3 +revision = 5 requires-python = ">=3.11" resolution-markers = [ "python_full_version >= '3.15'", @@ -11,7 +11,6 @@ resolution-markers = [ [manifest] members = [ "fastapi-boilerplate", - "fastapi-boilerplate-cli", "fastapi-boilerplate-workspace", ] @@ -232,15 +231,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/fb/76/641ae371508676492379f16e2fa48f4e2c11741bd63c48be4b12a6b09cba/aiosignal-1.4.0-py3-none-any.whl", hash = "sha256:053243f8b92b990551949e63930a839ff0cf0b0ebbe0597b0f3fb19e1a0fe82e", size = 7490, upload-time = "2025-07-03T22:54:42.156Z" }, ] -[[package]] -name = "aiosqlite" -version = "0.22.1" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/4e/8a/64761f4005f17809769d23e518d915db74e6310474e733e3593cfc854ef1/aiosqlite-0.22.1.tar.gz", hash = "sha256:043e0bd78d32888c0a9ca90fc788b38796843360c855a7262a532813133a0650", size = 14821, upload-time = "2025-12-23T19:25:43.997Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/00/b7/e3bf5133d697a08128598c8d0abc5e16377b51465a33756de24fa7dee953/aiosqlite-0.22.1-py3-none-any.whl", hash = "sha256:21c002eb13823fad740196c5a2e9d8e62f6243bd9e7e4a1f87fb5e44ecb4fceb", size = 17405, upload-time = "2025-12-23T19:25:42.139Z" }, -] - [[package]] name = "aiostream" version = "0.7.1" @@ -884,19 +874,15 @@ version = "0.20.0" source = { editable = "backend" } dependencies = [ { name = "aiomcache" }, - { name = "aiosqlite" }, { name = "alembic" }, { name = "anyio" }, { name = "asyncpg" }, { name = "crudauth", extra = ["all"] }, { name = "cryptography" }, - { name = "faker" }, { name = "fastapi", extra = ["standard"] }, { name = "fastcrud" }, { name = "greenlet" }, - { name = "httpx" }, { name = "itsdangerous" }, - { name = "jinja2" }, { name = "pydantic" }, { name = "pydantic-settings" }, { name = "redis" }, @@ -911,6 +897,9 @@ dependencies = [ [package.optional-dependencies] dev = [ + { name = "faker" }, + { name = "httpx" }, + { name = "jinja2" }, { name = "mypy" }, { name = "pre-commit" }, { name = "pytest" }, @@ -925,19 +914,18 @@ dev = [ [package.metadata] requires-dist = [ { name = "aiomcache", specifier = ">=0.8.2" }, - { name = "aiosqlite", specifier = ">=0.21.0" }, { name = "alembic", specifier = ">=1.16.4" }, { name = "anyio", specifier = ">=4.15.1" }, { name = "asyncpg", specifier = ">=0.30.0" }, { name = "crudauth", extras = ["all"], specifier = ">=0.8.2,<0.9.0" }, { name = "cryptography", specifier = ">=42.0.0" }, - { name = "faker", specifier = ">=37.1.0" }, - { name = "fastapi", extras = ["standard"], specifier = ">=0.115.8" }, + { name = "faker", marker = "extra == 'dev'", specifier = ">=37.1.0" }, + { name = "fastapi", extras = ["standard"], specifier = ">=0.115.8,<0.140.7" }, { name = "fastcrud", specifier = ">=0.21.0" }, { name = "greenlet", specifier = ">=3.1.1" }, - { name = "httpx", specifier = ">=0.28.1" }, + { name = "httpx", marker = "extra == 'dev'", specifier = ">=0.28.1" }, { name = "itsdangerous", specifier = ">=2.2.0" }, - { name = "jinja2", specifier = ">=3.1.6" }, + { name = "jinja2", marker = "extra == 'dev'", specifier = ">=3.1.6" }, { name = "mypy", marker = "extra == 'dev'", specifier = ">=1.14.1" }, { name = "pre-commit", marker = "extra == 'dev'", specifier = ">=4.0.0" }, { name = "pydantic", specifier = ">=2.10.6" }, @@ -961,35 +949,27 @@ requires-dist = [ provides-extras = ["dev"] [[package]] -name = "fastapi-boilerplate-cli" -version = "0.1.0" -source = { editable = "cli" } -dependencies = [ - { name = "fastapi-boilerplate" }, - { name = "jinja2" }, - { name = "typer" }, -] +name = "fastapi-boilerplate-workspace" +version = "0" +source = { virtual = "." } -[package.optional-dependencies] +[package.dev-dependencies] dev = [ - { name = "pytest" }, + { name = "fastro" }, + { name = "packaging" }, { name = "pyyaml" }, + { name = "types-pyyaml" }, ] [package.metadata] -requires-dist = [ - { name = "fastapi-boilerplate", editable = "backend" }, - { name = "jinja2", specifier = ">=3.1" }, - { name = "pytest", marker = "extra == 'dev'", specifier = ">=8.3.5" }, - { name = "pyyaml", marker = "extra == 'dev'", specifier = ">=6.0.2" }, - { name = "typer", specifier = ">=0.12" }, -] -provides-extras = ["dev"] -[[package]] -name = "fastapi-boilerplate-workspace" -version = "0" -source = { virtual = "." } +[package.metadata.requires-dev] +dev = [ + { name = "fastro", git = "https://github.com/benavlabs/fastro?rev=640caae2d6f7c129ab0f03ee6a34088d4dede65f" }, + { name = "packaging", specifier = ">=24.0" }, + { name = "pyyaml", specifier = ">=6.0.2" }, + { name = "types-pyyaml", specifier = ">=6.0.12" }, +] [[package]] name = "fastapi-cli" @@ -1146,6 +1126,16 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/5f/1b/85fb4c1cb771845e5ede668ef28c090e021020d117e891fa1e599c9e32d1/fastcrud-0.21.0-py3-none-any.whl", hash = "sha256:94daa5ca7815a268b700ee31b36455a8248a1a0547f3fcef5969df0047aab338", size = 107150, upload-time = "2026-01-23T19:30:05.895Z" }, ] +[[package]] +name = "fastro" +version = "0.1.0.dev0" +source = { git = "https://github.com/benavlabs/fastro?rev=640caae2d6f7c129ab0f03ee6a34088d4dede65f#640caae2d6f7c129ab0f03ee6a34088d4dede65f" } +dependencies = [ + { name = "jinja2" }, + { name = "packaging" }, + { name = "typer" }, +] + [[package]] name = "filelock" version = "4.2.4" @@ -2788,6 +2778,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/3f/f9/2b3ff4e56e5fa7debfaf9eb135d0da96f3e9a1d5b27222223c7296336e5f/typer-0.25.1-py3-none-any.whl", hash = "sha256:75caa44ed46a03fb2dab8808753ffacdbfea88495e74c85a28c5eefcf5f39c89", size = 58409, upload-time = "2026-04-30T19:32:18.271Z" }, ] +[[package]] +name = "types-pyyaml" +version = "6.0.12.20261113" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/4d/8b/ba599d956693dbc98e170f32097128bdea0a17f9d42b0b490fa749c12b1a/types_pyyaml-6.0.12.20261113.tar.gz", hash = "sha256:0828be2580fd94151182364f4d0158e4de62fdbeeb8d4296f7f7d2b6c22bb640", size = 19017, upload-time = "2026-11-13T08:51:21.488Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/fd/2e/36fc0941a40ef066dbc8abac41bbbefb41389f547c779aef832aea6b873d/types_pyyaml-6.0.12.20261113-py3-none-any.whl", hash = "sha256:3600749e613748afdc4327f0b17c3296cf880cdbc7335f320007abd9dd815f67", size = 21321, upload-time = "2026-11-13T08:51:20.417Z" }, +] + [[package]] name = "typing-extensions" version = "4.15.0" diff --git a/zensical.toml b/zensical.toml index cff4283a..a170537c 100644 --- a/zensical.toml +++ b/zensical.toml @@ -1,6 +1,6 @@ [project] -site_name = "Fastro · FastAPI Boilerplate" -site_description = "Production-ready FastAPI starter with sessions, OAuth, SQLAdmin, Taskiq, Redis caching, and a plugin-aware CLI." +site_name = "FastAPI-boilerplate" +site_description = "Production-ready FastAPI starter with sessions, OAuth, SQLAdmin, Taskiq, Redis caching, and compose files written by fastro." site_url = "https://benavlabs.github.io/FastAPI-boilerplate" docs_dir = "docs" site_dir = "site" @@ -73,7 +73,7 @@ name = "FastAPI on PyPI" "Home" = "index.md" [[project.nav]] -"Fastro vs FastroAI" = "fastro-vs-fastroai.md" +"FastAPI-boilerplate vs FastroAI" = "fastro-vs-fastroai.md" [[project.nav]] "Getting Started" = [ @@ -135,16 +135,10 @@ name = "FastAPI on PyPI" { "Development" = "user-guide/development.md" }, { "Production" = "user-guide/production.md" }, { "Observability" = "user-guide/observability.md" }, + { "Generating and updating projects with fastro" = "user-guide/fastro.md" }, { "Testing" = "user-guide/testing.md" }, ] -[[project.nav]] -"CLI" = [ - { "Overview" = "cli/index.md" }, - { "Commands" = "cli/commands.md" }, - { "Plugins" = "cli/plugins.md" }, -] - [[project.nav]] "Changelog" = "changelog.md" @@ -187,3 +181,12 @@ admonition = {} [[project.markdown_extensions]] "md_in_html" = {} + +# ============================================================================== +# Plugins +# ============================================================================== + +[project.plugins.redirects.redirect_maps] +"cli/index.md" = "user-guide/fastro.md" +"cli/commands.md" = "user-guide/fastro.md" +"cli/plugins.md" = "user-guide/fastro.md"