From dd735d0630aa0cf32820f6c14a30ec31776aff27 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Mon, 26 Oct 2026 17:20:08 -0300 Subject: [PATCH 01/71] carry the deploy templates into blueprint/ on the generator context, with their tests --- .github/workflows/linting.yml | 4 +- .github/workflows/tests.yml | 3 + .../deploy/local/docker-compose.yml.j2 | 108 ++++++++++ .../templates/deploy/nginx/default.conf.j2 | 33 +++ .../deploy/nginx/docker-compose.yml.j2 | 148 +++++++++++++ .../deploy/prod/docker-compose.yml.j2 | 127 +++++++++++ blueprint/tests/test_deploy_templates.py | 197 ++++++++++++++++++ 7 files changed, 618 insertions(+), 2 deletions(-) create mode 100644 blueprint/templates/deploy/local/docker-compose.yml.j2 create mode 100644 blueprint/templates/deploy/nginx/default.conf.j2 create mode 100644 blueprint/templates/deploy/nginx/docker-compose.yml.j2 create mode 100644 blueprint/templates/deploy/prod/docker-compose.yml.j2 create mode 100644 blueprint/tests/test_deploy_templates.py diff --git a/.github/workflows/linting.yml b/.github/workflows/linting.yml index e12a747a..1291d93a 100644 --- a/.github/workflows/linting.yml +++ b/.github/workflows/linting.yml @@ -28,7 +28,7 @@ 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 cli/src cli/tests tools 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 cli/src cli/tests tools blueprint/tests diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 1c94f005..746fd114 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -34,6 +34,9 @@ jobs: - name: Pytest (cli) run: cd cli && uv run --no-sync pytest + - name: Pytest (blueprint) + run: uv run --no-sync pytest blueprint/tests + removal-drills: runs-on: ubuntu-latest strategy: diff --git a/blueprint/templates/deploy/local/docker-compose.yml.j2 b/blueprint/templates/deploy/local/docker-compose.yml.j2 new file mode 100644 index 00000000..c2e4e5b1 --- /dev/null +++ b/blueprint/templates/deploy/local/docker-compose.yml.j2 @@ -0,0 +1,108 @@ +# 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.slug }} + +services: + api: + build: + context: . + dockerfile: backend/Dockerfile + target: dev + env_file: + - ./backend/.env + environment: + POSTGRES_SERVER: postgres + CACHE_REDIS_HOST: redis + RATE_LIMITER_REDIS_HOST: redis + TASKIQ_REDIS_HOST: redis + volumes: + - ./backend/src:/app/src + - ./backend/tests:/app/tests + ports: + - "{{ params.api_port }}:8000" + depends_on: + postgres: + condition: service_healthy + redis: + condition: service_healthy +{% if "worker" in services %} + worker: + build: + context: . + dockerfile: backend/Dockerfile + target: dev + env_file: + - ./backend/.env + environment: + POSTGRES_SERVER: postgres + CACHE_REDIS_HOST: redis + RATE_LIMITER_REDIS_HOST: redis + TASKIQ_REDIS_HOST: redis + working_dir: /app/src + command: > + taskiq worker src.infrastructure.taskiq.worker:default_broker + --reload + volumes: + - ./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: . + dockerfile: backend/Dockerfile + target: dev + env_file: + - ./backend/.env + environment: + POSTGRES_SERVER: postgres + CACHE_REDIS_HOST: redis + RATE_LIMITER_REDIS_HOST: redis + TASKIQ_REDIS_HOST: redis + working_dir: /app/src + command: > + taskiq scheduler src.infrastructure.taskiq.scheduler:scheduler + volumes: + - ./backend/src:/app/src + depends_on: + postgres: + condition: service_healthy + redis: + condition: service_healthy +{% endif %} + postgres: + image: postgres:16-alpine + env_file: + - ./backend/.env + volumes: + - postgres-data:/var/lib/postgresql/data + ports: + - "127.0.0.1:5432:5432" + healthcheck: + test: ["CMD-SHELL", "pg_isready -U \"$${POSTGRES_USER:-postgres}\""] + interval: 5s + timeout: 3s + retries: 10 + + redis: + image: redis:7-alpine + volumes: + - redis-data:/data + ports: + - "127.0.0.1:6379:6379" + healthcheck: + test: ["CMD", "redis-cli", "ping"] + interval: 5s + timeout: 3s + retries: 10 + +volumes: + postgres-data: + redis-data: diff --git a/blueprint/templates/deploy/nginx/default.conf.j2 b/blueprint/templates/deploy/nginx/default.conf.j2 new file mode 100644 index 00000000..8873337b --- /dev/null +++ b/blueprint/templates/deploy/nginx/default.conf.j2 @@ -0,0 +1,33 @@ +# Generated by `fastro make deploy nginx`. +# Drop-in nginx vhost in front of the FastAPI app container. + +upstream {{ project.slug }}_api { + server api:8000; +} + +server { + listen 80; + server_name _; + + client_max_body_size 25M; + server_tokens off; + + # Forwarded headers. X-Forwarded-For and X-Forwarded-Proto are replaced with what + # nginx saw, dropping whatever the client sent. uvicorn trusts the headers only from + # the compose network (FORWARDED_ALLOW_IPS); crudauth counts hops from the right + # through TRUSTED_PROXY_HOPS. + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $remote_addr; + proxy_set_header X-Forwarded-Proto $scheme; + + # Long-running endpoints (exports, AI, etc.) want generous timeouts. + proxy_connect_timeout 60s; + proxy_send_timeout 300s; + proxy_read_timeout 300s; + + location / { + proxy_pass http://{{ project.slug }}_api; + proxy_redirect off; + } +} diff --git a/blueprint/templates/deploy/nginx/docker-compose.yml.j2 b/blueprint/templates/deploy/nginx/docker-compose.yml.j2 new file mode 100644 index 00000000..b8873080 --- /dev/null +++ b/blueprint/templates/deploy/nginx/docker-compose.yml.j2 @@ -0,0 +1,148 @@ +# 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.slug }} + +services: + # One-shot, and nothing waits on it: run it and only then restart the rest, so a + # migration that fails leaves the old code serving on the old schema. + # docker compose --profile migrate run --rm migrate + migrate: + build: + context: . + dockerfile: backend/Dockerfile + target: migrate + env_file: + - ./backend/.env + environment: + POSTGRES_SERVER: postgres + CONFIRM_PRODUCTION_MIGRATION: "yes" + profiles: ["migrate"] + depends_on: + postgres: + condition: service_healthy + restart: "no" + + api: + build: + context: . + dockerfile: backend/Dockerfile + target: prod + 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: "{{ params.internal_subnet }}" + WORKERS: "{{ params.workers }}" + expose: + - "8000" + depends_on: + postgres: + condition: service_healthy + redis: + condition: service_healthy + healthcheck: + test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health/ready').read()"] + interval: 15s + timeout: 5s + retries: 5 + start_period: 20s + restart: unless-stopped +{% if "worker" in services %} + worker: + build: + context: . + dockerfile: backend/Dockerfile + target: prod + env_file: + - ./backend/.env + environment: + POSTGRES_SERVER: postgres + CACHE_REDIS_HOST: redis + RATE_LIMITER_REDIS_HOST: redis + TASKIQ_REDIS_HOST: redis + working_dir: /app/src + command: taskiq worker src.infrastructure.taskiq.worker:default_broker --workers 2 + depends_on: + postgres: + condition: service_healthy + 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: . + dockerfile: backend/Dockerfile + target: prod + env_file: + - ./backend/.env + environment: + POSTGRES_SERVER: postgres + CACHE_REDIS_HOST: redis + RATE_LIMITER_REDIS_HOST: redis + TASKIQ_REDIS_HOST: redis + working_dir: /app/src + command: taskiq scheduler src.infrastructure.taskiq.scheduler:scheduler + depends_on: + postgres: + condition: service_healthy + redis: + condition: service_healthy + restart: unless-stopped +{% endif %} + nginx: + image: nginx:1.27-alpine + ports: + - "80:80" + volumes: + - ./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro + depends_on: + - api + restart: unless-stopped + + postgres: + image: postgres:16-alpine + env_file: + - ./backend/.env + volumes: + - postgres-data:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U \"$${POSTGRES_USER:-postgres}\""] + interval: 10s + timeout: 5s + retries: 10 + restart: unless-stopped + + redis: + image: redis:7-alpine + command: ["redis-server", "--appendonly", "yes"] + volumes: + - redis-data:/data + healthcheck: + test: ["CMD", "redis-cli", "ping"] + interval: 10s + timeout: 5s + retries: 10 + restart: unless-stopped + +volumes: + postgres-data: + redis-data: + +# The API trusts forwarded headers only from this range, so a client can neither +# claim another address nor say the request arrived over HTTPS. Change both this +# subnet and FORWARDED_ALLOW_IPS together if it clashes with a network you use. +networks: + default: + ipam: + config: + - subnet: "{{ params.internal_subnet }}" diff --git a/blueprint/templates/deploy/prod/docker-compose.yml.j2 b/blueprint/templates/deploy/prod/docker-compose.yml.j2 new file mode 100644 index 00000000..d792a5a8 --- /dev/null +++ b/blueprint/templates/deploy/prod/docker-compose.yml.j2 @@ -0,0 +1,127 @@ +# 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.slug }} + +services: + # One-shot, and nothing waits on it: run it and only then restart the rest, so a + # migration that fails leaves the old code serving on the old schema. + # docker compose --profile migrate run --rm migrate + migrate: + build: + context: . + dockerfile: backend/Dockerfile + target: migrate + env_file: + - ./backend/.env + environment: + POSTGRES_SERVER: postgres + CONFIRM_PRODUCTION_MIGRATION: "yes" + profiles: ["migrate"] + depends_on: + postgres: + condition: service_healthy + restart: "no" + + api: + build: + context: . + dockerfile: backend/Dockerfile + target: prod + env_file: + - ./backend/.env + environment: + POSTGRES_SERVER: postgres + CACHE_REDIS_HOST: redis + RATE_LIMITER_REDIS_HOST: redis + TASKIQ_REDIS_HOST: redis + WORKERS: "{{ params.workers }}" + ports: + - "{{ params.api_port }}:8000" + depends_on: + postgres: + condition: service_healthy + redis: + condition: service_healthy + healthcheck: + test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health/ready').read()"] + interval: 15s + timeout: 5s + retries: 5 + start_period: 20s + restart: unless-stopped +{% if "worker" in services %} + worker: + build: + context: . + dockerfile: backend/Dockerfile + target: prod + env_file: + - ./backend/.env + environment: + POSTGRES_SERVER: postgres + CACHE_REDIS_HOST: redis + RATE_LIMITER_REDIS_HOST: redis + TASKIQ_REDIS_HOST: redis + working_dir: /app/src + command: taskiq worker src.infrastructure.taskiq.worker:default_broker --workers 2 + depends_on: + postgres: + condition: service_healthy + 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: . + dockerfile: backend/Dockerfile + target: prod + env_file: + - ./backend/.env + environment: + POSTGRES_SERVER: postgres + CACHE_REDIS_HOST: redis + RATE_LIMITER_REDIS_HOST: redis + TASKIQ_REDIS_HOST: redis + working_dir: /app/src + command: taskiq scheduler src.infrastructure.taskiq.scheduler:scheduler + depends_on: + postgres: + condition: service_healthy + redis: + condition: service_healthy + restart: unless-stopped +{% endif %} + postgres: + image: postgres:16-alpine + env_file: + - ./backend/.env + volumes: + - postgres-data:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U \"$${POSTGRES_USER:-postgres}\""] + interval: 10s + timeout: 5s + retries: 10 + restart: unless-stopped + + redis: + image: redis:7-alpine + command: ["redis-server", "--appendonly", "yes"] + volumes: + - redis-data:/data + healthcheck: + test: ["CMD", "redis-cli", "ping"] + interval: 10s + timeout: 5s + retries: 10 + restart: unless-stopped + +volumes: + postgres-data: + redis-data: diff --git a/blueprint/tests/test_deploy_templates.py b/blueprint/tests/test_deploy_templates.py new file mode 100644 index 00000000..6c3ea73c --- /dev/null +++ b/blueprint/tests/test_deploy_templates.py @@ -0,0 +1,197 @@ +"""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. +""" + +from pathlib import Path +from typing import Any + +import pytest +import yaml +from jinja2 import Environment, FileSystemLoader, StrictUndefined + +TEMPLATES = Path(__file__).resolve().parents[1] / "templates" / "deploy" + +INTERNAL_SUBNET = "172.31.240.0/24" +"""The default of the ``internal_subnet`` param.""" + +TASKIQ_SERVICES = ("scheduler", "worker") +"""What the taskiq feature puts in ``services``.""" + + +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": "fastro", "version": "0.20.0"}, + "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, **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: Any) -> dict: + return yaml.safe_load(_render(f"{mode}/docker-compose.yml.j2", **overrides)) + + +@pytest.mark.parametrize("mode", ["prod", "nginx"]) +def test_the_api_reports_whether_it_is_ready(mode: str): + """Compose has no way to hold traffic back without one.""" + healthcheck = _compose(mode)["services"]["api"]["healthcheck"] + + assert "/health/ready" in " ".join(healthcheck["test"]) + + +@pytest.mark.parametrize("mode", ["prod", "nginx"]) +def test_the_worker_does_not_run_as_root(mode: str): + """The base stage has no USER, so building the worker from it would run it as root.""" + assert _compose(mode)["services"]["worker"]["build"]["target"] == "prod" + + +def test_behind_nginx_the_app_is_told_how_many_proxies_it_sits_behind(): + """Without this every client looks like the nginx container, and one attacker locks everyone out.""" + api = _compose("nginx")["services"]["api"]["environment"] + + assert api["TRUSTED_PROXY_HOPS"] == "1" + + +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"] == 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") + + +def test_the_local_compose_does_not_claim_a_proxy(): + """Nothing sits in front of it, so trusting forwarded headers would let a client forge its IP.""" + api = _compose("local")["services"]["api"] + + assert "TRUSTED_PROXY_HOPS" not in api.get("environment", {}) + + +def test_the_local_compose_publishes_its_databases_to_the_host_only(): + """Both database ports are bound to the loopback address.""" + services = _compose("local")["services"] + + assert services["postgres"]["ports"] == ["127.0.0.1:5432:5432"] + assert services["redis"]["ports"] == ["127.0.0.1:6379:6379"] + + +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") + + 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") + + assert f'- subnet: "{INTERNAL_SUBNET}"' in rendered + + +SCHEDULER_COMMAND = "taskiq scheduler src.infrastructure.taskiq.scheduler:scheduler" + + +@pytest.mark.parametrize("mode", ["local", "prod", "nginx"]) +def test_a_project_with_taskiq_gets_one_scheduler(mode: str): + """Every schedule fires once per scheduler, so the stack runs a single one.""" + scheduler = _compose(mode)["services"]["scheduler"] + + assert SCHEDULER_COMMAND in " ".join(scheduler["command"].split()) + assert "deploy" not in scheduler + + +@pytest.mark.parametrize("mode", ["local", "prod", "nginx"]) +def test_a_project_without_taskiq_gets_neither_worker_nor_scheduler(mode: str): + services = _compose(mode, features=("accounts",), services=())["services"] + + assert "worker" not in services + assert "scheduler" not in services + assert "api" in services + + +@pytest.mark.parametrize("mode", ["prod", "nginx"]) +def test_the_migration_runner_waits_to_be_asked(mode: str): + """A deploy runs it and only then restarts, so a failed migration leaves the old code serving.""" + migrate = _compose(mode)["services"]["migrate"] + + assert migrate["profiles"] == ["migrate"] + assert migrate["build"]["target"] == "migrate" + + +@pytest.mark.parametrize("mode", ["local", "prod", "nginx"]) +def test_nothing_depends_on_a_service_behind_a_profile(mode: str): + """Compose refuses the whole project when a service it starts depends on a profiled one.""" + services = _compose(mode)["services"] + behind_a_profile = {name for name, service in services.items() if service.get("profiles")} + + for name, service in services.items(): + assert behind_a_profile.isdisjoint(service.get("depends_on", {})), name + + +@pytest.mark.parametrize("mode", ["local", "prod", "nginx"]) +def test_the_database_takes_its_credentials_from_the_environment_file(mode: str): + """Compose interpolates ``${VAR}`` from the shell, never from ``env_file``, and + ``environment`` wins over it: a password set in ``backend/.env``, which is where every page + says to set it, was replaced in the container by the literal fallback. + """ + postgres = _compose(mode)["services"]["postgres"] + + assert postgres["env_file"] == ["./backend/.env"] + assert "${" not in yaml.safe_dump(postgres.get("environment", {})) + + +@pytest.mark.parametrize("mode", ["local", "prod", "nginx"]) +def test_the_database_probe_reads_the_user_inside_the_container(mode: str): + """A probe interpolated by compose asks for ``postgres`` whatever ``POSTGRES_USER`` says.""" + 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 From eb24ef2258f80ca9c2c362e45db250347f1deb43 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Mon, 26 Oct 2026 23:49:30 -0300 Subject: [PATCH 02/71] draw a secret key the project's own rules accept from a backend script --- backend/scripts/gen_secret.py | 93 ++++++++++++++++ backend/tests/unit/scripts/test_gen_secret.py | 101 ++++++++++++++++++ docs/user-guide/project-structure.md | 2 + 3 files changed, 196 insertions(+) create mode 100644 backend/scripts/gen_secret.py create mode 100644 backend/tests/unit/scripts/test_gen_secret.py 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/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/docs/user-guide/project-structure.md b/docs/user-guide/project-structure.md index cd6fcd2a..cf31af4b 100644 --- a/docs/user-guide/project-structure.md +++ b/docs/user-guide/project-structure.md @@ -34,6 +34,7 @@ backend/ │ ├── 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 @@ -208,6 +209,7 @@ scripts/ ├── 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 ├── 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 ``` From 77ce33ed1249291487dc7a47f6b0391c77ab239c Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Tue, 27 Oct 2026 13:24:13 -0300 Subject: [PATCH 03/71] audit the environment the way production would from a backend script --- backend/scripts/validate_env.py | 61 ++++++ .../tests/unit/scripts/test_validate_env.py | 176 ++++++++++++++++++ docs/user-guide/project-structure.md | 4 +- 3 files changed, 240 insertions(+), 1 deletion(-) create mode 100644 backend/scripts/validate_env.py create mode 100644 backend/tests/unit/scripts/test_validate_env.py 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/tests/unit/scripts/test_validate_env.py b/backend/tests/unit/scripts/test_validate_env.py new file mode 100644 index 00000000..13bf5638 --- /dev/null +++ b/backend/tests/unit/scripts/test_validate_env.py @@ -0,0 +1,176 @@ +"""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 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 _strong() -> dict[str, Any]: + return { + "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", + } + + +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.""" + _audited(monkeypatch, _settings(SECRET_KEY="insecure-secret-key-change-this")) + + 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.""" + _audited(monkeypatch, _settings(**(_strong() | {"CACHE_REDIS_PASSWORD": ""}))) + + 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.""" + _audited(monkeypatch, _settings(ENVIRONMENT=EnvironmentOption.DEVELOPMENT, EMAIL_BACKEND="console")) + + 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( + ("secret", "code"), + [("insecure-secret-key-change-this", 1), (secrets.token_hex(32), 0)], +) +def test_it_runs_as_a_module_and_exits_on_what_it_found(secret: str, code: int): + """``python -m scripts.validate_env`` is what the blueprint declares as a command.""" + 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/docs/user-guide/project-structure.md b/docs/user-guide/project-structure.md index cf31af4b..c0417621 100644 --- a/docs/user-guide/project-structure.md +++ b/docs/user-guide/project-structure.md @@ -39,7 +39,8 @@ backend/ │ ├── 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) ``` @@ -210,6 +211,7 @@ scripts/ ├── 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 ``` From 4778e01966423057ec0a10f7565103940774d254 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Tue, 27 Oct 2026 15:36:20 -0300 Subject: [PATCH 04/71] describe the blueprint, its dependencies, its presets and its verify sets --- backend/tests/unit/test_blueprint_catalog.py | 146 +++++++++++++++++++ blueprint.toml | 80 ++++++++++ 2 files changed, 226 insertions(+) create mode 100644 backend/tests/unit/test_blueprint_catalog.py create mode 100644 blueprint.toml diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py new file mode 100644 index 00000000..f2811f12 --- /dev/null +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -0,0 +1,146 @@ +"""The catalog describes this repository, and `tools/removal_drill.py` is what it describes. + +`blueprint.toml` is read by fastro, which isn't a dependency here yet, so nothing in this +file imports it: the rules it checks are transcribed from the catalog spec, and the facts it +checks against come from the drill, which is the repository's own account of its features. + +This file goes when `fastro blueprint lint` and `fastro blueprint verify` replace the drill. +""" + +import importlib.util +import re +import sys +import tomllib +from pathlib import Path +from typing import Any + +import pytest + +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 fastro is not a dependency yet.""" + +BLUEPRINT_NAME = re.compile(r"^[a-z][a-z0-9-]*$") + +NOT_YET_WRITTEN = {"fastro.toml"} +"""`fastro.toml` is declared in the catalog before it exists.""" + + +def _catalog() -> dict[str, Any]: + with CATALOG.open("rb") as handle: + return tomllib.load(handle) + + +def _drill(): + """The drill's manifest, loaded as a module: its dataclasses need it in ``sys.modules``.""" + spec = importlib.util.spec_from_file_location("removal_drill_manifest", REPO_ROOT / "tools" / "removal_drill.py") + 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 test_the_catalog_parses(): + assert _catalog()["blueprint"]["name"] == "fastro" + + +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 test_the_core_dependencies_are_the_ones_the_backend_declares(): + """The catalog carries the backend's lists until they are split per feature.""" + with BACKEND_PYPROJECT.open("rb") as handle: + backend = tomllib.load(handle) + + dependencies = _catalog()["blueprint"]["dependencies"] + + assert dependencies["runtime"] == backend["project"]["dependencies"] + assert dependencies["dev"] == backend["project"]["optional-dependencies"]["dev"] + + +@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(set(_catalog()["blueprint"]["blueprint_only"]) - NOT_YET_WRITTEN)) +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 test_the_things_projects_must_not_receive_are_listed(): + """The catalog, the drill, the docs and the tool's own tree belong to the blueprint only.""" + listed = set(_catalog()["blueprint"]["blueprint_only"]) + + assert {"blueprint/", "blueprint.toml", "fastro.toml", "docs/", "tools/", "cli/"} <= 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 + + +def test_the_verify_sets_are_the_drills_presets(): + """`everything` is implied by the spec, so the named sets are the other eight.""" + expected = {name: list(features) for name, features in _drill().PRESETS.items() if name != "everything"} + + assert _catalog()["verify"]["sets"] == expected + + +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.""" + requires = _drill().REQUIRES + + for name, features in _catalog()["presets"].items(): + for feature in features: + assert set(requires.get(feature, ())) <= set(features), f"{name} is missing what {feature} requires" + + +def test_the_presets_name_features_this_repository_has(): + known = set(_drill().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(_drill().FEATURES) diff --git a/blueprint.toml b/blueprint.toml new file mode 100644 index 00000000..670519e4 --- /dev/null +++ b/blueprint.toml @@ -0,0 +1,80 @@ +[blueprint] +name = "fastro" +version = "0.20.0" +schema = 1 +requires_fastro = ">=0.1.0.dev0,<0.2" +python_root = "backend" +import_root = "src" +blueprint_only = [ + ".github/", + "CODE_OF_CONDUCT.md", + "CONTRIBUTING.md", + "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_wiring.py", + "backend/tests/unit/test_image_contents.py", + "blueprint/", + "blueprint.toml", + "cli/", + "docs/", + "fastro.toml", + "tools/", + "uv.lock", + "zensical.toml", +] + +[blueprint.dependencies] +runtime = [ + "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", + "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", + "sqladmin>=0.28.0", + "sqlalchemy>=2.0.37", + "starlette>=1.3.1", + "taskiq>=0.11.20", + "taskiq-redis>=1.1.2", + "taskiq-aio-pika>=0.4.3", + "user-agents>=2.2.0", +] +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", + "taskiq[reload]>=0.11.20", + "pre-commit>=4.0.0", +] + +[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.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"] From 0fdec4ebb369ba62a87a78f2f5d3b6948b06fd81 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Tue, 27 Oct 2026 22:34:54 -0300 Subject: [PATCH 05/71] declare the points features contribute to, and what core contributes --- backend/tests/unit/test_blueprint_catalog.py | 91 ++++++++++++++++++ blueprint.toml | 98 ++++++++++++++++++++ 2 files changed, 189 insertions(+) diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index f2811f12..5ec84c4c 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -7,6 +7,7 @@ This file goes when `fastro blueprint lint` and `fastro blueprint verify` replace the drill. """ +import ast import importlib.util import re import sys @@ -144,3 +145,93 @@ def test_the_presets_name_features_this_repository_has(): def test_full_is_every_feature(): assert sorted(_catalog()["presets"]["full"]) == sorted(_drill().FEATURES) + + +ONE_OF_EACH = {"root_routers", "docs_guard", "email_sender", "cache_decorator"} +"""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 _import_line(entry: str) -> str: + """The import a wiring file under ``src/wiring/`` gets for this ref. + + Spec 2.8: a file under the import root imports relatively, so ``src.a.b:name`` is + written ``from ..a.b import name``, and an alias keeps its own statement. + """ + module, attribute, alias = _ref(entry) + imported = attribute if alias == attribute else f"{attribute} as {alias}" + + return f"from ..{module.removeprefix('src.')} import {imported}" + + +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 + + +def test_the_database_checks_belong_to_no_feature(): + """The drill wires them whatever is selected, so the catalog gives them to core.""" + core = _catalog()["core"]["contributes"]["critical_readiness"] + with_nothing_selected = _drill()._wiring_hooks(set()) + rendered = with_nothing_selected.split("CRITICAL_READINESS_CHECKS: tuple[ReadinessCheck, ...] = (")[1] + + assert [_ref(entry)[2] for entry in core] == [name.strip() for name in rendered.split(")")[0].split(",") if name.strip()] + + +@pytest.mark.parametrize("entry", _catalog()["core"]["contributes"]["critical_readiness"]) +def test_every_core_contribution_is_imported_the_way_the_drill_imports_it(entry: str): + """The names alone would accept a ref that kept the alias and changed the module.""" + assert _import_line(entry) in _drill()._wiring_hooks(set()) + + +@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 diff --git a/blueprint.toml b/blueprint.toml index 670519e4..1d2a4cdd 100644 --- a/blueprint.toml +++ b/blueprint.toml @@ -78,3 +78,101 @@ 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.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." From 339d7cc97e3cb59ab4882be93fd25af8451631c8 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Tue, 27 Oct 2026 22:40:35 -0300 Subject: [PATCH 06/71] declare the points features contribute to, and what core contributes --- backend/tests/unit/test_blueprint_catalog.py | 44 ++++++++++++++++---- 1 file changed, 37 insertions(+), 7 deletions(-) diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index 5ec84c4c..6aa2a26e 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -159,16 +159,31 @@ def _ref(text: str) -> tuple[str, str, str]: return module, attribute, alias or attribute -def _import_line(entry: str) -> str: - """The import a wiring file under ``src/wiring/`` gets for this ref. +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 - written ``from ..a.b import name``, and an alias keeps its own statement. + Spec 2.8: a file under the import root imports relatively, so ``src.a.b:name`` is read + from ``..a.b``. """ module, attribute, alias = _ref(entry) - imported = attribute if alias == attribute else f"{attribute} as {alias}" - return f"from ..{module.removeprefix('src.')} import {imported}" + return ".." + module.removeprefix("src."), 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: the drill merges names from one module + into a single statement and wraps long ones 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: @@ -226,7 +241,7 @@ def test_the_database_checks_belong_to_no_feature(): @pytest.mark.parametrize("entry", _catalog()["core"]["contributes"]["critical_readiness"]) def test_every_core_contribution_is_imported_the_way_the_drill_imports_it(entry: str): """The names alone would accept a ref that kept the alias and changed the module.""" - assert _import_line(entry) in _drill()._wiring_hooks(set()) + assert _binding(entry) in _bindings(_drill()._wiring_hooks(set())) @pytest.mark.parametrize("entry", _catalog()["core"]["contributes"]["critical_readiness"]) @@ -235,3 +250,18 @@ def test_every_core_contribution_names_something_that_exists(entry: str): module, attribute, _ = _ref(entry) assert _defines(module, attribute), entry + + +def test_the_import_reader_sees_a_name_the_drill_merges(): + """Two names from one module become one statement, whose second name no line contains.""" + bindings = _bindings(_drill()._wiring_hooks({"accounts"})) + + 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_the_drill_wraps(): + """The composition import is written over several lines, so no single line holds it.""" + bindings = _bindings(_drill()._wiring_hooks(set())) + + assert ("..infrastructure.composition", "ReadinessCheck", "ReadinessCheck") in bindings From 90355bee0b8d307bc408d644651781c8143f7cee Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Tue, 27 Oct 2026 23:26:31 -0300 Subject: [PATCH 07/71] check the catalog against the rules spec rev 1.7 tightens --- backend/tests/unit/test_blueprint_catalog.py | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index 6aa2a26e..e4182bc9 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -27,6 +27,9 @@ 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.""" + NOT_YET_WRITTEN = {"fastro.toml"} """`fastro.toml` is declared in the catalog before it exists.""" @@ -119,10 +122,18 @@ def test_the_docs_reading_tests_stay_in_the_blueprint(): def test_the_verify_sets_are_the_drills_presets(): - """`everything` is implied by the spec, so the named sets are the other eight.""" + """`everything` is implied by the spec, and declaring it is an error, so the sets are the other eight.""" expected = {name: list(features) for name, features in _drill().PRESETS.items() if name != "everything"} + sets = _catalog()["verify"]["sets"] + + assert "everything" not in sets + assert sets == expected + - assert _catalog()["verify"]["sets"] == expected +@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(): From 80839e9da6ce41767b4cd191292f12ce8dce94b7 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Tue, 27 Oct 2026 23:26:37 -0300 Subject: [PATCH 08/71] draw the test's key inside the test, not into its id --- backend/tests/unit/scripts/test_validate_env.py | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/backend/tests/unit/scripts/test_validate_env.py b/backend/tests/unit/scripts/test_validate_env.py index 13bf5638..821803a5 100644 --- a/backend/tests/unit/scripts/test_validate_env.py +++ b/backend/tests/unit/scripts/test_validate_env.py @@ -145,12 +145,14 @@ def _run(environment: dict[str, str]) -> subprocess.CompletedProcess[str]: ) -@pytest.mark.parametrize( - ("secret", "code"), - [("insecure-secret-key-change-this", 1), (secrets.token_hex(32), 0)], -) -def test_it_runs_as_a_module_and_exits_on_what_it_found(secret: str, code: int): - """``python -m scripts.validate_env`` is what the blueprint declares as a command.""" +@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", From 4a062654f7bb151a34f53e4456b91df92c898154 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Tue, 27 Oct 2026 23:26:40 -0300 Subject: [PATCH 09/71] run the blueprint's tests when pytest runs from the workspace root --- pyproject.toml | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/pyproject.toml b/pyproject.toml index 7aa03036..542c7d72 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -10,6 +10,11 @@ # uv sync --all-packages --all-extras # one venv shared by all members # uv run bp ... # runs the CLI from cli/, 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 +# +# Each package'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, and `cli` +# has to be importable. So the root's testpaths name the blueprint's tests and nothing else. # # To install `bp` machine-wide so it works outside this repo: # @@ -24,6 +29,9 @@ requires-python = ">=3.11" [tool.uv.workspace] members = ["backend", "cli"] +[tool.pytest.ini_options] +testpaths = ["blueprint/tests"] + [tool.ruff] line-length = 128 From 8bd2c1e9b4a5a9f13a37b2035728ee0568db878b Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Wed, 28 Oct 2026 12:43:27 -0300 Subject: [PATCH 10/71] declare the nine features, what they need and what they own --- backend/tests/unit/test_blueprint_catalog.py | 138 +++++++++++++++++ blueprint.toml | 155 +++++++++++++++++++ 2 files changed, 293 insertions(+) diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index e4182bc9..ea96f254 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -9,6 +9,7 @@ import ast import importlib.util +import itertools import re import sys import tomllib @@ -276,3 +277,140 @@ def test_the_import_reader_sees_a_name_the_drill_wraps(): bindings = _bindings(_drill()._wiring_hooks(set())) assert ("..infrastructure.composition", "ReadinessCheck", "ReadinessCheck") in bindings + + +GENERATED_BY_WIRING = "backend/src/wiring/admin.py" +"""The drill deletes it with the admin feature; the catalog's `[[wiring]]` entry omits it instead.""" + + +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 condition in chosen + } + + +def _kept_by_the_drill(manifest: Any, chosen: set[str]) -> set[str]: + """What `build` leaves on disk: a combination path needs both of its features.""" + kept: set[str] = set() + for name, feature in manifest.FEATURES.items(): + if name not in chosen: + continue + + kept.update(path for path in feature.paths if path != GENERATED_BY_WIRING) + for partner, paths in feature.combination_paths.items(): + if partner in chosen: + kept.update(paths) + + return kept + + +def _selections(manifest: Any) -> list[set[str]]: + """Every selection a project could carry: each subset of the features, closed under requires.""" + closed = [] + for size in range(len(manifest.FEATURES) + 1): + for combination in itertools.combinations(manifest.FEATURES, size): + selection = manifest._selected_from(combination) + if selection not in closed: + closed.append(selection) + + return closed + + +def test_the_features_are_the_ones_the_drill_knows(): + """In the drill's order: spec 6.2 hands templates the selection in catalog order.""" + assert list(_catalog()["features"]) == list(_drill().FEATURES) + + +@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"} + + +def test_every_feature_requires_what_the_drill_says_it_requires(): + """A requires that drifts would generate a project whose imports have nothing to bind.""" + requires = _drill().REQUIRES + + for name, feature in _catalog()["features"].items(): + assert list(feature.get("requires", ())) == list(requires.get(name, ())) + + +@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 _drill().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 _drill().FEATURES["admin"].paths + assert GENERATED_BY_WIRING not in declared + + +def test_every_selection_keeps_the_files_the_drill_keeps(): + """The catalog gives a shared file to the feature whose subtree holds it, and the drill to both. + + `src/modules/user/admin.py` is admin's work inside accounts' package, and the drill lists it + under both. One declaration owns it here, so what's compared is the file surviving a + selection, not which feature spoke for it. + """ + manifest = _drill() + features = _catalog()["features"] + + for chosen in _selections(manifest): + assert _kept_by_the_catalog(features, chosen) == _kept_by_the_drill(manifest, chosen), sorted(chosen) diff --git a/blueprint.toml b/blueprint.toml index 1d2a4cdd..be8ff39b 100644 --- a/blueprint.toml +++ b/blueprint.toml @@ -176,3 +176,158 @@ 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" +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.when]] +if = "admin" +paths = [ + "backend/src/modules/user/admin.py", + "backend/tests/unit/modules/user/test_admin.py", +] + +[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.when]] +if = "admin" +paths = [ + "backend/src/modules/role/admin.py", + "backend/tests/unit/modules/role/test_admin.py", +] + +[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.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.when]] +if = "admin" +paths = [ + "backend/src/modules/tier/admin.py", + "backend/tests/unit/modules/tier/test_admin.py", +] + +[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.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.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", +] + +[[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"] +paths = [ + "backend/src/interfaces/admin/", + "backend/tests/unit/interfaces/admin/", +] + +[features.cache] +summary = "@cache over Redis or Memcached" +group = "Operations" +paths = [ + "backend/src/infrastructure/cache/", + "backend/tests/unit/infrastructure/cache/", +] + +[features.taskiq] +summary = "Background tasks on Redis or RabbitMQ" +group = "Operations" +paths = [ + "backend/src/infrastructure/taskiq/", + "backend/tests/unit/infrastructure/taskiq/", +] + +[[features.taskiq.when]] +if = "accounts" +paths = [ + "backend/src/infrastructure/taskiq/email.py", + "backend/tests/unit/infrastructure/taskiq/test_email.py", +] + From 10327c39916a6d5b621f2055fbb7ce30e0c72e8d Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Wed, 28 Oct 2026 14:34:05 -0300 Subject: [PATCH 11/71] declare what each feature contributes, in what order, and what it can be asked --- backend/.env.example | 2 + backend/tests/unit/test_blueprint_catalog.py | 401 +++++++++++++++++++ blueprint.toml | 100 +++++ 3 files changed, 503 insertions(+) diff --git a/backend/.env.example b/backend/.env.example index 03b82981..791e7fe2 100644 --- a/backend/.env.example +++ b/backend/.env.example @@ -42,6 +42,7 @@ POSTGRES_POOL_RECYCLE=-1 # =================================== CACHE_ENABLED=true # Options: memcached, redis +# @fastro option=cache.backend CACHE_BACKEND=redis # Client-side cache settings @@ -132,6 +133,7 @@ KEY_USAGE_RETENTION_DAYS=90 # Taskiq Configuration # =================================== # 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 diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index ea96f254..29c0cb28 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -414,3 +414,404 @@ def test_every_selection_keeps_the_files_the_drill_keeps(): for chosen in _selections(manifest): assert _kept_by_the_catalog(features, chosen) == _kept_by_the_drill(manifest, chosen), sorted(chosen) + + +POINTS: dict[str, tuple[str, str]] = { + "routers": ("_wiring_app", "ROUTER_MOUNTS"), + "root_routers": ("_wiring_app", "ROOT_ROUTERS"), + "api_throttle": ("_wiring_app", "API_THROTTLE"), + "lifecycles": ("_wiring_app", "LIFECYCLES"), + "installers": ("_wiring_app", "INSTALLERS"), + "docs_guard": ("_wiring_app", "DOCS_GUARD"), + "settings": ("_wiring_settings", "Settings"), + "permission_sources": ("_wiring_hooks", "PERMISSION_SOURCES"), + "rate_limit_resolvers": ("_wiring_hooks", "RATE_LIMIT_RESOLVERS"), + "tier_delete_guards": ("_wiring_hooks", "TIER_DELETE_GUARDS"), + "tier_delete_releases": ("_wiring_hooks", "TIER_DELETE_RELEASES"), + "critical_readiness": ("_wiring_hooks", "CRITICAL_READINESS_CHECKS"), + "informational_readiness": ("_wiring_hooks", "INFORMATIONAL_READINESS_CHECKS"), + "user_model": ("_wiring_models", "UserModelExtensions"), + "user_schema": ("_wiring_models", "UserSchemaExtensions"), + "admin_views": ("_wiring_admin", "ADMIN_VIEWS"), + "email_sender": ("_wiring_email", "EMAIL_SENDER"), + "cache_decorator": ("_wiring_cache", "cached"), + "task_modules": ("_wiring_tasks", "TASK_MODULES"), + "table_modules": ("_wiring_tables", "TABLE_MODULES"), + "extra_transports": ("_wiring_transports", "EXTRA_TRANSPORTS"), + "seeders": ("_seeders", "SEEDERS"), + "test_plugins": ("_tests_wiring", "PYTEST_PLUGINS"), +} +"""Where the drill writes each point: the generator, and the name it assigns or defines.""" + +FALLBACKS = { + "root_routers": "()", + "docs_guard": "None", + "email_sender": "HandingOverSender(build_sender())", + "user_schema": "BaseModel", +} +"""What a point renders as when nothing contributes to it, which is no contribution at all.""" + +APPENDED = {"settings": "CoreSettings"} +"""A base the slot always adds last, after everything contributed.""" + + +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 _named(entry: dict[str, Any]) -> Any: + """The local name a contribution binds, or the literal it contributes.""" + if "value" in entry: + return entry["value"] + + return _ref(entry["ref"])[2] + + +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 _leading_name(element: ast.AST) -> Any: + """What a rendered item is built around: ``RouterMount(users_router, …)`` is ``users_router``.""" + if isinstance(element, ast.Constant): + return element.value + if isinstance(element, ast.Name): + return element.id + if isinstance(element, ast.Call): + return _leading_name(element.args[0]) if element.args else _leading_name(element.func) + + raise AssertionError(ast.unparse(element)) + + +def _rendered(source: str, point: str, name: str) -> list[Any]: + """The names the drill rendered into this point, in the order it wrote them.""" + if point == "cache_decorator": + bound = [module for module, _, alias in _bindings(source) if alias == name] + + return [] if bound == ["..infrastructure.uncached"] else [name] + + defined = _defined(source, name) + assert defined is not None, name + + if isinstance(defined, ast.ClassDef): + bases = [base.id for base in defined.bases if isinstance(base, ast.Name)] + if point in APPENDED: + assert bases[-1] == APPENDED[point], bases + bases = bases[:-1] + + return [] if bases == [FALLBACKS.get(point)] else bases + + if isinstance(defined, ast.Tuple | ast.List): + return [_leading_name(element) for element in defined.elts] + + return [] if ast.unparse(defined) == FALLBACKS[point] else [_leading_name(defined)] + + +def _written_for(manifest: Any, generator: str, chosen: set[str]) -> str: + written: str = getattr(manifest, generator)(chosen) + + return written + + +def _constant(node: ast.expr) -> Any: + """The value of a rendered literal, such as a mount's prefix or its throttle flag.""" + assert isinstance(node, ast.Constant), ast.unparse(node) + + return node.value + + +def test_every_declared_point_is_one_the_drill_writes_somewhere(): + """A point missing from this table would skip the comparison below without saying so.""" + assert set(POINTS) == set(_catalog()["points"]) + + +@pytest.mark.parametrize("point", sorted(POINTS)) +def test_every_point_is_written_by_a_generator_the_drill_has(point: str): + generator, _ = POINTS[point] + + assert hasattr(_drill(), generator) + + +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(_drill()): + for point in single: + assert len(_contributed(catalog, point, chosen)) <= 1, (point, sorted(chosen)) + + +@pytest.mark.parametrize("point", sorted(POINTS)) +def test_the_catalog_says_what_the_drill_renders(point: str): + """For every selection a project could carry, what reaches a point is what the drill wrote. + + All 164 of them, not the verify sets: a set builds and tests a project, so the sets are + few, and a generator is a function of the selection alone, so it costs nothing to ask it + about combinations no set builds. + """ + catalog = _catalog() + manifest = _drill() + generator, name = POINTS[point] + + for chosen in _selections(manifest): + expected = [_named(entry) for entry in _contributed(catalog, point, chosen)] + if generator == "_wiring_admin" and "admin" not in chosen: + assert expected == [], sorted(chosen) + continue + + assert _rendered(_written_for(manifest, generator, chosen), point, name) == expected, sorted(chosen) + + +def test_every_mounted_router_is_mounted_where_the_drill_mounts_it(): + """The prefix and the throttle are the catalog's to carry now, so they are compared too.""" + catalog = _catalog() + manifest = _drill() + + for chosen in _selections(manifest): + declared = [(_named(entry), entry["prefix"], entry["throttled"]) for entry in _contributed(catalog, "routers", chosen)] + mounts = _defined(_written_for(manifest, "_wiring_app", chosen), "ROUTER_MOUNTS") + assert isinstance(mounts, ast.Tuple) + + rendered = [ + ( + _leading_name(element.args[0]), + _constant(element.args[1]), + next(_constant(word.value) for word in element.keywords if word.arg == "throttled"), + ) + for element in mounts.elts + if isinstance(element, ast.Call) + ] + + assert rendered == declared, sorted(chosen) + + +def test_every_contribution_is_imported_the_way_the_drill_imports_it(): + """A ref that kept the local name and changed the module would render the same line.""" + catalog = _catalog() + manifest = _drill() + everything = set(manifest.FEATURES) + + for point, (generator, _) in POINTS.items(): + source = _written_for(manifest, generator, everything) + bound = _bindings(source) + for entry in _contributed(catalog, point, everything): + if "value" in entry: + continue + + module, attribute, alias = _binding(entry["ref"]) + assert (module.replace("..scripts.", "scripts."), attribute, alias) in bound, (point, entry) + + +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(_written_for(_drill(), "_wiring_transports", everything), "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"] + ) + + +@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}=") diff --git a/blueprint.toml b/blueprint.toml index be8ff39b..83920d42 100644 --- a/blueprint.toml +++ b/blueprint.toml @@ -198,12 +198,34 @@ paths = [ "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" }] + [[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" @@ -215,12 +237,26 @@ paths = [ "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" @@ -232,6 +268,10 @@ paths = [ "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" @@ -244,12 +284,24 @@ paths = [ "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" }] + [[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" @@ -261,6 +313,15 @@ paths = [ "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.api_keys] summary = "API keys: create, revoke, meter" group = "Accounts" @@ -274,6 +335,14 @@ paths = [ "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.when]] if = "ratelimit" paths = [ @@ -292,6 +361,7 @@ 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" @@ -308,6 +378,10 @@ paths = [ "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" @@ -316,18 +390,44 @@ paths = [ "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.options.backend] +choices = ["redis", "memcached"] +default = "redis" +env = { CACHE_BACKEND = "{value}" } +services = { memcached = ["memcached"] } + [features.taskiq] summary = "Background tasks on Redis or RabbitMQ" group = "Operations" +services = ["worker", "scheduler"] 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 }] From e1810766f7bcb29b7833c17a524054d0e4c4d595 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Wed, 28 Oct 2026 15:04:36 -0300 Subject: [PATCH 12/71] declare the twelve files the composition root is generated into --- backend/tests/unit/test_blueprint_catalog.py | 353 +++++++++++++++++-- blueprint.toml | 228 ++++++++++++ 2 files changed, 561 insertions(+), 20 deletions(-) diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index 29c0cb28..1554e94e 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -8,7 +8,10 @@ """ import ast +import functools +import importlib import importlib.util +import inspect import itertools import re import sys @@ -35,11 +38,13 @@ """`fastro.toml` is declared in the catalog before it exists.""" +@functools.cache def _catalog() -> dict[str, Any]: with CATALOG.open("rb") as handle: return tomllib.load(handle) +@functools.cache def _drill(): """The drill's manifest, loaded as a module: its dataclasses need it in ``sys.modules``.""" spec = importlib.util.spec_from_file_location("removal_drill_manifest", REPO_ROOT / "tools" / "removal_drill.py") @@ -175,11 +180,13 @@ 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``. + 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.removeprefix("src."), attribute, alias + return module, attribute, alias def _bindings(source: str) -> set[tuple[str, str, str]]: @@ -443,16 +450,30 @@ def test_every_selection_keeps_the_files_the_drill_keeps(): } """Where the drill writes each point: the generator, and the name it assigns or defines.""" -FALLBACKS = { - "root_routers": "()", - "docs_guard": "None", - "email_sender": "HandingOverSender(build_sender())", - "user_schema": "BaseModel", -} -"""What a point renders as when nothing contributes to it, which is no contribution at all.""" -APPENDED = {"settings": "CoreSettings"} -"""A base the slot always adds last, after everything contributed.""" +def _slot_of(point: str) -> dict[str, Any]: + """The one slot that collects this point, which `[[wiring]]` declares exactly once.""" + slots: list[dict[str, Any]] = [ + slot for entry in _catalog()["wiring"] for slot in entry["slots"] if slot.get("point") == point + ] + assert len(slots) == 1, point + + return slots[0] + + +def _fallback_of(point: str) -> str | None: + """How a point renders with nothing contributed: an expression, or a ref's local name.""" + slot = _slot_of(point) + fallback = slot.get("fallback") + if fallback is None: + return None + + return _ref(fallback)[2] if slot["kind"] in {"class", "reexport"} else fallback + + +def _appended_to(point: str) -> list[str]: + """The bases a `class` slot always adds last, by the name they are bound under.""" + return [_ref(ref)[2] for ref in _slot_of(point).get("append", ())] def _true(condition: str, chosen: set[str]) -> bool: @@ -571,26 +592,28 @@ def _leading_name(element: ast.AST) -> Any: def _rendered(source: str, point: str, name: str) -> list[Any]: """The names the drill rendered into this point, in the order it wrote them.""" - if point == "cache_decorator": + if _slot_of(point)["kind"] == "reexport": + fallback, _, _ = _binding(_slot_of(point)["fallback"]) bound = [module for module, _, alias in _bindings(source) if alias == name] - return [] if bound == ["..infrastructure.uncached"] else [name] + return [] if bound == [fallback] else [name] defined = _defined(source, name) assert defined is not None, name if isinstance(defined, ast.ClassDef): bases = [base.id for base in defined.bases if isinstance(base, ast.Name)] - if point in APPENDED: - assert bases[-1] == APPENDED[point], bases - bases = bases[:-1] + appended = _appended_to(point) + if appended: + assert bases[-len(appended) :] == appended, bases + bases = bases[: -len(appended)] - return [] if bases == [FALLBACKS.get(point)] else bases + return [] if bases == [_fallback_of(point)] else bases if isinstance(defined, ast.Tuple | ast.List): return [_leading_name(element) for element in defined.elts] - return [] if ast.unparse(defined) == FALLBACKS[point] else [_leading_name(defined)] + return [] if ast.unparse(defined) == _fallback_of(point) else [_leading_name(defined)] def _written_for(manifest: Any, generator: str, chosen: set[str]) -> str: @@ -711,8 +734,7 @@ def test_every_contribution_is_imported_the_way_the_drill_imports_it(): if "value" in entry: continue - module, attribute, alias = _binding(entry["ref"]) - assert (module.replace("..scripts.", "scripts."), attribute, alias) in bound, (point, entry) + assert _binding(entry["ref"]) in bound, (point, entry) def test_a_transport_that_is_constructed_says_so(): @@ -815,3 +837,294 @@ def test_every_option_marks_the_line_it_rewrites(feature: str, option: str): 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 _written_by_build(manifest: Any) -> list[str]: + """The files `build` writes, read out of its source rather than listed again here.""" + source = inspect.getsource(manifest.build) + + return re.findall(r'\(project / "([^"]+)"\)\.write_text', source) + + +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 + + +def test_the_wiring_entries_are_the_files_the_drill_writes(): + """One entry per generated file, both ways. The entries' order carries nothing, so it is free.""" + written = _written_by_build(_drill()) + + assert sorted(entry["path"] for entry in _entries()) == sorted(written) + assert len(written) == 12 + + +@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", [entry["path"] for entry in _entries()]) +def test_every_wiring_file_says_what_it_is_for(path: str): + """The entry's `doc` is the file's own docstring, minus the line naming what generated it.""" + entry = next(entry for entry in _entries() if entry["path"] == path) + docstring = ast.get_docstring(ast.parse(_committed(path))) + + assert docstring is not None + declared = entry["doc"].splitlines() + assert declared[0] == docstring.splitlines()[0] + assert " ".join(" ".join(declared[1:]).split()) in " ".join(docstring.split()) + + +@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")) + build = inspect.getsource(_drill().build) + + assert admin["if"] == "admin" + assert 'if "admin" in chosen:' in build + assert [entry.get("if") for entry in _entries()].count(None) == 11 + + +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 + + +@pytest.mark.parametrize("path", [entry["path"] for entry in _entries()]) +def test_the_catalog_accounts_for_what_the_file_imports_for_every_selection(path: str): + """The fallbacks, where the committed files cannot reach: nothing falls back with all nine. + + `fallback_imports`, the pydantic base and the uncached decorator are only written into a + project that left the feature out, so only a smaller selection compares them. + """ + catalog = _catalog() + manifest = _drill() + entry = next(entry for entry in _entries() if entry["path"] == path) + generator = next( + drill_generator + for point, (drill_generator, _) in POINTS.items() + if any(slot.get("point") == point for slot in entry["slots"]) + ) + + for chosen in _selections(manifest): + if generator == "_wiring_admin" and "admin" not in chosen: + continue + + written = _bindings(_written_for(manifest, generator, chosen)) + assert _declared_bindings(catalog, entry, chosen) == written, sorted(chosen) + + +LINE_LENGTH = 128 +"""The project's ruff line length, which spec 2.8 wraps a generated import at.""" + + +@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)) diff --git a/blueprint.toml b/blueprint.toml index 83920d42..97226792 100644 --- a/blueprint.toml +++ b/blueprint.toml @@ -431,3 +431,231 @@ paths = [ contributes.email_sender = ["src.infrastructure.taskiq.email:queued_sender"] contributes.task_modules = [{ value = "src.infrastructure.taskiq.email", order = 10 }] + +[wiring_defaults] +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/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 From c4dcb84df7a091fe9c6299f04709e97d0674c6b7 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Wed, 28 Oct 2026 15:04:40 -0300 Subject: [PATCH 13/71] lay the generated wiring out the way the spec renders it --- backend/src/wiring/hooks.py | 8 +------- backend/src/wiring/tasks.py | 5 ++++- 2 files changed, 5 insertions(+), 8 deletions(-) diff --git a/backend/src/wiring/hooks.py b/backend/src/wiring/hooks.py index 6d542e41..b7b5f66f 100644 --- a/backend/src/wiring/hooks.py +++ b/backend/src/wiring/hooks.py @@ -6,13 +6,7 @@ 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/tasks.py b/backend/src/wiring/tasks.py index 5e529acd..61bb4ba1 100644 --- a/backend/src/wiring/tasks.py +++ b/backend/src/wiring/tasks.py @@ -5,4 +5,7 @@ declaring one belongs in this list. """ -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", +) From b3a00dc764b938230c4a04af2220142f29a3f96e Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Wed, 28 Oct 2026 16:29:02 -0300 Subject: [PATCH 14/71] declare the deploy generator, the commands and the blueprint's own project file --- backend/tests/unit/test_blueprint_catalog.py | 166 ++++++++++++++++++- blueprint.toml | 36 ++++ fastro.toml | 10 ++ 3 files changed, 208 insertions(+), 4 deletions(-) create mode 100644 fastro.toml diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index 1554e94e..910e13e9 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -12,7 +12,9 @@ import importlib import importlib.util import inspect +import ipaddress import itertools +import keyword import re import sys import tomllib @@ -34,9 +36,6 @@ 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.""" -NOT_YET_WRITTEN = {"fastro.toml"} -"""`fastro.toml` is declared in the catalog before it exists.""" - @functools.cache def _catalog() -> dict[str, Any]: @@ -105,7 +104,7 @@ def test_every_blueprint_only_path_is_written_the_way_the_spec_reads_them(entry: assert entry.endswith("/") == (REPO_ROOT / entry).is_dir() -@pytest.mark.parametrize("entry", sorted(set(_catalog()["blueprint"]["blueprint_only"]) - NOT_YET_WRITTEN)) +@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() @@ -1128,3 +1127,162 @@ def test_a_collection_of_more_than_one_is_written_one_entry_to_a_line(path: str, 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-]*$") + +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()) + + +def test_the_deploy_modes_are_the_ones_this_repo_can_generate(): + """A mode with no template tree would be offered and then fail; a tree with no mode is dead.""" + templates = REPO_ROOT / _catalog()["generators"]["deploy"]["templates"] + offered = re.findall(r"^ (\w+) = \"\w+\"$", (REPO_ROOT / "cli/src/cli/commands/deploy.py").read_text(), re.M) + + assert sorted(child.name for child in templates.iterdir() if child.is_dir()) == sorted(offered) + + +@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"] + + assert str(ipaddress.ip_network(declared["default"], strict=True)) == declared["default"] + assert 0 <= declared["max_prefix"] <= 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 test_the_defaults_are_what_this_repos_own_generator_already_uses(): + """`fastro make deploy` has to write what `bp deploy generate` writes, or the first run changes.""" + params = _catalog()["generators"]["deploy"]["params"] + source = (REPO_ROOT / "cli/src/cli/commands/deploy.py").read_text() + subnet = (REPO_ROOT / "cli/src/cli/features/_builtins/deploy/feature.py").read_text() + + assert f'typer.Option({params["api_port"]["default"]}, "--api-port"' in source + assert f'typer.Option({params["workers"]["default"]}, "--workers"' in source + assert f'DEFAULT_INTERNAL_SUBNET = "{params["internal_subnet"]["default"]}"' in subnet + + +@pytest.mark.parametrize("words", sorted(_catalog()["commands"])) +def test_every_command_is_spelled_the_way_the_spec_reads_it(words: str): + """Spec 2.9: the words become the command path, one space apart.""" + command = _catalog()["commands"][words] + + 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", sorted(_catalog()["commands"])) +def test_every_command_runs_a_module_this_repo_can_run(words: str): + """It is run as `python -m `, which needs the entry point that makes that work.""" + module = _catalog()["commands"][words]["module"] + path = REPO_ROOT / _catalog()["blueprint"]["python_root"] / Path(*module.split(".")).with_suffix(".py") + + assert path.is_file() + assert '__name__ == "__main__"' in path.read_text() + + +@pytest.mark.parametrize("words", sorted(_catalog()["commands"])) +def test_every_command_runs_a_script_no_feature_takes_away(words: str): + """A command carries no condition (spec 2.9), so one naming a feature's script would break. + + `scripts/unlock_account.py` goes with accounts, and `fastro users unlock` in a project + without accounts would be a command pointing at a module that isn't there. + """ + module = _catalog()["commands"][words]["module"] + script = f"{_catalog()['blueprint']['python_root']}/{Path(*module.split('.')).with_suffix('.py')}" + + assert script not in _owned_paths(), script + + +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"] diff --git a/blueprint.toml b/blueprint.toml index 97226792..38eb2cc5 100644 --- a/blueprint.toml +++ b/blueprint.toml @@ -659,3 +659,39 @@ name = "PYTEST_PLUGINS" point = "test_plugins" annotation = "list[str]" literal = true + +[generators.deploy] +templates = "blueprint/templates/deploy" + +[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 = 8 +help = "The compose network, and the only peers uvicorn takes forwarded headers from, in nginx mode." + +[commands."env gen-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 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/fastro.toml b/fastro.toml new file mode 100644 index 00000000..ee853cbe --- /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 = "fastro", version = "0.20.0" } + +[project] +name = "fastapi-boilerplate" + +[options] +"cache.backend" = "redis" +"taskiq.broker" = "redis" From 951950b99013800c0c5bbf1b939c2706d7cfee6d Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Wed, 28 Oct 2026 19:12:31 -0300 Subject: [PATCH 15/71] declare the commands each feature brings with it --- backend/tests/unit/test_blueprint_catalog.py | 129 ++++++++++++++++--- blueprint.toml | 28 ++++ 2 files changed, 140 insertions(+), 17 deletions(-) diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index 910e13e9..b41b9aad 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -18,6 +18,7 @@ import re import sys import tomllib +from collections.abc import Iterable from pathlib import Path from typing import Any @@ -1222,11 +1223,46 @@ def test_the_defaults_are_what_this_repos_own_generator_already_uses(): assert f'DEFAULT_INTERNAL_SUBNET = "{params["internal_subnet"]["default"]}"' in subnet -@pytest.mark.parametrize("words", sorted(_catalog()["commands"])) -def test_every_command_is_spelled_the_way_the_spec_reads_it(words: str): - """Spec 2.9: the words become the command path, one space apart.""" - command = _catalog()["commands"][words] +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(".")) @@ -1235,27 +1271,86 @@ def test_every_command_is_spelled_the_way_the_spec_reads_it(words: str): assert command.get("outside_project", "error") in {"error", "token_hex"} -@pytest.mark.parametrize("words", sorted(_catalog()["commands"])) -def test_every_command_runs_a_module_this_repo_can_run(words: str): +@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.""" - module = _catalog()["commands"][words]["module"] - path = REPO_ROOT / _catalog()["blueprint"]["python_root"] / Path(*module.split(".")).with_suffix(".py") + path = REPO_ROOT / _catalog()["blueprint"]["python_root"] / Path(*command["module"].split(".")).with_suffix(".py") - assert path.is_file() + assert path.is_file(), words assert '__name__ == "__main__"' in path.read_text() -@pytest.mark.parametrize("words", sorted(_catalog()["commands"])) -def test_every_command_runs_a_script_no_feature_takes_away(words: str): - """A command carries no condition (spec 2.9), so one naming a feature's script would break. +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. - `scripts/unlock_account.py` goes with accounts, and `fastro users unlock` in a project - without accounts would be a command pointing at a module that isn't there. + 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. """ - module = _catalog()["commands"][words]["module"] - script = f"{_catalog()['blueprint']['python_root']}/{Path(*module.split('.')).with_suffix('.py')}" + 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. + """ + manifest = _drill() + owned = _owned_paths() + + for chosen in _selections(manifest): + kept = _kept_by_the_drill(manifest, 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 script not in _owned_paths(), script + assert offered == runnable, sorted(chosen) def test_the_blueprint_repo_says_it_is_the_blueprint(): diff --git a/blueprint.toml b/blueprint.toml index 38eb2cc5..0e92f2e0 100644 --- a/blueprint.toml +++ b/blueprint.toml @@ -219,6 +219,18 @@ table_modules = [{ value = "src.infrastructure.auth.store" }] seeders = [{ ref = "scripts.create_first_superuser:create_first_superuser", order = 11 }] test_plugins = [{ value = "tests.fixtures.accounts" }] +[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 = [ @@ -295,6 +307,10 @@ user_schema = ["src.modules.tier.contrib:UserTierFields"] seeders = [{ ref = "scripts.create_first_tier:create_first_tier", order = 10 }] test_plugins = [{ value = "tests.fixtures.tiers" }] +[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 = [ @@ -343,6 +359,18 @@ 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 = [ From 1ae7f452f3c47d0285b9f024fd5ef615713845cb Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Wed, 28 Oct 2026 23:53:37 -0300 Subject: [PATCH 16/71] write the baseline migration from a script, and declare it as a command --- backend/scripts/baseline.py | 182 +++++++++++++++ backend/tests/unit/scripts/test_baseline.py | 240 ++++++++++++++++++++ blueprint.toml | 4 + docs/user-guide/database/migrations.md | 6 + docs/user-guide/project-structure.md | 2 + 5 files changed, 434 insertions(+) create mode 100644 backend/scripts/baseline.py create mode 100644 backend/tests/unit/scripts/test_baseline.py 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/tests/unit/scripts/test_baseline.py b/backend/tests/unit/scripts/test_baseline.py new file mode 100644 index 00000000..78da1496 --- /dev/null +++ b/backend/tests/unit/scripts/test_baseline.py @@ -0,0 +1,240 @@ +"""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 + +HOST = "127.0.0.1" +PORT = 54321 + + +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): + monkeypatch.setattr(baseline, "created_schema", _schema_of({"alembic_version": []})) + + 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): + """It is read in this process, so a models import that stopped working would be silent.""" + declared = baseline.declared_schema() + + assert declared["alembic_version"] == [] + assert "user" in declared + + +def test_the_migrations_guide_names_the_script(): + """The guide's manual recipe is this script by hand, which a reader has no way to know.""" + guide = Path(baseline.__file__).resolve().parents[2] / "docs/user-guide/database/migrations.md" + + assert "python -m scripts.baseline" in guide.read_text() + + +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=Path(baseline.__file__).resolve().parents[1], + capture_output=True, + text=True, + env={**os.environ, "PYTHONPATH": str(Path(baseline.__file__).resolve().parents[1])}, + timeout=120, + ) + + assert result.returncode == 0, result.stdout + result.stderr + assert "--check" in result.stdout diff --git a/blueprint.toml b/blueprint.toml index 0e92f2e0..66c2e4dc 100644 --- a/blueprint.toml +++ b/blueprint.toml @@ -716,6 +716,10 @@ outside_project = "token_hex" 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." diff --git a/docs/user-guide/database/migrations.md b/docs/user-guide/database/migrations.md index 8be1f0d6..f1fac7e1 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 diff --git a/docs/user-guide/project-structure.md b/docs/user-guide/project-structure.md index c0417621..9694c951 100644 --- a/docs/user-guide/project-structure.md +++ b/docs/user-guide/project-structure.md @@ -29,6 +29,7 @@ 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 @@ -207,6 +208,7 @@ 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 From 7e49c355cfe6e8ddf4b093fb614e5b5b86db34f4 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Thu, 29 Oct 2026 00:09:27 -0300 Subject: [PATCH 17/71] say in every generated file that fastro generated it --- backend/scripts/seeders.py | 3 +- backend/src/wiring/__init__.py | 2 +- backend/src/wiring/admin.py | 3 +- backend/src/wiring/app.py | 4 +- backend/src/wiring/cache.py | 4 +- backend/src/wiring/email.py | 7 +-- backend/src/wiring/hooks.py | 4 +- backend/src/wiring/models.py | 3 +- backend/src/wiring/settings.py | 6 ++- backend/src/wiring/tables.py | 4 +- backend/src/wiring/tasks.py | 7 +-- backend/src/wiring/transports.py | 6 ++- backend/tests/unit/test_blueprint_catalog.py | 56 +++++++++++++++----- backend/tests/wiring.py | 3 +- 14 files changed, 78 insertions(+), 34 deletions(-) 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/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 b7b5f66f..434d9f32 100644 --- a/backend/src/wiring/hooks.py +++ b/backend/src/wiring/hooks.py @@ -1,7 +1,7 @@ """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 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/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/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 61bb4ba1..6fd060b2 100644 --- a/backend/src/wiring/tasks.py +++ b/backend/src/wiring/tasks.py @@ -1,8 +1,9 @@ """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, ...] = ( 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/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index b41b9aad..1c40d883 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -885,18 +885,6 @@ def test_every_wiring_file_is_under_the_python_root_and_is_a_file(path: str): assert (REPO_ROOT / path).is_file() -@pytest.mark.parametrize("path", [entry["path"] for entry in _entries()]) -def test_every_wiring_file_says_what_it_is_for(path: str): - """The entry's `doc` is the file's own docstring, minus the line naming what generated it.""" - entry = next(entry for entry in _entries() if entry["path"] == path) - docstring = ast.get_docstring(ast.parse(_committed(path))) - - assert docstring is not None - declared = entry["doc"].splitlines() - assert declared[0] == docstring.splitlines()[0] - assert " ".join(" ".join(declared[1:]).split()) in " ".join(docstring.split()) - - @pytest.mark.parametrize( ("path", "name"), [(entry["path"], slot["name"]) for entry in _entries() for slot in entry["slots"] if "annotation" in slot], @@ -1074,6 +1062,50 @@ def test_the_header_fits_the_line_length_of_the_files_it_goes_into(): 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" + + +@pytest.mark.parametrize("path", [entry["path"] for entry in _entries()]) +def test_no_generated_file_names_the_drill(path: str): + """The header names fastro as the author, and the drill goes in B3: two authors is one too many.""" + assert "removal_drill" not in _committed(path), path + + +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 + assert "removal_drill" not in docstring + + @pytest.mark.parametrize("path", [entry["path"] for entry in _entries()]) def test_the_catalog_accounts_for_what_the_file_imports_for_every_selection(path: str): """The fallbacks, where the committed files cannot reach: nothing falls back with all nine. 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] = [ From 48e8107f50e6aab241745d76f3f2c52217b755bc Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Fri, 30 Oct 2026 20:12:27 -0300 Subject: [PATCH 18/71] name the secret command what fastro names it, and keep the blueprint's own root files out of projects --- backend/tests/unit/test_blueprint_catalog.py | 66 ++++++++++++++++++++ blueprint.toml | 5 +- 2 files changed, 70 insertions(+), 1 deletion(-) diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index 1c40d883..85bc3b37 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -111,6 +111,72 @@ def test_every_blueprint_only_path_is_one_this_repo_has(entry: str): 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 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 _hook_paths() -> list[str]: + """The literal head of each pre-commit `files:` pattern, which is a path in the repository.""" + patterns = re.findall(r"^\s*files: (\S+)$", (REPO_ROOT / ".pre-commit-config.yaml").read_text(), re.M) + + return [re.split(r"[(\[{|?*+.\\]", pattern.removeprefix("^"))[0].rstrip("/") for pattern in patterns] + + +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": _workspace_members, + ".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 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": "cli", + ".pre-commit-config.yaml": "cli/src", + "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. When `cli/` goes + in B3, this is where the question of shipping the workspace root comes back. + """ + pointed = POINTS_AT[path]() + + assert any(target.startswith(WITHHELD_POINTERS[path]) for target in pointed), pointed + + def test_the_things_projects_must_not_receive_are_listed(): """The catalog, the drill, the docs and the tool's own tree belong to the blueprint only.""" listed = set(_catalog()["blueprint"]["blueprint_only"]) diff --git a/blueprint.toml b/blueprint.toml index 66c2e4dc..af2cf8c7 100644 --- a/blueprint.toml +++ b/blueprint.toml @@ -7,8 +7,10 @@ python_root = "backend" import_root = "src" blueprint_only = [ ".github/", + ".pre-commit-config.yaml", "CODE_OF_CONDUCT.md", "CONTRIBUTING.md", + "README.md", "backend/tests/unit/test_blueprint_catalog.py", "backend/tests/unit/test_docs_imports.py", "backend/tests/unit/test_docs_recipes.py", @@ -20,6 +22,7 @@ blueprint_only = [ "cli/", "docs/", "fastro.toml", + "pyproject.toml", "tools/", "uv.lock", "zensical.toml", @@ -707,7 +710,7 @@ default = "172.31.240.0/24" max_prefix = 8 help = "The compose network, and the only peers uvicorn takes forwarded headers from, in nginx mode." -[commands."env gen-secret"] +[commands."env secret"] module = "scripts.gen_secret" help = "Print a secret key the project's own rules accept." outside_project = "token_hex" From c7de105bdb0814c75ff18a03b06ba1c99a8e2bff Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Sat, 31 Oct 2026 00:00:54 -0300 Subject: [PATCH 19/71] keep the blueprint's own files out of the projects the drill builds --- backend/tests/unit/scripts/test_baseline.py | 51 ++++++++++++++---- .../tests/unit/scripts/test_validate_env.py | 52 ++++++++++++++++--- backend/tests/unit/test_blueprint_catalog.py | 50 +++++++++++++++++- backend/tests/unit/test_docs_scripts.py | 9 ++++ backend/tests/unit/test_removal_drill.py | 19 +++++++ blueprint.toml | 1 + tools/removal_drill.py | 15 ++++++ 7 files changed, 180 insertions(+), 17 deletions(-) diff --git a/backend/tests/unit/scripts/test_baseline.py b/backend/tests/unit/scripts/test_baseline.py index 78da1496..0a5d362e 100644 --- a/backend/tests/unit/scripts/test_baseline.py +++ b/backend/tests/unit/scripts/test_baseline.py @@ -16,10 +16,13 @@ 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.""" @@ -156,7 +159,8 @@ def test_the_commands_run_against_the_container(versions, container, matching, a def test_a_database_the_models_do_not_declare_is_refused(versions, container, alembic, monkeypatch, capsys): - monkeypatch.setattr(baseline, "created_schema", _schema_of({"alembic_version": []})) + """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"]) @@ -211,28 +215,57 @@ def test_a_project_that_already_has_a_history_is_refused(versions, container, ma def test_the_declared_schema_is_the_one_the_models_build(versions): - """It is read in this process, so a models import that stopped working would be silent.""" + """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 "user" in declared + 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. -def test_the_migrations_guide_names_the_script(): - """The guide's manual recipe is this script by hand, which a reader has no way to know.""" - guide = Path(baseline.__file__).resolve().parents[2] / "docs/user-guide/database/migrations.md" + 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") - assert "python -m scripts.baseline" in guide.read_text() + 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=Path(baseline.__file__).resolve().parents[1], + cwd=BACKEND, capture_output=True, text=True, - env={**os.environ, "PYTHONPATH": str(Path(baseline.__file__).resolve().parents[1])}, + env={**os.environ, "PYTHONPATH": str(BACKEND)}, timeout=120, ) diff --git a/backend/tests/unit/scripts/test_validate_env.py b/backend/tests/unit/scripts/test_validate_env.py index 821803a5..af6c8fae 100644 --- a/backend/tests/unit/scripts/test_validate_env.py +++ b/backend/tests/unit/scripts/test_validate_env.py @@ -14,6 +14,7 @@ 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 @@ -39,8 +40,31 @@ def _audited(monkeypatch, settings: Settings) -> None: 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]: - return { + """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", @@ -54,6 +78,8 @@ def _strong() -> dict[str, Any]: "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())) @@ -77,8 +103,12 @@ def test_a_weak_configuration_is_refused_and_named(monkeypatch, capsys): def test_warnings_are_reported_even_when_something_is_critical(monkeypatch, capsys): - """The warnings used to be computed only when nothing critical was found.""" - _audited(monkeypatch, _settings(SECRET_KEY="insecure-secret-key-change-this")) + """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() @@ -89,8 +119,12 @@ def test_warnings_are_reported_even_when_something_is_critical(monkeypatch, caps 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.""" - _audited(monkeypatch, _settings(**(_strong() | {"CACHE_REDIS_PASSWORD": ""}))) + """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() @@ -101,8 +135,12 @@ def test_warnings_alone_do_not_fail_the_audit(monkeypatch, capsys): 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.""" - _audited(monkeypatch, _settings(ENVIRONMENT=EnvironmentOption.DEVELOPMENT, EMAIL_BACKEND="console")) + """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() diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index 85bc3b37..14028346 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -113,7 +113,10 @@ def test_every_blueprint_only_path_is_one_this_repo_has(entry: str): 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 path.startswith(entry) for entry in _catalog()["blueprint"]["blueprint_only"]) + return any( + path == entry.rstrip("/") or (entry.endswith("/") and path.startswith(entry)) + for entry in _catalog()["blueprint"]["blueprint_only"] + ) def _workspace_members() -> list[str]: @@ -177,6 +180,51 @@ def test_each_file_still_names_the_path_that_keeps_it_out(path: str): assert any(target.startswith(WITHHELD_POINTERS[path]) for target in pointed), pointed +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/`, `tools/` or `cli/` is a test no project can run. + + `test_removal_drill.py` loads `tools/removal_drill.py`, and `test_baseline.py` read the + migrations guide: both are files a project never receives, and the drill hid it by copying + the whole repository into every project it built. 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, the drill, the docs and the tool's own tree belong to the blueprint only.""" listed = set(_catalog()["blueprint"]["blueprint_only"]) 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_removal_drill.py b/backend/tests/unit/test_removal_drill.py index 97ecc211..eb3bce9d 100644 --- a/backend/tests/unit/test_removal_drill.py +++ b/backend/tests/unit/test_removal_drill.py @@ -223,6 +223,25 @@ def _without_formatting(source: str) -> tuple[tuple[str, ...], tuple[str, ...]]: return tuple(imports), tuple(statements) +def test_a_project_is_kept_from_everything_the_catalog_reserves(): + """A project that received the catalog, this drill or the docs would run the blueprint's own + tests against itself, and they describe a repository it is not. Spec 1.1: an entry with a + trailing slash reserves the whole subtree, not just the directory.""" + reserved = drill.blueprint_only() + + assert reserved, "the catalog reserves nothing, so this reads it wrongly" + for entry in reserved: + assert drill.withheld(entry.rstrip("/")), entry + if entry.endswith("/"): + assert drill.withheld(f"{entry}somewhere/deeper.py"), entry + + +def test_nothing_a_drill_step_needs_is_kept_from_the_project(): + """Every step runs from `backend/`, and reads its configuration and its tests from there.""" + for needed in ("backend", "backend/pyproject.toml", "backend/tests/conftest.py", "backend/src/wiring/app.py"): + assert not drill.withheld(needed), needed + + 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() diff --git a/blueprint.toml b/blueprint.toml index af2cf8c7..b644461a 100644 --- a/blueprint.toml +++ b/blueprint.toml @@ -17,6 +17,7 @@ blueprint_only = [ "backend/tests/unit/test_docs_scripts.py", "backend/tests/unit/test_docs_wiring.py", "backend/tests/unit/test_image_contents.py", + "backend/tests/unit/test_removal_drill.py", "blueprint/", "blueprint.toml", "cli/", diff --git a/tools/removal_drill.py b/tools/removal_drill.py index 334d1a06..2d689f9d 100644 --- a/tools/removal_drill.py +++ b/tools/removal_drill.py @@ -20,6 +20,7 @@ import subprocess import sys import tempfile +import tomllib from dataclasses import dataclass, field from pathlib import Path @@ -541,6 +542,17 @@ def _tests_wiring(chosen: set[str]) -> str: ) +def blueprint_only() -> tuple[str, ...]: + """The paths a project never receives, as `blueprint.toml` lists them.""" + with (REPO / "blueprint.toml").open("rb") as handle: + return tuple(tomllib.load(handle)["blueprint"]["blueprint_only"]) + + +def withheld(path: str) -> bool: + """Whether a project is kept from receiving this path: a trailing slash means its subtree.""" + return any(path == entry.rstrip("/") or (entry.endswith("/") and path.startswith(entry)) for entry in blueprint_only()) + + def copy_repository(source: Path, project: Path) -> None: """Copy ``source`` to ``project``, leaving out what a scratch build must not carry.""" shutil.copytree( @@ -556,6 +568,9 @@ def build(preset: str, into: Path) -> Path: project = into / preset copy_repository(REPO, project) + for entry in blueprint_only(): + _remove(project / entry.rstrip("/")) + for name, feature in FEATURES.items(): if name in chosen: for partner, paths in feature.combination_paths.items(): From 2879f5a5b12dbb0b92c15115eafb603ffc610c2d Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Sat, 31 Oct 2026 00:14:17 -0300 Subject: [PATCH 20/71] declare faker and httpx for development, which is where they are imported --- backend/pyproject.toml | 4 +- backend/tests/unit/test_blueprint_catalog.py | 90 ++++++++++++++++++++ blueprint.toml | 4 +- docs/changelog.md | 4 + uv.lock | 8 +- 5 files changed, 102 insertions(+), 8 deletions(-) diff --git a/backend/pyproject.toml b/backend/pyproject.toml index 2f016c69..efca55fe 100644 --- a/backend/pyproject.toml +++ b/backend/pyproject.toml @@ -18,11 +18,9 @@ dependencies = [ "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", "fastcrud>=0.21.0", "greenlet>=3.1.1", - "httpx>=0.28.1", "itsdangerous>=2.2.0", "jinja2>=3.1.6", "pydantic>=2.10.6", @@ -48,6 +46,8 @@ 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", ] [tool.setuptools.packages.find] diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index 14028346..b1b42c64 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -19,6 +19,7 @@ import sys import tomllib from collections.abc import Iterable +from importlib.metadata import packages_distributions from pathlib import Path from typing import Any @@ -93,6 +94,95 @@ def test_the_core_dependencies_are_the_ones_the_backend_declares(): assert dependencies["dev"] == backend["project"]["optional-dependencies"]["dev"] +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 _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} + found: set[str] = set() + for directory in directories: + for path in sorted((root / directory).rglob("*.py")): + if path in skipped: + continue + + for node in ast.walk(ast.parse(path.read_text())): + 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) + + +def _declared_distributions(listing: str) -> set[str]: + return {_distribution(specifier) for specifier in _catalog()["blueprint"]["dependencies"][listing]} + + +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. diff --git a/blueprint.toml b/blueprint.toml index b644461a..23e8a4c2 100644 --- a/blueprint.toml +++ b/blueprint.toml @@ -38,11 +38,9 @@ runtime = [ "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", "fastcrud>=0.21.0", "greenlet>=3.1.1", - "httpx>=0.28.1", "itsdangerous>=2.2.0", "jinja2>=3.1.6", "pydantic>=2.10.6", @@ -66,6 +64,8 @@ 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", ] [presets] diff --git a/docs/changelog.md b/docs/changelog.md index 32ad0a17..37e52686 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -17,6 +17,10 @@ ___ 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. ___ diff --git a/uv.lock b/uv.lock index 897ebc29..0811bdf3 100644 --- a/uv.lock +++ b/uv.lock @@ -890,11 +890,9 @@ dependencies = [ { 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" }, @@ -911,6 +909,8 @@ dependencies = [ [package.optional-dependencies] dev = [ + { name = "faker" }, + { name = "httpx" }, { name = "mypy" }, { name = "pre-commit" }, { name = "pytest" }, @@ -931,11 +931,11 @@ requires-dist = [ { 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 = "faker", marker = "extra == 'dev'", specifier = ">=37.1.0" }, { name = "fastapi", extras = ["standard"], specifier = ">=0.115.8" }, { 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 = "mypy", marker = "extra == 'dev'", specifier = ">=1.14.1" }, From 52abbcf9b8c81fb44de5034cbf14d49cf5d3455f Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Sat, 31 Oct 2026 00:24:19 -0300 Subject: [PATCH 21/71] declare each feature's own dependencies, and the memcached option's --- .../cache/backends/test_memcached.py | 10 +- backend/tests/unit/test_blueprint_catalog.py | 164 ++++++++++++++++-- blueprint.toml | 17 +- 3 files changed, 167 insertions(+), 24 deletions(-) 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/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index b1b42c64..3f51b19e 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -83,15 +83,31 @@ def test_development_builds_of_the_tool_can_read_it(): assert _catalog()["blueprint"]["requires_fastro"] == ">=0.1.0.dev0,<0.2" -def test_the_core_dependencies_are_the_ones_the_backend_declares(): - """The catalog carries the backend's lists until they are split per feature.""" +def _declared_specifiers() -> set[str]: + """Every runtime specifier a project could install: the core's, each feature's, each option's.""" + specifiers = set(_catalog()["blueprint"]["dependencies"]["runtime"]) + for feature in _catalog()["features"].values(): + specifiers.update(feature.get("dependencies", ())) + for block in feature.get("when", ()): + specifiers.update(block.get("dependencies", ())) + for option in feature.get("options", {}).values(): + 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) - dependencies = _catalog()["blueprint"]["dependencies"] - - assert dependencies["runtime"] == backend["project"]["dependencies"] - assert dependencies["dev"] == backend["project"]["optional-dependencies"]["dev"] + assert _declared_specifiers() == set(backend["project"]["dependencies"]) + assert _catalog()["blueprint"]["dependencies"]["dev"] == backend["project"]["optional-dependencies"]["dev"] def _distribution(specifier: str) -> str: @@ -111,31 +127,149 @@ def _provided() -> dict[str, frozenset[str]]: 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 directory in directories: - for path in sorted((root / directory).rglob("*.py")): - if path in skipped: - continue + for node in ast.walk(tree): + if id(node) in guarded: + continue - for node in ast.walk(ast.parse(path.read_text())): - 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]) + 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: `runtime` is every list a project could install from.""" + if listing == "runtime": + return {_distribution(specifier) for specifier in _declared_specifiers()} + return {_distribution(specifier) for specifier in _catalog()["blueprint"]["dependencies"][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 +`crudauth/transports/session/__init__.py` 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.""" + + +@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) + + +@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. diff --git a/blueprint.toml b/blueprint.toml index 23e8a4c2..6191c4e9 100644 --- a/blueprint.toml +++ b/blueprint.toml @@ -31,28 +31,20 @@ blueprint_only = [ [blueprint.dependencies] runtime = [ - "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", "fastapi[standard]>=0.115.8", "fastcrud>=0.21.0", "greenlet>=3.1.1", - "itsdangerous>=2.2.0", "jinja2>=3.1.6", "pydantic>=2.10.6", "pydantic-settings>=2.14.2", "redis>=6.1.0", - "sqladmin>=0.28.0", "sqlalchemy>=2.0.37", "starlette>=1.3.1", - "taskiq>=0.11.20", - "taskiq-redis>=1.1.2", - "taskiq-aio-pika>=0.4.3", - "user-agents>=2.2.0", ] dev = [ "mypy>=1.14.1", @@ -184,6 +176,7 @@ 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", @@ -405,6 +398,7 @@ paths = [ 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/", @@ -433,11 +427,18 @@ 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", +] paths = [ "backend/src/infrastructure/taskiq/", "backend/tests/unit/infrastructure/taskiq/", From e6aa1c28b2ea93645413623d5433bf4da6f921a4 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Sat, 31 Oct 2026 00:34:14 -0300 Subject: [PATCH 22/71] declare each feature's own dependencies, and the memcached option's --- backend/tests/unit/test_blueprint_catalog.py | 61 ++++++++++++++++++-- 1 file changed, 57 insertions(+), 4 deletions(-) diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index 3f51b19e..757d5349 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -210,10 +210,11 @@ def _declared_distributions(listing: str) -> set[str]: "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 -`crudauth/transports/session/__init__.py` 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.""" +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.""" @pytest.mark.parametrize( @@ -244,6 +245,58 @@ def test_every_feature_dependency_is_one_that_feature_needs(feature: str, specif 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(_drill()): + 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) + + @pytest.mark.parametrize( ("feature", "option", "value", "specifier"), sorted( From b607680ec5d84dde7d17051c459cb001167bf851 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Sat, 31 Oct 2026 00:55:15 -0300 Subject: [PATCH 23/71] drop the dependency nothing used, and account for the ones nothing imports --- backend/pyproject.toml | 3 +- backend/tests/conftest.py | 2 - .../infrastructure/config/test_settings.py | 8 ---- backend/tests/unit/test_blueprint_catalog.py | 37 ++++++++++++++++++- blueprint.toml | 3 +- docs/changelog.md | 4 ++ uv.lock | 15 +------- 7 files changed, 44 insertions(+), 28 deletions(-) diff --git a/backend/pyproject.toml b/backend/pyproject.toml index efca55fe..f26c53ea 100644 --- a/backend/pyproject.toml +++ b/backend/pyproject.toml @@ -12,7 +12,6 @@ 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", @@ -22,7 +21,6 @@ dependencies = [ "fastcrud>=0.21.0", "greenlet>=3.1.1", "itsdangerous>=2.2.0", - "jinja2>=3.1.6", "pydantic>=2.10.6", "pydantic-settings>=2.14.2", "redis>=6.1.0", @@ -48,6 +46,7 @@ dev = [ "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/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/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/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index 757d5349..88a13974 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -19,7 +19,7 @@ import sys import tomllib from collections.abc import Iterable -from importlib.metadata import packages_distributions +from importlib.metadata import packages_distributions, requires from pathlib import Path from typing import Any @@ -217,6 +217,41 @@ def _declared_distributions(listing: str) -> set[str]: 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", default="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( diff --git a/blueprint.toml b/blueprint.toml index 6191c4e9..6dd734c0 100644 --- a/blueprint.toml +++ b/blueprint.toml @@ -31,7 +31,6 @@ blueprint_only = [ [blueprint.dependencies] runtime = [ - "aiosqlite>=0.21.0", "alembic>=1.16.4", "anyio>=4.15.1", "asyncpg>=0.30.0", @@ -39,7 +38,6 @@ runtime = [ "fastapi[standard]>=0.115.8", "fastcrud>=0.21.0", "greenlet>=3.1.1", - "jinja2>=3.1.6", "pydantic>=2.10.6", "pydantic-settings>=2.14.2", "redis>=6.1.0", @@ -58,6 +56,7 @@ dev = [ "pre-commit>=4.0.0", "faker>=37.1.0", "httpx>=0.28.1", + "jinja2>=3.1.6", ] [presets] diff --git a/docs/changelog.md b/docs/changelog.md index 37e52686..29d25861 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -21,6 +21,10 @@ ___ 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. ___ diff --git a/uv.lock b/uv.lock index 0811bdf3..ea8f91a4 100644 --- a/uv.lock +++ b/uv.lock @@ -232,15 +232,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,7 +875,6 @@ version = "0.20.0" source = { editable = "backend" } dependencies = [ { name = "aiomcache" }, - { name = "aiosqlite" }, { name = "alembic" }, { name = "anyio" }, { name = "asyncpg" }, @@ -894,7 +884,6 @@ dependencies = [ { name = "fastcrud" }, { name = "greenlet" }, { name = "itsdangerous" }, - { name = "jinja2" }, { name = "pydantic" }, { name = "pydantic-settings" }, { name = "redis" }, @@ -911,6 +900,7 @@ dependencies = [ dev = [ { name = "faker" }, { name = "httpx" }, + { name = "jinja2" }, { name = "mypy" }, { name = "pre-commit" }, { name = "pytest" }, @@ -925,7 +915,6 @@ 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" }, @@ -937,7 +926,7 @@ requires-dist = [ { name = "greenlet", specifier = ">=3.1.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" }, From e838bf0107945121d32a275b7b233ef8b45e3cfd Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Sat, 31 Oct 2026 01:20:35 -0300 Subject: [PATCH 24/71] give every section of the environment example one owner --- backend/.env.example | 38 ++++++--- backend/tests/unit/test_blueprint_catalog.py | 90 ++++++++++++++++++++ 2 files changed, 114 insertions(+), 14 deletions(-) diff --git a/backend/.env.example b/backend/.env.example index 791e7fe2..6543bbaf 100644 --- a/backend/.env.example +++ b/backend/.env.example @@ -45,10 +45,6 @@ CACHE_ENABLED=true # @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 @@ -68,15 +64,21 @@ CACHE_REDIS_POOL_SIZE=10 # =================================== # Rate Limiting Configuration # =================================== -# Provided by crudauth (Redis-backed). Limits are resolved per request from the +# 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 +# =================================== +# 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) @@ -179,12 +181,23 @@ 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. The login lockout, where +# there is one, counts proxy hops with TRUSTED_PROXY_HOPS instead. +# 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 @@ -192,6 +205,9 @@ SECRET_KEY=insecure-secret-key-change-this-in-production # Automatically validates security settings in production environments PRODUCTION_SECURITY_VALIDATION_ENABLED=true +# =================================== +# Authentication & Security +# =================================== # Session Management SESSION_TIMEOUT_MINUTES=30 SESSION_CLEANUP_INTERVAL_MINUTES=15 @@ -233,12 +249,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 diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index 88a13974..024da6af 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -1243,6 +1243,96 @@ def test_every_option_offers_the_values_its_feature_acts_on(feature: str, option ) +ENV_EXAMPLE = REPO_ROOT / "backend" / ".env.example" + +NOT_A_SETTING = { + "DATABASE_URL": "core", + "FORWARDED_ALLOW_IPS": "core", + "SESSION_REDIS_URL": "accounts", +} +"""Variables the example sets that no settings field declares, and where each belongs: +`DATABASE_URL` is the name `DATABASE_URL_OVERRIDE` is aliased to, `FORWARDED_ALLOW_IPS` is read +by uvicorn and written by the deploy templates, and `SESSION_REDIS_URL` is built by the accounts +settings rather than declared as a field.""" + + +@functools.cache +def _settings_fields() -> dict[str, frozenset[str]]: + """Which part of the project declares each setting: `core`, or the features whose contributed + settings classes declare it.""" + 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(): + declared.setdefault(node.target.id, set()).add(owner) + + return {name: frozenset(owners) for name, owners in declared.items()} + + +@functools.cache +def _env_sections() -> tuple[tuple[str, tuple[str, ...]], ...]: + """Each section of the example: its title, 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)) + ) + sections.append((lines[start + 1].lstrip("# ").strip(), 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]}) + + +@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. + """ + variables = next(found for name, found in _env_sections() if name == title) + owners = {owner for variable in variables for owner in _owner_of(variable)} + + assert len(owners) <= 1, sorted(owners) + + +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 = dict(_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"}) + + @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.""" From 2ffce919a232aa2696462e5fcb89f87dafc47f34 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Sat, 31 Oct 2026 01:38:45 -0300 Subject: [PATCH 25/71] say which feature keeps each section of the environment example --- backend/.env.example | 64 ++++-- backend/tests/unit/test_blueprint_catalog.py | 193 +++++++++++++++++-- 2 files changed, 221 insertions(+), 36 deletions(-) diff --git a/backend/.env.example b/backend/.env.example index 6543bbaf..a7374a7c 100644 --- a/backend/.env.example +++ b/backend/.env.example @@ -40,6 +40,7 @@ POSTGRES_POOL_RECYCLE=-1 # =================================== # Cache Configuration # =================================== +# @fastro if=cache CACHE_ENABLED=true # Options: memcached, redis # @fastro option=cache.backend @@ -61,9 +62,13 @@ 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 # =================================== +# @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 @@ -73,6 +78,7 @@ 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 @@ -91,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 # =================================== @@ -120,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 @@ -134,6 +144,7 @@ KEY_USAGE_RETENTION_DAYS=90 # =================================== # Taskiq Configuration # =================================== +# @fastro if=taskiq # Broker type: 'redis' or 'rabbitmq' # @fastro option=taskiq.broker TASKIQ_BROKER_TYPE=redis @@ -162,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 @@ -188,8 +202,7 @@ 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. The login lockout, where -# there is one, counts proxy hops with TRUSTED_PROXY_HOPS instead. +# address. Leave unset when nothing sits in front of the app. # FORWARDED_ALLOW_IPS=172.31.240.0/24 # API documentation settings @@ -208,6 +221,7 @@ PRODUCTION_SECURITY_VALIDATION_ENABLED=true # =================================== # Authentication & Security # =================================== +# @fastro if=accounts # Session Management SESSION_TIMEOUT_MINUTES=30 SESSION_CLEANUP_INTERVAL_MINUTES=15 @@ -235,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 @@ -256,9 +278,14 @@ 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) # =================================== +# @fastro if=admin # Enable/disable the admin interface ADMIN_ENABLED=true # Where the panel is mounted; the admin session cookie is scoped to this path @@ -267,6 +294,7 @@ ADMIN_BASE_URL=/admin # =================================== # OAuth Configuration # =================================== +# @fastro if=accounts OAUTH_REDIRECT_BASE_URL=http://localhost:8000 # Google OAuth @@ -321,15 +349,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 # =================================== @@ -337,16 +375,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/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index 024da6af..107a1948 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -1246,20 +1246,36 @@ def test_every_option_offers_the_values_its_feature_acts_on(feature: str, option ENV_EXAMPLE = REPO_ROOT / "backend" / ".env.example" NOT_A_SETTING = { - "DATABASE_URL": "core", "FORWARDED_ALLOW_IPS": "core", - "SESSION_REDIS_URL": "accounts", } -"""Variables the example sets that no settings field declares, and where each belongs: -`DATABASE_URL` is the name `DATABASE_URL_OVERRIDE` is aliased to, `FORWARDED_ALLOW_IPS` is read -by uvicorn and written by the deploy templates, and `SESSION_REDIS_URL` is built by the accounts -settings rather than declared as a field.""" +"""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 part of the project declares each setting: `core`, or the features whose contributed - settings classes declare it.""" + """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", ()): @@ -1271,15 +1287,38 @@ def _settings_fields() -> dict[str, frozenset[str]]: 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(): - declared.setdefault(node.target.id, set()).add(owner) + 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_sections() -> tuple[tuple[str, tuple[str, ...]], ...]: - """Each section of the example: its title, and the variables it sets, including the ones it - ships commented out, since a reader uncomments them where they sit.""" +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 = [ @@ -1294,7 +1333,8 @@ def _env_sections() -> tuple[tuple[str, tuple[str, ...]], ...]: variables = tuple( found.group(1) for line in lines[start + 3 : end] if (found := re.match(r"^#?\s*([A-Z][A-Z0-9_]*)=", line)) ) - sections.append((lines[start + 1].lstrip("# ").strip(), variables)) + 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) @@ -1309,28 +1349,145 @@ def _owner_of(variable: str) -> frozenset[str]: return frozenset({NOT_A_SETTING[variable]}) -@pytest.mark.parametrize("title", [title for title, _ in _env_sections()]) +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. """ - variables = next(found for name, found in _env_sections() if name == title) - owners = {owner for variable in variables for owner in _owner_of(variable)} + 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 len(owners) <= 1, sorted(owners) + assert marked == under_headers + assert all(_true(marker.removeprefix("# @fastro if="), set(_catalog()["features"])) for marker in marked) 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 = dict(_env_sections()) + 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)) From 7dad5848dc409e206c35b98adb02ea3ff1dad5b6 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Sat, 31 Oct 2026 01:44:50 -0300 Subject: [PATCH 26/71] keep the blueprint's own files out of the source tarball --- .gitattributes | 4 ++ backend/tests/unit/test_tarball_contents.py | 59 +++++++++++++++++++++ blueprint.toml | 2 + 3 files changed, 65 insertions(+) create mode 100644 .gitattributes create mode 100644 backend/tests/unit/test_tarball_contents.py diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..c4926b32 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,4 @@ +docs/ export-ignore +tools/ export-ignore +zensical.toml export-ignore +.github/ISSUE_TEMPLATE/ export-ignore diff --git a/backend/tests/unit/test_tarball_contents.py b/backend/tests/unit/test_tarball_contents.py new file mode 100644 index 00000000..84b82b84 --- /dev/null +++ b/backend/tests/unit/test_tarball_contents.py @@ -0,0 +1,59 @@ +"""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, the +removal drill and the issue templates are things to read or run 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/", "tools/", "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 diff --git a/blueprint.toml b/blueprint.toml index 6dd734c0..55954b4d 100644 --- a/blueprint.toml +++ b/blueprint.toml @@ -6,6 +6,7 @@ requires_fastro = ">=0.1.0.dev0,<0.2" python_root = "backend" import_root = "src" blueprint_only = [ + ".gitattributes", ".github/", ".pre-commit-config.yaml", "CODE_OF_CONDUCT.md", @@ -18,6 +19,7 @@ blueprint_only = [ "backend/tests/unit/test_docs_wiring.py", "backend/tests/unit/test_image_contents.py", "backend/tests/unit/test_removal_drill.py", + "backend/tests/unit/test_tarball_contents.py", "blueprint/", "blueprint.toml", "cli/", From e46bf26cf8b2f2f2bb182e29b0b78b3b7ba34616 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Sat, 31 Oct 2026 01:54:36 -0300 Subject: [PATCH 27/71] give taskiq's reload extra to the taskiq feature, and drop the example's em dash --- backend/.env.example | 2 +- backend/tests/unit/test_blueprint_catalog.py | 79 ++++++++++++++++---- blueprint.toml | 5 +- 3 files changed, 67 insertions(+), 19 deletions(-) diff --git a/backend/.env.example b/backend/.env.example index a7374a7c..9d28355d 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 diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index 107a1948..b2b19dad 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -83,14 +83,16 @@ def test_development_builds_of_the_tool_can_read_it(): assert _catalog()["blueprint"]["requires_fastro"] == ">=0.1.0.dev0,<0.2" -def _declared_specifiers() -> set[str]: - """Every runtime specifier a project could install: the core's, each feature's, each option's.""" - specifiers = set(_catalog()["blueprint"]["dependencies"]["runtime"]) +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("dependencies", ())) + specifiers.update(feature.get(key, ())) for block in feature.get("when", ()): - specifiers.update(block.get("dependencies", ())) - for option in feature.get("options", {}).values(): + 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) @@ -107,7 +109,7 @@ def test_the_dependencies_a_project_could_install_are_the_ones_the_backend_decla backend = tomllib.load(handle) assert _declared_specifiers() == set(backend["project"]["dependencies"]) - assert _catalog()["blueprint"]["dependencies"]["dev"] == backend["project"]["optional-dependencies"]["dev"] + assert _declared_specifiers("dev") == set(backend["project"]["optional-dependencies"]["dev"]) def _distribution(specifier: str) -> str: @@ -198,11 +200,8 @@ def _importers() -> dict[str, frozenset[str]]: def _declared_distributions(listing: str) -> set[str]: - """The distributions a listing names: `runtime` is every list a project could install from.""" - if listing == "runtime": - return {_distribution(specifier) for specifier in _declared_specifiers()} - - return {_distribution(specifier) for specifier in _catalog()["blueprint"]["dependencies"][listing]} + """The distributions a listing names, the core's and every feature's together.""" + return {_distribution(specifier) for specifier in _declared_specifiers(listing)} INDIRECT_NEEDS = { @@ -332,6 +331,28 @@ def test_no_file_a_project_keeps_imports_a_dependency_it_did_not_select(): assert _under(file, removed) or _withheld(file), (sorted(chosen), name, file) +@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( @@ -1803,8 +1824,19 @@ def test_the_catalog_accounts_for_what_the_file_imports_for_every_selection(path assert _declared_bindings(catalog, entry, chosen) == written, sorted(chosen) -LINE_LENGTH = 128 -"""The project's ruff line length, which spec 2.8 wraps a generated import at.""" +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()]) @@ -1903,9 +1935,21 @@ def test_every_param_is_declared_the_way_the_spec_asks(generator: str, param: st 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" + - assert str(ipaddress.ip_network(declared["default"], strict=True)) == declared["default"] - assert 0 <= declared["max_prefix"] <= 128 +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(): @@ -1927,6 +1971,9 @@ def test_the_defaults_are_what_this_repos_own_generator_already_uses(): assert f'typer.Option({params["workers"]["default"]}, "--workers"' in source assert f'DEFAULT_INTERNAL_SUBNET = "{params["internal_subnet"]["default"]}"' in subnet + limits = params["internal_subnet"]["max_prefix"] + assert f"SMALLEST_TRUSTED_PREFIX = {{4: {limits['v4']}, 6: {limits['v6']}}}" in subnet + 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. diff --git a/blueprint.toml b/blueprint.toml index 55954b4d..84f2ffff 100644 --- a/blueprint.toml +++ b/blueprint.toml @@ -54,7 +54,6 @@ dev = [ "pytest-mock>=3.14.0", "testcontainers[postgres]>=4.10.0", "pytest-xdist[psutil]>=3.8.0", - "taskiq[reload]>=0.11.20", "pre-commit>=4.0.0", "faker>=37.1.0", "httpx>=0.28.1", @@ -440,6 +439,7 @@ dependencies = [ "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/", @@ -467,6 +467,7 @@ contributes.task_modules = [{ value = "src.infrastructure.taskiq.email", order = [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`.""" @@ -710,7 +711,7 @@ 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 = 8 +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"] From ccae106a37e7917c452499bffd52e744bf57349e Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Sat, 31 Oct 2026 02:07:55 -0300 Subject: [PATCH 28/71] give projects their own gitignore and agent instructions --- blueprint.toml | 2 + blueprint/overlay/.gitignore | 22 ++++++ blueprint/overlay/AGENTS.md | 43 +++++++++++ blueprint/overlay/CLAUDE.md | 1 + blueprint/tests/test_overlay.py | 133 ++++++++++++++++++++++++++++++++ 5 files changed, 201 insertions(+) create mode 100644 blueprint/overlay/.gitignore create mode 100644 blueprint/overlay/AGENTS.md create mode 100644 blueprint/overlay/CLAUDE.md create mode 100644 blueprint/tests/test_overlay.py diff --git a/blueprint.toml b/blueprint.toml index 84f2ffff..8017ce00 100644 --- a/blueprint.toml +++ b/blueprint.toml @@ -4,9 +4,11 @@ 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", 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/AGENTS.md b/blueprint/overlay/AGENTS.md new file mode 100644 index 00000000..72be0aa3 --- /dev/null +++ b/blueprint/overlay/AGENTS.md @@ -0,0 +1,43 @@ +# Working in this project + +A FastAPI backend generated 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/tests/test_overlay.py b/blueprint/tests/test_overlay.py new file mode 100644 index 00000000..d6acbd52 --- /dev/null +++ b/blueprint/tests/test_overlay.py @@ -0,0 +1,133 @@ +"""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 +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. Anything else after `fastro` has to be a command the catalog declares.""" + +A_FASTRO_COMMAND = re.compile(r"\bfastro ((?:[a-z][a-z0-9-]*)(?: [a-z][a-z0-9-]*)?)") + +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 _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): + """Two files at one path, and nothing says which wins: the overlay's `.gitignore` is the + project's, so this repository's own is `blueprint_only` and never copied.""" + landing = Path(path) + written = landing.with_suffix("") if landing.suffix == ".j2" else landing + + assert not (REPO_ROOT / written).exists() or _withheld(written.as_posix()), written.as_posix() + + +@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.""" + environment = Environment(loader=FileSystemLoader(OVERLAY), undefined=StrictUndefined, keep_trailing_newline=True) + source = environment.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 rest: + assert named in declared, named + else: + assert verb in BUILT_IN_COMMANDS or verb in declared, named + + +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" From 513647a9c6c526b4a69f2c6012804b02bfb3541d Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Sat, 31 Oct 2026 02:33:42 -0300 Subject: [PATCH 29/71] give projects a readme that matches what they carry --- blueprint/overlay/README.md.j2 | 109 ++++++++++++++++++++++++++++ blueprint/tests/test_overlay.py | 121 +++++++++++++++++++++++++++++--- 2 files changed, 220 insertions(+), 10 deletions(-) create mode 100644 blueprint/overlay/README.md.j2 diff --git a/blueprint/overlay/README.md.j2 b/blueprint/overlay/README.md.j2 new file mode 100644 index 00000000..7126c09a --- /dev/null +++ b/blueprint/overlay/README.md.j2 @@ -0,0 +1,109 @@ +# {{ project.name }} + +A FastAPI backend, generated from the {{ blueprint.name }} blueprint ({{ 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 + +`backend/.env.example` turns it on, so a copied example has it at `/admin`. Set +`ADMIN_ENABLED=false` where you don't want it, and give `ADMIN_USERNAME` and `ADMIN_PASSWORD` +values of your own before anything but your laptop can reach it. +{%- 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/blueprint/tests/test_overlay.py b/blueprint/tests/test_overlay.py index d6acbd52..506e3ed7 100644 --- a/blueprint/tests/test_overlay.py +++ b/blueprint/tests/test_overlay.py @@ -23,9 +23,15 @@ """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. Anything else after `fastro` has to be a command the catalog declares.""" +"""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 ((?:[a-z][a-z0-9-]*)(?: [a-z][a-z0-9-]*)?)") +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 of `\S+` 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 @@ -60,6 +66,26 @@ def _declared_commands() -> set[str]: 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)) @@ -74,12 +100,20 @@ def test_the_overlay_is_where_the_catalog_says(): @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): - """Two files at one path, and nothing says which wins: the overlay's `.gitignore` is the - project's, so this repository's own is `blueprint_only` and never copied.""" - landing = Path(path) - written = landing.with_suffix("") if landing.suffix == ".j2" else landing + """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 - assert not (REPO_ROOT / written).exists() or _withheld(written.as_posix()), written.as_posix() + +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"]) @@ -113,10 +147,77 @@ def test_every_fastro_command_the_overlay_names_is_one_a_project_has(path: str): verb, _, rest = named.partition(" ") if verb == "make" and rest: assert rest in CATALOG["generators"], named - elif rest: - assert named in declared, named + elif verb in BUILT_IN_COMMANDS: + continue else: - assert verb in BUILT_IN_COMMANDS or verb in declared, named + 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_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 + + +def test_every_fastro_command_in_the_readme_runs_the_tool_that_generated_the_project(): + """`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. + + Only what a reader runs is checked: `fastro.toml` is a file and `fastro.version` is a context + value, not something to run. + """ + spans = [span or fenced for span, fenced in A_CODE_SPAN.findall((OVERLAY / README).read_text())] + unpinned = [] + for span in spans: + for found in re.finditer(r"fastro", span): + before, after = span[: found.start()], span[found.end() :] + if after.startswith((".toml", ".version")): + continue + + if not (before.endswith("uvx ") and after.startswith("@{{ fastro.version }}")): + unpinned.append(span.strip()[:60]) + + assert unpinned == [] + assert "uvx fastro@{{ fastro.version }}" in (OVERLAY / README).read_text() def test_the_claude_file_points_at_the_agents_file(): From 0b25ea0290c2807a1a3d9ac331ad17d1e2ae706b Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Sat, 31 Oct 2026 02:49:06 -0300 Subject: [PATCH 30/71] give projects a CI workflow and pre-commit hooks that check what they carry --- blueprint/overlay/.github/workflows/ci.yml.j2 | 46 ++++++++++++ blueprint/overlay/.pre-commit-config.yaml.j2 | 46 ++++++++++++ blueprint/tests/test_overlay.py | 71 +++++++++++++++++-- 3 files changed, 156 insertions(+), 7 deletions(-) create mode 100644 blueprint/overlay/.github/workflows/ci.yml.j2 create mode 100644 blueprint/overlay/.pre-commit-config.yaml.j2 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/.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/tests/test_overlay.py b/blueprint/tests/test_overlay.py index 506e3ed7..eca3656b 100644 --- a/blueprint/tests/test_overlay.py +++ b/blueprint/tests/test_overlay.py @@ -11,6 +11,7 @@ from typing import Any import pytest +import yaml from jinja2 import Environment, FileSystemLoader, StrictUndefined, meta REPO_ROOT = Path(__file__).resolve().parents[2] @@ -30,7 +31,7 @@ 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 of `\S+` the template's own `{{ fastro.version }}` reads as one, leaving `fastro` as +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) @@ -198,26 +199,82 @@ def test_the_readme_names_the_features_a_project_selected(): assert "Selected: accounts, admin." in rendered -def test_every_fastro_command_in_the_readme_runs_the_tool_that_generated_the_project(): +@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. - Only what a reader runs is checked: `fastro.toml` is a file and `fastro.version` is a context - value, not something to run. + 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. """ - spans = [span or fenced for span, fenced in A_CODE_SPAN.findall((OVERLAY / README).read_text())] + 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.startswith((".toml", ".version")): + if after.removeprefix("\\").startswith((".toml", ".version")): continue if not (before.endswith("uvx ") and after.startswith("@{{ fastro.version }}")): unpinned.append(span.strip()[:60]) assert unpinned == [] - assert "uvx fastro@{{ fastro.version }}" in (OVERLAY / README).read_text() + + +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 `cli/` or `tools/` 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(): From b6ab6f90f398f9e975da5c3f04633e703c131078 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Sat, 31 Oct 2026 03:02:05 -0300 Subject: [PATCH 31/71] ship the admin panel switched off in the environment example --- backend/.env.example | 5 ++- backend/tests/unit/test_blueprint_catalog.py | 41 ++++++++++++++++++++ blueprint/overlay/README.md.j2 | 6 +-- blueprint/tests/test_overlay.py | 11 ++++++ docs/changelog.md | 4 ++ docs/getting-started/index.md | 2 +- docs/getting-started/installation.md | 3 +- docs/user-guide/admin-panel/configuration.md | 7 ++-- 8 files changed, 69 insertions(+), 10 deletions(-) diff --git a/backend/.env.example b/backend/.env.example index 9d28355d..2263cf62 100644 --- a/backend/.env.example +++ b/backend/.env.example @@ -286,8 +286,9 @@ PASSWORD_REQUIRE_SPECIAL=true # Admin Interface (SQLAdmin) # =================================== # @fastro if=admin -# Enable/disable the admin interface -ADMIN_ENABLED=true +# 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 diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index b2b19dad..5c1dbd9c 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -1498,6 +1498,47 @@ def test_no_marker_sits_anywhere_but_under_a_header(): 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.""" diff --git a/blueprint/overlay/README.md.j2 b/blueprint/overlay/README.md.j2 index 7126c09a..6660d50e 100644 --- a/blueprint/overlay/README.md.j2 +++ b/blueprint/overlay/README.md.j2 @@ -35,9 +35,9 @@ docker compose exec api python -m scripts.setup_initial_data ## The admin panel -`backend/.env.example` turns it on, so a copied example has it at `/admin`. Set -`ADMIN_ENABLED=false` where you don't want it, and give `ADMIN_USERNAME` and `ADMIN_PASSWORD` -values of your own before anything but your laptop can reach it. +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 diff --git a/blueprint/tests/test_overlay.py b/blueprint/tests/test_overlay.py index eca3656b..800d1fcd 100644 --- a/blueprint/tests/test_overlay.py +++ b/blueprint/tests/test_overlay.py @@ -185,6 +185,17 @@ def test_the_readme_tells_a_project_only_what_it_carries(features: tuple[str, .. 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, ()) diff --git a/docs/changelog.md b/docs/changelog.md index 29d25861..8684fe1b 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -25,6 +25,10 @@ ___ `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. ___ diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 97d17c84..f0927758 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -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..7c13a09b 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -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/user-guide/admin-panel/configuration.md b/docs/user-guide/admin-panel/configuration.md index d5d7466d..48e76706 100644 --- a/docs/user-guide/admin-panel/configuration.md +++ b/docs/user-guide/admin-panel/configuration.md @@ -222,17 +222,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 From d7c218d188a2537f6884b6319bd2aa2c2b901441 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Wed, 4 Nov 2026 17:05:23 -0300 Subject: [PATCH 32/71] name the app blueprint verify imports, and the test environment its checks run with, which holds no secrets --- backend/tests/unit/test_blueprint_catalog.py | 39 ++++++++++++++++++++ blueprint.toml | 9 +++++ 2 files changed, 48 insertions(+) diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index 5c1dbd9c..4d0872a3 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -870,6 +870,42 @@ def test_every_selection_keeps_the_files_the_drill_keeps(): assert _kept_by_the_catalog(features, chosen) == _kept_by_the_drill(manifest, chosen), sorted(chosen) +TOOLCHAIN_ONLY = {"PATH", "PYTHONPATH", "HOME"} +"""What the drill's environment holds beyond the settings: paths, not configuration.""" + + +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. These are the settings the drill sets itself + before it imports anything, and 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"] + source = inspect.getsource(_drill().check) + set_by_the_drill = set(re.findall(r'^\s+"([A-Z][A-Z0-9_]*)":', source, re.M)) - TOOLCHAIN_ONLY + + assert set(declared) == set_by_the_drill + 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" + + POINTS: dict[str, tuple[str, str]] = { "routers": ("_wiring_app", "ROUTER_MOUNTS"), "root_routers": ("_wiring_app", "ROOT_ROUTERS"), @@ -1915,6 +1951,9 @@ def test_a_collection_of_more_than_one_is_written_one_entry_to_a_line(path: str, 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} diff --git a/blueprint.toml b/blueprint.toml index 8017ce00..e288ab91 100644 --- a/blueprint.toml +++ b/blueprint.toml @@ -67,6 +67,9 @@ 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"] @@ -468,6 +471,12 @@ 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 From 00661ee9dccfab19b775c0c9b26cf0ef894a030e Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Mon, 16 Nov 2026 18:20:16 -0300 Subject: [PATCH 33/71] pin fastro at the repository root, and run its sync check in pre-commit and its sync check and blueprint lint in ci --- .github/workflows/linting.yml | 6 + .pre-commit-config.yaml | 7 + backend/tests/unit/test_blueprint_catalog.py | 238 ++++++++++++++++++- pyproject.toml | 6 + uv.lock | 22 +- 5 files changed, 271 insertions(+), 8 deletions(-) diff --git a/.github/workflows/linting.yml b/.github/workflows/linting.yml index 1291d93a..e652ba18 100644 --- a/.github/workflows/linting.yml +++ b/.github/workflows/linting.yml @@ -32,3 +32,9 @@ jobs: - name: Ruff format run: uv run --no-sync ruff format --check backend/src backend/tests backend/scripts backend/migrations cli/src cli/tests tools 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/.pre-commit-config.yaml b/.pre-commit-config.yaml index e292631c..db8dee68 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -54,6 +54,13 @@ repos: files: ^cli/src/ types: [python] + - id: fastro_sync_check + name: Wiring in sync (fastro) + language: system + entry: uv run --no-sync fastro sync --check + pass_filenames: false + files: ^(blueprint\.toml|fastro\.toml|backend/src/wiring/.*|backend/scripts/seeders\.py|backend/tests/wiring\.py)$ + - id: unit_test name: Unit test language: system diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index 4d0872a3..bf5d5947 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -1,8 +1,9 @@ """The catalog describes this repository, and `tools/removal_drill.py` is what it describes. -`blueprint.toml` is read by fastro, which isn't a dependency here yet, so nothing in this -file imports it: the rules it checks are transcribed from the catalog spec, and the facts it -checks against come from the drill, which is the repository's own account of its features. +`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 come from the drill, which is the repository's own account of +its features. This file goes when `fastro blueprint lint` and `fastro blueprint verify` replace the drill. """ @@ -31,7 +32,7 @@ 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 fastro is not a dependency yet.""" +"""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-]*$") @@ -457,11 +458,81 @@ def _workspace_members() -> list[str]: return list(tomllib.load(handle)["tool"]["uv"]["workspace"]["members"]) +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 literal head of each pre-commit `files:` pattern, which is a path in the repository.""" - patterns = re.findall(r"^\s*files: (\S+)$", (REPO_ROOT / ".pre-commit-config.yaml").read_text(), re.M) + """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"), + [ + ("^cli/src/", ["cli/src"]), + ("^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 + - return [re.split(r"[(\[{|?*+.\\]", pattern.removeprefix("^"))[0].rstrip("/") for pattern in patterns] +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]: @@ -513,6 +584,159 @@ def test_each_file_still_names_the_path_that_keeps_it_out(path: str): 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_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_hooks() -> list[dict[str, str]]: + """Each hook's keys, read from its `- id:` block, with the value written on the key's own line.""" + blocks = re.findall(r"^( *)- id: (\S+)\n((?:\1 +[\w-]+:.*\n)*)", (REPO_ROOT / ".pre-commit-config.yaml").read_text(), re.M) + + return [{"id": hook, **dict(re.findall(r"^ +([\w-]+):[ ]*(.*)$", keys, re.M))} for _, hook, keys in blocks] + + +def _the_sync_check_hook() -> dict[str, str]: + hooks = [hook for hook in _pre_commit_hooks() if "fastro sync --check" in hook.get("entry", "")] + assert len(hooks) == 1, hooks + + return hooks[0] + + +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"] == "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 + + +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", + ): + assert not re.search(_the_sync_check_hook()["files"], path), path + + +def _workflow_runs() -> list[str]: + """Every one-line `run:` in the repository's own CI.""" + return [ + run.strip() + for workflow in sorted((REPO_ROOT / ".github" / "workflows").glob("*.yml")) + for run in re.findall(r"^\s+run: (.+)$", workflow.read_text(), re.M) + ] + + +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 + + def _literals(module: Path) -> set[str]: """Every string literal in a module, less the docstrings, which talk about files rather than reach for them.""" diff --git a/pyproject.toml b/pyproject.toml index 542c7d72..88cfe6a8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -26,9 +26,15 @@ version = "0" description = "Workspace root — see backend/ and cli/ for actual packages." requires-python = ">=3.11" +[dependency-groups] +dev = ["fastro"] + [tool.uv.workspace] members = ["backend", "cli"] +[tool.uv.sources] +fastro = { git = "https://github.com/benavlabs/fastro", rev = "ddda03f1151b3233e083dd2d4354649dc997e4ec" } + [tool.pytest.ini_options] testpaths = ["blueprint/tests"] diff --git a/uv.lock b/uv.lock index ea8f91a4..f3cd0818 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'", @@ -980,6 +980,16 @@ name = "fastapi-boilerplate-workspace" version = "0" source = { virtual = "." } +[package.dev-dependencies] +dev = [ + { name = "fastro" }, +] + +[package.metadata] + +[package.metadata.requires-dev] +dev = [{ name = "fastro", git = "https://github.com/benavlabs/fastro?rev=ddda03f1151b3233e083dd2d4354649dc997e4ec" }] + [[package]] name = "fastapi-cli" version = "0.0.24" @@ -1135,6 +1145,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=ddda03f1151b3233e083dd2d4354649dc997e4ec#ddda03f1151b3233e083dd2d4354649dc997e4ec" } +dependencies = [ + { name = "jinja2" }, + { name = "packaging" }, + { name = "typer" }, +] + [[package]] name = "filelock" version = "4.2.4" From 4bfe979b030e33318365df4174e526c13265b499 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Mon, 16 Nov 2026 19:35:58 -0300 Subject: [PATCH 34/71] run the sync check when a commit moves the fastro pin, since another fastro can render the catalog differently --- .pre-commit-config.yaml | 2 +- backend/tests/unit/test_blueprint_catalog.py | 12 ++++++++++++ 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index db8dee68..fe2ac28a 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -59,7 +59,7 @@ repos: language: system entry: uv run --no-sync fastro sync --check pass_filenames: false - files: ^(blueprint\.toml|fastro\.toml|backend/src/wiring/.*|backend/scripts/seeders\.py|backend/tests/wiring\.py)$ + 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/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index bf5d5947..76fc073d 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -658,12 +658,24 @@ def test_a_commit_that_touches_what_sync_compares_runs_sync_check(path: str): 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 From d811716367c9f77d011b21e5a764c223abf1fab1 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Mon, 16 Nov 2026 20:23:57 -0300 Subject: [PATCH 35/71] say in the contributing guide that syncing installs fastro, that a commit runs its sync check and how to fix it, and which uv wrote the lock --- CONTRIBUTING.md | 6 ++ backend/tests/unit/test_blueprint_catalog.py | 100 +++++++++++++++++++ blueprint/tests/test_fastro.py | 45 +++++++++ 3 files changed, 151 insertions(+) create mode 100644 blueprint/tests/test_fastro.py diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 03de15b1..d229a78d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,6 +27,11 @@ 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. +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 uv creates a virtual environment for your project. Activate it using: @@ -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/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index 76fc073d..b8b2e9ea 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -749,6 +749,106 @@ def test_ci_runs_fastros_checks_where_fastro_is_installed(command: str): 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 test_the_contributing_guide_is_the_blueprint_s_own(): + assert _withheld("CONTRIBUTING.md") + + +def test_the_sync_the_contributing_guide_gives_installs_fastro(): + """The guide says the sync brings fastro in, so the sync it gives keeps the root dev group.""" + assert _contributing_syncs() + for sync in _contributing_syncs(): + assert set(sync.split()) <= SYNC_THAT_KEEPS_THE_DEV_GROUP, sync + assert re.search(r"The sync also installs fastro\b", CONTRIBUTING.read_text()) + + +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 re.search(rf"pins fastro to one commit in its `{groups[0]}`\s+group\.", 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"lock\s+revision\s+{revision}\b", text) + assert re.search(rf"uv\s+{re.escape(UV_THAT_WROTE_THE_LOCK[revision])}\s+or\s+newer\b", text) + assert set(re.findall(r"\buv\s+(\d+\.\d+\.\d+)", text)) == {UV_THAT_WROTE_THE_LOCK[revision]} + + +def _the_guide_s_sentences() -> list[str]: + return re.split(r"(?<=\.)\s+", CONTRIBUTING.read_text()) + + +def _the_guide_s_sync_check_sentence() -> str: + hook = f"`{_the_sync_check_hook()['entry']}`" + sentences = [sentence for sentence in _the_guide_s_sentences() 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/` proves the check fails on wiring that differs from what fastro generates.""" + hook = f"`{_the_sync_check_hook()['entry']}`" + + assert re.search( + rf"{re.escape(hook)},\s+which\s+fails\s+when\s+the\s+wiring\s+in\s+the\s+commit\s+differs\b", + _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 by what it is, each one the hook runs on.""" + sentence = _the_guide_s_sync_check_sentence() + named = set(re.findall(r"`([\w.]+\.(?:toml|lock))`", sentence)) + + assert named == {"blueprint.toml", "fastro.toml", "pyproject.toml", "uv.lock"} + for path in named: + assert re.search(_the_sync_check_hook()["files"], path), path + assert re.search(r"\ba wiring file fastro generates\b", sentence) + + +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 = set(re.findall(r"`([\w.]+\.(?:toml|lock))`", _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(): + """Right after the check, and `blueprint/tests/` proves the command regenerates what the check compares.""" + sentences = _the_guide_s_sentences() + following = sentences[sentences.index(_the_guide_s_sync_check_sentence()) + 1] + + assert following.rstrip() == "Run `uv run --no-sync fastro sync` to regenerate the wiring, then commit the result.", ( + following + ) + + def _literals(module: Path) -> set[str]: """Every string literal in a module, less the docstrings, which talk about files rather than reach for them.""" diff --git a/blueprint/tests/test_fastro.py b/blueprint/tests/test_fastro.py new file mode 100644 index 00000000..37e2fa76 --- /dev/null +++ b/blueprint/tests/test_fastro.py @@ -0,0 +1,45 @@ +"""What the fastro the repository root installs gives the people who work on the blueprint.""" + +import shutil +import subprocess +import sys +import tomllib +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parents[2] + + +def _fastro(*arguments: str, cwd: Path) -> subprocess.CompletedProcess[str]: + return subprocess.run([sys.executable, "-m", "fastro", *arguments], cwd=cwd, capture_output=True, text=True, check=False) + + +def _tree(destination: Path) -> Path: + 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 + + +def test_plain_sync_regenerates_what_the_check_compares(tmp_path: Path): + """CONTRIBUTING.md sends a failed `fastro sync --check` to `fastro sync`.""" + tree = _tree(tmp_path / "blueprint") + 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 From 93a3e164adf5469fa917263fd566ad6de9660a5a Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Mon, 16 Nov 2026 20:31:17 -0300 Subject: [PATCH 36/71] test the facts the contributing guide states about fastro, not its wording --- backend/tests/unit/test_blueprint_catalog.py | 37 ++++++-------------- 1 file changed, 11 insertions(+), 26 deletions(-) diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index b8b2e9ea..6cea6447 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -765,11 +765,10 @@ def test_the_contributing_guide_is_the_blueprint_s_own(): def test_the_sync_the_contributing_guide_gives_installs_fastro(): - """The guide says the sync brings fastro in, so the sync it gives keeps the root dev group.""" + """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 - assert re.search(r"The sync also installs fastro\b", CONTRIBUTING.read_text()) def test_the_contributing_guide_names_the_group_that_pins_fastro(): @@ -780,7 +779,7 @@ def test_the_contributing_guide_names_the_group_that_pins_fastro(): ] assert len(groups) == 1, groups - assert re.search(rf"pins fastro to one commit in its `{groups[0]}`\s+group\.", CONTRIBUTING.read_text()) + assert f"`{groups[0]}`" in CONTRIBUTING.read_text() def test_the_contributing_guide_names_the_uv_that_wrote_the_lock(): @@ -790,42 +789,33 @@ def test_the_contributing_guide_names_the_uv_that_wrote_the_lock(): 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"lock\s+revision\s+{revision}\b", text) - assert re.search(rf"uv\s+{re.escape(UV_THAT_WROTE_THE_LOCK[revision])}\s+or\s+newer\b", 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]} - - -def _the_guide_s_sentences() -> list[str]: - return re.split(r"(?<=\.)\s+", CONTRIBUTING.read_text()) + 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 _the_guide_s_sentences() if hook in sentence] + 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/` proves the check fails on wiring that differs from what fastro generates.""" - hook = f"`{_the_sync_check_hook()['entry']}`" - - assert re.search( - rf"{re.escape(hook)},\s+which\s+fails\s+when\s+the\s+wiring\s+in\s+the\s+commit\s+differs\b", - _the_guide_s_sync_check_sentence(), - ) + """`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 by what it is, each one the hook runs on.""" + """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() named = set(re.findall(r"`([\w.]+\.(?:toml|lock))`", sentence)) assert named == {"blueprint.toml", "fastro.toml", "pyproject.toml", "uv.lock"} for path in named: assert re.search(_the_sync_check_hook()["files"], path), path - assert re.search(r"\ba wiring file fastro generates\b", 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(): @@ -840,13 +830,8 @@ def test_the_check_runs_on_no_file_the_contributing_guide_leaves_out(): def test_the_contributing_guide_names_the_command_that_fixes_a_failed_check(): - """Right after the check, and `blueprint/tests/` proves the command regenerates what the check compares.""" - sentences = _the_guide_s_sentences() - following = sentences[sentences.index(_the_guide_s_sync_check_sentence()) + 1] - - assert following.rstrip() == "Run `uv run --no-sync fastro sync` to regenerate the wiring, then commit the result.", ( - following - ) + """`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]: From bfe285fba586f30889ea90b1484af899f40049b1 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Mon, 16 Nov 2026 20:58:09 -0300 Subject: [PATCH 37/71] name the sync check hook in the development guide's hook table, and test the table against the config --- backend/tests/unit/test_blueprint_catalog.py | 92 ++++++++++++++++++-- docs/user-guide/development.md | 1 + 2 files changed, 88 insertions(+), 5 deletions(-) diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index 6cea6447..8d78f0fc 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -638,6 +638,21 @@ def _the_sync_check_hook() -> dict[str, str]: 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() @@ -680,6 +695,76 @@ def test_a_commit_that_touches_nothing_sync_compares_skips_sync_check(): assert not re.search(_the_sync_check_hook()["files"], path), path +HYGIENE_HOOKS_REPOSITORY = "https://github.com/pre-commit/pre-commit-hooks" +"""The repository whose hooks the development guide's table names together, as its hygiene hooks.""" + + +def _hook_repositories() -> dict[str, str]: + """Each hook id in `.pre-commit-config.yaml`, with the repository it comes from.""" + text = (REPO_ROOT / ".pre-commit-config.yaml").read_text() + + return { + hook: repository + for repository, block in re.findall(r"^ - repo: (\S+)\n((?:(?! - repo: ).*\n)*)", text, re.M) + for hook in re.findall(r"^ *- id: ([\w-]+)", block, re.M) + } + + +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.""" + section = (REPO_ROOT / "docs" / "user-guide" / "development.md").read_text().split("## Pre-Commit", 1)[1] + rows = re.findall(r"^\| (?!Hook\b|-)(.+?) \| (.+) \|$", section.split("\n\n## ", 1)[0], 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(): + rows = _development_guide_hook_rows() + assert _hook_repositories() + + for hook, repository in _hook_repositories().items(): + assert hook in rows or (repository == HYGIENE_HOOKS_REPOSITORY and "hygiene hooks" in rows), hook + + +def test_the_development_guide_names_no_hook_the_config_lacks(): + rows = _development_guide_hook_rows() + + assert set(rows) - {"hygiene hooks"} <= set(_hook_repositories()) + if "hygiene hooks" in rows: + assert HYGIENE_HOOKS_REPOSITORY in _hook_repositories().values() + + +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 _workflow_runs() -> list[str]: """Every one-line `run:` in the repository's own CI.""" return [ @@ -810,17 +895,14 @@ def test_the_contributing_guide_names_the_check_a_commit_runs(): 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() - named = set(re.findall(r"`([\w.]+\.(?:toml|lock))`", sentence)) - assert named == {"blueprint.toml", "fastro.toml", "pyproject.toml", "uv.lock"} - for path in named: - assert re.search(_the_sync_check_hook()["files"], path), path + _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 = set(re.findall(r"`([\w.]+\.(?:toml|lock))`", _the_guide_s_sync_check_sentence())) + 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"]): diff --git a/docs/user-guide/development.md b/docs/user-guide/development.md index 25c0e10b..04154340 100644 --- a/docs/user-guide/development.md +++ b/docs/user-guide/development.md @@ -104,6 +104,7 @@ The repo's `.pre-commit-config.yaml` runs what CI runs, and nothing that fights | `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 | +| `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` | | `unit_test` | local, manual stage: `pytest tests/unit` | `unit_test` runs the unit tests only — they need no container and finish in seconds. The From 6739d4d42815e89601ea20a0cf40f60bb5d32391 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Mon, 16 Nov 2026 21:58:17 -0300 Subject: [PATCH 38/71] say in the readme that the quickstart sync installs fastro, and hold every readme sync to the flags that keep the root dev group --- README.md | 2 +- backend/tests/unit/test_blueprint_catalog.py | 10 ++++++++++ 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d0af0a05..f72f94ec 100644 --- a/README.md +++ b/README.md @@ -126,7 +126,7 @@ 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: both members, plus fastro ``` Generate a compose file for the deployment shape you want: diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index 8d78f0fc..fb5da387 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -856,6 +856,16 @@ def test_the_sync_the_contributing_guide_gives_installs_fastro(): 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 From 5bce23c2d335fe92cf43736767734e1f88121fdc Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Mon, 16 Nov 2026 22:06:52 -0300 Subject: [PATCH 39/71] name every hook and the unit test hook's command and directory in the development guide's hook table, and test that the hooks it says ci runs run what ci runs --- backend/tests/unit/test_blueprint_catalog.py | 44 ++++++++++++++------ docs/user-guide/development.md | 4 +- 2 files changed, 33 insertions(+), 15 deletions(-) diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index fb5da387..c9735a19 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -695,10 +695,6 @@ def test_a_commit_that_touches_nothing_sync_compares_skips_sync_check(): assert not re.search(_the_sync_check_hook()["files"], path), path -HYGIENE_HOOKS_REPOSITORY = "https://github.com/pre-commit/pre-commit-hooks" -"""The repository whose hooks the development guide's table names together, as its hygiene hooks.""" - - def _hook_repositories() -> dict[str, str]: """Each hook id in `.pre-commit-config.yaml`, with the repository it comes from.""" text = (REPO_ROOT / ".pre-commit-config.yaml").read_text() @@ -726,19 +722,12 @@ def _development_guide_hook_rows() -> dict[str, str]: def test_the_development_guide_names_every_hook_a_commit_runs(): - rows = _development_guide_hook_rows() assert _hook_repositories() - - for hook, repository in _hook_repositories().items(): - assert hook in rows or (repository == HYGIENE_HOOKS_REPOSITORY and "hygiene hooks" in rows), hook + assert set(_hook_repositories()) <= set(_development_guide_hook_rows()) def test_the_development_guide_names_no_hook_the_config_lacks(): - rows = _development_guide_hook_rows() - - assert set(rows) - {"hygiene hooks"} <= set(_hook_repositories()) - if "hygiene hooks" in rows: - assert HYGIENE_HOOKS_REPOSITORY in _hook_repositories().values() + assert set(_development_guide_hook_rows()) <= set(_hook_repositories()) def test_the_development_guide_says_which_hooks_are_local(): @@ -765,6 +754,35 @@ def test_the_development_guide_gives_the_command_the_sync_check_hook_runs(): 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 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 "entry" in hook and re.search(r"\bCI\b", rows.get(hook["id"], ""))] + + assert claimed + for hook in claimed: + assert _hook_shell_line(hook) in _workflow_runs(), hook["id"] + + +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 _workflow_runs() -> list[str]: """Every one-line `run:` in the repository's own CI.""" return [ diff --git a/docs/user-guide/development.md b/docs/user-guide/development.md index 04154340..762e545e 100644 --- a/docs/user-guide/development.md +++ b/docs/user-guide/development.md @@ -102,10 +102,10 @@ The repo's `.pre-commit-config.yaml` runs what CI runs, and nothing that fights | `ruff-check --fix`, `ruff-format` | the same lint and format CI checks | | `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 | +| `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`, `mypy_cli` | local hooks, the same invocations 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` | -| `unit_test` | local, manual stage: `pytest tests/unit` | +| `unit_test` | local, manual stage: `uv run --no-sync pytest tests/unit` 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 From 33a0e730d7cc512b3f7690c1e3f995b9427f391a Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Mon, 16 Nov 2026 22:24:48 -0300 Subject: [PATCH 40/71] say in each row of the development guide's hook table whether ci runs it, and test the claim both ways against the workflows --- backend/tests/unit/test_blueprint_catalog.py | 40 +++++++++++++++++++- docs/user-guide/development.md | 8 ++-- 2 files changed, 42 insertions(+), 6 deletions(-) diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index c9735a19..60c866e1 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -761,13 +761,49 @@ def _hook_shell_line(hook: dict[str, str]) -> str: 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 re.sub(r"(?: [\w.-]*[/.][\w./-]*)+$", "", line) in _workflow_runs() + + 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 "entry" in hook and re.search(r"\bCI\b", rows.get(hook["id"], ""))] + claimed = [hook for hook in _pre_commit_hooks() if _names_ci(rows[hook["id"]])] assert claimed for hook in claimed: - assert _hook_shell_line(hook) in _workflow_runs(), hook["id"] + 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(): diff --git a/docs/user-guide/development.md b/docs/user-guide/development.md index 762e545e..453fc750 100644 --- a/docs/user-guide/development.md +++ b/docs/user-guide/development.md @@ -95,17 +95,17 @@ 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 | | `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`, `mypy_cli` | local hooks, the same invocations 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` | -| `unit_test` | local, manual stage: `uv run --no-sync pytest tests/unit` in `backend/` | +| `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 From cb28fe03d61f5c5ee9b3fe581964b4fdb6b156fc Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Mon, 16 Nov 2026 22:57:47 -0300 Subject: [PATCH 41/71] correct the development guide's claim that the unit tests need no container, and test each fact its pre-commit prose states past the hook table --- backend/tests/unit/test_blueprint_catalog.py | 121 ++++++++++++++++++- docs/user-guide/development.md | 12 +- 2 files changed, 125 insertions(+), 8 deletions(-) diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index 60c866e1..dc613343 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -17,6 +17,7 @@ import itertools import keyword import re +import subprocess import sys import tomllib from collections.abc import Iterable @@ -26,6 +27,8 @@ import pytest +from tests.conftest import is_docker_running + REPO_ROOT = Path(__file__).resolve().parents[3] CATALOG = REPO_ROOT / "blueprint.toml" @@ -706,10 +709,15 @@ def _hook_repositories() -> dict[str, str]: } +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.""" - section = (REPO_ROOT / "docs" / "user-guide" / "development.md").read_text().split("## Pre-Commit", 1)[1] - rows = re.findall(r"^\| (?!Hook\b|-)(.+?) \| (.+) \|$", section.split("\n\n## ", 1)[0], re.M) + rows = re.findall(r"^\| (?!Hook\b|-)(.+?) \| (.+) \|$", _development_guide_pre_commit_section(), re.M) named = [ (name, cells) @@ -819,6 +827,115 @@ def test_the_development_guide_gives_the_command_each_manual_hook_runs_and_where 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 _modules_imported_anywhere(path: Path) -> set[str]: + """Each module a file imports, at its top or inside a function, a block or a fixture.""" + modules = set() + for node in ast.walk(ast.parse(path.read_text())): + if isinstance(node, ast.ImportFrom) and node.module: + modules.add(node.module) + elif isinstance(node, ast.Import): + modules.update(alias.name for alias in node.names) + + return modules + + +def test_every_test_that_starts_a_container_skips_without_docker(): + """What the development guide means when it says the unit test hook passes without Docker.""" + tests = REPO_ROOT / "backend" / "tests" + starting = [ + path + for path in sorted(tests.rglob("*.py")) + if any(re.fullmatch(r"testcontainers(?:\..+)?", module) for module in _modules_imported_anywhere(path)) + ] + + assert "`testcontainers`" in _development_guide_pre_commit_prose() + assert any(path.is_relative_to(tests / "unit") for path in starting) + for path in starting: + assert re.search(r"if not is_docker_running\(\):\n\s+pytest\.skip\(", path.read_text()), path + + +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]") == f"[{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]: """Every one-line `run:` in the repository's own CI.""" return [ diff --git a/docs/user-guide/development.md b/docs/user-guide/development.md index 453fc750..12a2cf5e 100644 --- a/docs/user-guide/development.md +++ b/docs/user-guide/development.md @@ -107,17 +107,17 @@ The repo's `.pre-commit-config.yaml` runs these hooks. A row that names CI says | `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: From c270f3cf8fd97c81aa54a217e0b1a86f1f33978f Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Mon, 16 Nov 2026 23:25:48 -0300 Subject: [PATCH 42/71] check that the unit test hook passes without docker by running it against an unreachable docker host, in place of the per-file guard check --- backend/tests/unit/test_blueprint_catalog.py | 32 +++++------------ blueprint/tests/test_pre_commit.py | 38 ++++++++++++++++++++ 2 files changed, 47 insertions(+), 23 deletions(-) create mode 100644 blueprint/tests/test_pre_commit.py diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index dc613343..40d2db89 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -832,31 +832,17 @@ def _development_guide_pre_commit_prose() -> str: return _development_guide_pre_commit_section().rsplit("\n|", 1)[1].split("\n", 1)[1] -def _modules_imported_anywhere(path: Path) -> set[str]: - """Each module a file imports, at its top or inside a function, a block or a fixture.""" - modules = set() - for node in ast.walk(ast.parse(path.read_text())): - if isinstance(node, ast.ImportFrom) and node.module: - modules.add(node.module) - elif isinstance(node, ast.Import): - modules.update(alias.name for alias in node.names) - - return modules - - -def test_every_test_that_starts_a_container_skips_without_docker(): - """What the development guide means when it says the unit test hook passes without Docker.""" - tests = REPO_ROOT / "backend" / "tests" - starting = [ - path - for path in sorted(tests.rglob("*.py")) - if any(re.fullmatch(r"testcontainers(?:\..+)?", module) for module in _modules_imported_anywhere(path)) - ] +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(path.is_relative_to(tests / "unit") for path in starting) - for path in starting: - assert re.search(r"if not is_docker_running\(\):\n\s+pytest\.skip\(", path.read_text()), path + 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): 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:] From a66c494e5dc7e87f0abe3a0619277a2f5c1cabde Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Tue, 17 Nov 2026 00:34:48 -0300 Subject: [PATCH 43/71] read the pre-commit config and the workflows in the catalog tests with yaml.safe_load instead of regexes, and add pyyaml and types-pyyaml to the root dev group --- backend/tests/unit/test_blueprint_catalog.py | 93 +++++++++++++++----- pyproject.toml | 2 +- uv.lock | 17 +++- 3 files changed, 89 insertions(+), 23 deletions(-) diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index 40d2db89..0a7ca7a9 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -26,6 +26,7 @@ from typing import Any import pytest +import yaml from tests.conftest import is_docker_running @@ -627,14 +628,42 @@ def test_no_project_receives_the_fastro_pin(): assert "fastro" not in backend.get("tool", {}).get("uv", {}).get("sources", {}) -def _pre_commit_hooks() -> list[dict[str, str]]: - """Each hook's keys, read from its `- id:` block, with the value written on the key's own line.""" - blocks = re.findall(r"^( *)- id: (\S+)\n((?:\1 +[\w-]+:.*\n)*)", (REPO_ROOT / ".pre-commit-config.yaml").read_text(), re.M) +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 [{"id": hook, **dict(re.findall(r"^ +([\w-]+):[ ]*(.*)$", keys, re.M))} for _, hook, keys in blocks] + return repositories -def _the_sync_check_hook() -> dict[str, str]: +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 @@ -662,7 +691,7 @@ def test_a_commit_runs_sync_check_on_the_whole_tree(): assert hook["entry"] == "uv run --no-sync fastro sync --check" assert hook["language"] == "system" - assert hook["pass_filenames"] == "false" + assert hook["pass_filenames"] is False def test_the_sync_check_hook_runs_at_every_commit(): @@ -700,13 +729,7 @@ def test_a_commit_that_touches_nothing_sync_compares_skips_sync_check(): def _hook_repositories() -> dict[str, str]: """Each hook id in `.pre-commit-config.yaml`, with the repository it comes from.""" - text = (REPO_ROOT / ".pre-commit-config.yaml").read_text() - - return { - hook: repository - for repository, block in re.findall(r"^ - repo: (\S+)\n((?:(?! - repo: ).*\n)*)", text, re.M) - for hook in re.findall(r"^ *- id: ([\w-]+)", block, re.M) - } + return {hook["id"]: repository["repo"] for repository in _pre_commit_repositories() for hook in repository["hooks"]} def _development_guide_pre_commit_section() -> str: @@ -747,7 +770,7 @@ def test_the_development_guide_says_which_hooks_are_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]"} + 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 @@ -815,7 +838,7 @@ def test_the_hooks_the_development_guide_leaves_ci_out_of_are_no_ci_step(): 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]"] + manual = [hook for hook in _pre_commit_hooks() if hook.get("stages") == ["manual"]] assert manual for hook in manual: @@ -902,7 +925,7 @@ def test_each_hook_the_development_guide_runs_by_name_is_in_the_config_at_the_st 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]") == f"[{stage[1] if stage else 'pre-commit'}]", hook + 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(): @@ -922,15 +945,43 @@ def test_each_pre_commit_command_the_development_guide_gives_takes_the_flags_it_ assert re.search(rf"(? list[str]: - """Every one-line `run:` in the repository's own CI.""" +def _workflow_runs(workflows: Iterable[str] | None = None) -> 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 [ - run.strip() - for workflow in sorted((REPO_ROOT / ".github" / "workflows").glob("*.yml")) - for run in re.findall(r"^\s+run: (.+)$", workflow.read_text(), re.M) + 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 _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() diff --git a/pyproject.toml b/pyproject.toml index 88cfe6a8..8d55164c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -27,7 +27,7 @@ description = "Workspace root — see backend/ and cli/ for actual packages." requires-python = ">=3.11" [dependency-groups] -dev = ["fastro"] +dev = ["fastro", "pyyaml>=6.0.2", "types-pyyaml>=6.0.12"] [tool.uv.workspace] members = ["backend", "cli"] diff --git a/uv.lock b/uv.lock index f3cd0818..c79544cf 100644 --- a/uv.lock +++ b/uv.lock @@ -983,12 +983,18 @@ source = { virtual = "." } [package.dev-dependencies] dev = [ { name = "fastro" }, + { name = "pyyaml" }, + { name = "types-pyyaml" }, ] [package.metadata] [package.metadata.requires-dev] -dev = [{ name = "fastro", git = "https://github.com/benavlabs/fastro?rev=ddda03f1151b3233e083dd2d4354649dc997e4ec" }] +dev = [ + { name = "fastro", git = "https://github.com/benavlabs/fastro?rev=ddda03f1151b3233e083dd2d4354649dc997e4ec" }, + { name = "pyyaml", specifier = ">=6.0.2" }, + { name = "types-pyyaml", specifier = ">=6.0.12" }, +] [[package]] name = "fastapi-cli" @@ -2797,6 +2803,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" From 44679a6b3e5bb300cb52c5d373eb30f12b4bdd1d Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Tue, 17 Nov 2026 01:01:58 -0300 Subject: [PATCH 44/71] remove the left-out path filters from the docs tests, which only run in the full repo, test that every test reading the docs or importing a withheld test stays in blueprint_only, and draw the diagram's sets from verify.sets --- backend/tests/unit/test_blueprint_catalog.py | 34 ++++++++++++ backend/tests/unit/test_docs_imports.py | 55 ++------------------ backend/tests/unit/test_docs_wiring.py | 24 ++++----- backend/tests/unit/test_image_contents.py | 18 +------ 4 files changed, 48 insertions(+), 83 deletions(-) diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index 0a7ca7a9..a1434ba6 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -1053,6 +1053,40 @@ def _contributing_syncs() -> list[str]: 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") diff --git a/backend/tests/unit/test_docs_imports.py b/backend/tests/unit/test_docs_imports.py index 5516fb52..874e1ec2 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) @@ -37,41 +33,6 @@ ) -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 +64,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 +83,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 +120,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 +142,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_wiring.py b/backend/tests/unit/test_docs_wiring.py index ee5ef6c3..85fbd3b8 100644 --- a/backend/tests/unit/test_docs_wiring.py +++ b/backend/tests/unit/test_docs_wiring.py @@ -7,10 +7,9 @@ """ import re +import tomllib from pathlib import Path -from tests.unit.test_docs_imports import LEFT_OUT_PATHS - REPO_ROOT = Path(__file__).resolve().parents[3] WIRING = REPO_ROOT / "backend" / "src" / "wiring" STRUCTURE = REPO_ROOT / "docs" / "user-guide" / "project-structure.md" @@ -21,12 +20,7 @@ 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 +59,11 @@ 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.""" + with (REPO_ROOT / "blueprint.toml").open("rb") as handle: + sets = tomllib.load(handle)["verify"]["sets"] + drawn = set(re.findall(r">([a-z0-9-]+)", DIAGRAMS.read_text())) - assert presets, "no presets found in the drill" - assert [preset for preset in presets if "-" in preset and preset not in drawn] == [] + assert sets + assert [name for name in sets if name not in drawn] == [] 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()] == [] From d5b74fb38d2db424f450dda088a8a36a11f598a9 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Tue, 17 Nov 2026 02:00:38 -0300 Subject: [PATCH 45/71] cap fastapi below 0.140.7, the first release the app can't import, and test that every fastapi a project could install is one the app imports --- backend/pyproject.toml | 2 +- backend/tests/unit/test_blueprint_catalog.py | 24 ++++++++++++++++++++ blueprint.toml | 2 +- docs/changelog.md | 5 ++++ pyproject.toml | 2 +- uv.lock | 4 +++- 6 files changed, 35 insertions(+), 4 deletions(-) diff --git a/backend/pyproject.toml b/backend/pyproject.toml index f26c53ea..27fad392 100644 --- a/backend/pyproject.toml +++ b/backend/pyproject.toml @@ -17,7 +17,7 @@ dependencies = [ "asyncpg>=0.30.0", "crudauth[all]>=0.8.2,<0.9.0", "cryptography>=42.0.0", - "fastapi[standard]>=0.115.8", + "fastapi[standard]>=0.115.8,<0.140.7", "fastcrud>=0.21.0", "greenlet>=3.1.1", "itsdangerous>=2.2.0", diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index a1434ba6..aa898ce1 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -27,6 +27,7 @@ import pytest import yaml +from packaging.requirements import Requirement from tests.conftest import is_docker_running @@ -117,6 +118,29 @@ def test_the_dependencies_a_project_could_install_are_the_ones_the_backend_decla 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("_", "-") diff --git a/blueprint.toml b/blueprint.toml index e288ab91..7d3bafcc 100644 --- a/blueprint.toml +++ b/blueprint.toml @@ -39,7 +39,7 @@ runtime = [ "anyio>=4.15.1", "asyncpg>=0.30.0", "crudauth[all]>=0.8.2,<0.9.0", - "fastapi[standard]>=0.115.8", + "fastapi[standard]>=0.115.8,<0.140.7", "fastcrud>=0.21.0", "greenlet>=3.1.1", "pydantic>=2.10.6", diff --git a/docs/changelog.md b/docs/changelog.md index 8684fe1b..58fceec9 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -12,6 +12,11 @@ ___ #### Changed +- **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 diff --git a/pyproject.toml b/pyproject.toml index 8d55164c..0ffcd34e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -27,7 +27,7 @@ description = "Workspace root — see backend/ and cli/ for actual packages." requires-python = ">=3.11" [dependency-groups] -dev = ["fastro", "pyyaml>=6.0.2", "types-pyyaml>=6.0.12"] +dev = ["fastro", "packaging>=24.0", "pyyaml>=6.0.2", "types-pyyaml>=6.0.12"] [tool.uv.workspace] members = ["backend", "cli"] diff --git a/uv.lock b/uv.lock index c79544cf..07f11706 100644 --- a/uv.lock +++ b/uv.lock @@ -921,7 +921,7 @@ requires-dist = [ { name = "crudauth", extras = ["all"], specifier = ">=0.8.2,<0.9.0" }, { name = "cryptography", specifier = ">=42.0.0" }, { name = "faker", marker = "extra == 'dev'", specifier = ">=37.1.0" }, - { name = "fastapi", extras = ["standard"], specifier = ">=0.115.8" }, + { 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", marker = "extra == 'dev'", specifier = ">=0.28.1" }, @@ -983,6 +983,7 @@ source = { virtual = "." } [package.dev-dependencies] dev = [ { name = "fastro" }, + { name = "packaging" }, { name = "pyyaml" }, { name = "types-pyyaml" }, ] @@ -992,6 +993,7 @@ dev = [ [package.metadata.requires-dev] dev = [ { name = "fastro", git = "https://github.com/benavlabs/fastro?rev=ddda03f1151b3233e083dd2d4354649dc997e4ec" }, + { name = "packaging", specifier = ">=24.0" }, { name = "pyyaml", specifier = ">=6.0.2" }, { name = "types-pyyaml", specifier = ">=6.0.12" }, ] From 37633accb18f9201f3873d8c526560361c6a89ec Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Tue, 17 Nov 2026 02:16:39 -0300 Subject: [PATCH 46/71] register the tracing recipe's installer under fastro.toml's app contributions and run fastro sync, have install configure tracing itself, and replace the drill's tracing tests with a blueprint test that follows the recipe in a copy --- backend/tests/unit/test_docs_imports.py | 1 - backend/tests/unit/test_removal_drill.py | 21 ----- blueprint/tests/conftest.py | 42 +++++++++ blueprint/tests/test_fastro.py | 36 ++------ blueprint/tests/test_observability_recipe.py | 95 ++++++++++++++++++++ docs/changelog.md | 5 ++ docs/user-guide/observability.md | 42 ++++----- 7 files changed, 168 insertions(+), 74 deletions(-) create mode 100644 blueprint/tests/conftest.py create mode 100644 blueprint/tests/test_observability_recipe.py diff --git a/backend/tests/unit/test_docs_imports.py b/backend/tests/unit/test_docs_imports.py index 874e1ec2..22c5104a 100644 --- a/backend/tests/unit/test_docs_imports.py +++ b/backend/tests/unit/test_docs_imports.py @@ -29,7 +29,6 @@ "src.modules.reports", "src.modules.user.routes_v2", "src.interfaces.api.v2", - "src.infrastructure.observability", ) diff --git a/backend/tests/unit/test_removal_drill.py b/backend/tests/unit/test_removal_drill.py index eb3bce9d..0a9f52a2 100644 --- a/backend/tests/unit/test_removal_drill.py +++ b/backend/tests/unit/test_removal_drill.py @@ -254,24 +254,3 @@ def test_the_generator_rebuilds_what_this_project_committed(): 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/blueprint/tests/conftest.py b/blueprint/tests/conftest.py new file mode 100644 index 00000000..deb38cfb --- /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] + +Fastro = 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() -> Fastro: + """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/test_fastro.py b/blueprint/tests/test_fastro.py index 37e2fa76..4ea1dcd0 100644 --- a/blueprint/tests/test_fastro.py +++ b/blueprint/tests/test_fastro.py @@ -1,45 +1,23 @@ """What the fastro the repository root installs gives the people who work on the blueprint.""" -import shutil -import subprocess -import sys import tomllib from pathlib import Path -REPO_ROOT = Path(__file__).resolve().parents[2] - - -def _fastro(*arguments: str, cwd: Path) -> subprocess.CompletedProcess[str]: - return subprocess.run([sys.executable, "-m", "fastro", *arguments], cwd=cwd, capture_output=True, text=True, check=False) +from conftest import Fastro - -def _tree(destination: Path) -> Path: - 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 +REPO_ROOT = Path(__file__).resolve().parents[2] -def test_plain_sync_regenerates_what_the_check_compares(tmp_path: Path): +def test_plain_sync_regenerates_what_the_check_compares(tracked_tree: Path, fastro: Fastro): """CONTRIBUTING.md sends a failed `fastro sync --check` to `fastro sync`.""" - tree = _tree(tmp_path / "blueprint") + 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 + assert fastro("sync", "--check", cwd=tree).returncode == 1 - synced = _fastro("sync", cwd=tree) + synced = fastro("sync", cwd=tree) assert synced.returncode == 0, synced.stderr - assert _fastro("sync", "--check", cwd=tree).returncode == 0 + assert fastro("sync", "--check", cwd=tree).returncode == 0 diff --git a/blueprint/tests/test_observability_recipe.py b/blueprint/tests/test_observability_recipe.py new file mode 100644 index 00000000..be4fd69c --- /dev/null +++ b/blueprint/tests/test_observability_recipe.py @@ -0,0 +1,95 @@ +"""The observability guide's tracing recipe, followed in a copy of the repository.""" + +import ast +import re +import tomllib +from pathlib import Path + +from conftest import Fastro + +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: Fastro): + 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 diff --git a/docs/changelog.md b/docs/changelog.md index 58fceec9..c79176b7 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -12,6 +12,11 @@ ___ #### Changed +- **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 diff --git a/docs/user-guide/observability.md b/docs/user-guide/observability.md index ee96e657..75cc9534 100644 --- a/docs/user-guide/observability.md +++ b/docs/user-guide/observability.md @@ -59,33 +59,29 @@ 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. `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 @@ -162,8 +158,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` | --- From b03038b4bb3df29478c0e46a0a9ba64632cce12d Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Tue, 17 Nov 2026 02:28:07 -0300 Subject: [PATCH 47/71] say in the observability guide how a generated project adds the tracing installer until fastro syncs projects, test that the pinned fastro still can't, and test the worker note and the feature section --- blueprint/tests/test_observability_recipe.py | 89 ++++++++++++++++++++ docs/user-guide/observability.md | 25 ++++-- 2 files changed, 105 insertions(+), 9 deletions(-) diff --git a/blueprint/tests/test_observability_recipe.py b/blueprint/tests/test_observability_recipe.py index be4fd69c..e9148f5b 100644 --- a/blueprint/tests/test_observability_recipe.py +++ b/blueprint/tests/test_observability_recipe.py @@ -5,6 +5,7 @@ import tomllib from pathlib import Path +import pytest from conftest import Fastro REPO_ROOT = Path(__file__).resolve().parents[2] @@ -93,3 +94,91 @@ def test_the_installer_configures_tracing_before_it_instruments_the_app(): 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: Fastro, 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 "tools/removal_drill.py" not in section + 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/docs/user-guide/observability.md b/docs/user-guide/observability.md index 75cc9534..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, @@ -83,6 +83,12 @@ installers, and the app calls it as it's built. Don't write it into `src/wiring/ 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 project follows — a setting that enables something is off when unset. `LOGFIRE_TOKEN`, @@ -91,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 @@ -144,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 From b8817f15ca843ac0118936ab720a6bb25d20b15d Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Tue, 17 Nov 2026 02:31:45 -0300 Subject: [PATCH 48/71] hold the overlay test's loader in a variable and call get_source on it, so mypy no longer sees an optional loader --- blueprint/tests/test_overlay.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/blueprint/tests/test_overlay.py b/blueprint/tests/test_overlay.py index 800d1fcd..4d9c1064 100644 --- a/blueprint/tests/test_overlay.py +++ b/blueprint/tests/test_overlay.py @@ -120,8 +120,9 @@ def test_no_two_overlay_files_land_on_one_path(): @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.""" - environment = Environment(loader=FileSystemLoader(OVERLAY), undefined=StrictUndefined, keep_trailing_newline=True) - source = environment.loader.get_source(environment, path)[0] + 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 From 04b505f25a483d740c7c01b859e43362d93e6eba Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Tue, 17 Nov 2026 02:37:31 -0300 Subject: [PATCH 49/71] type-check blueprint/tests in ci and test that ci type-checks every blueprint test directory it runs --- .github/workflows/type-checking.yml | 6 ++++++ backend/tests/unit/test_blueprint_catalog.py | 19 +++++++++++++++++++ 2 files changed, 25 insertions(+) diff --git a/.github/workflows/type-checking.yml b/.github/workflows/type-checking.yml index 56698fda..cdcefaa2 100644 --- a/.github/workflows/type-checking.yml +++ b/.github/workflows/type-checking.yml @@ -40,3 +40,9 @@ jobs: env: ENVIRONMENT: local SECRET_KEY: test-secret-key-for-testing-only + + - 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/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index aa898ce1..fe8808b4 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -1006,6 +1006,25 @@ def test_the_workflow_reader_reads_every_run_and_a_block_line_by_line(): 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() From 3d01bb219057828633247624245bf299e23a9dd7 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Tue, 17 Nov 2026 16:17:20 -0300 Subject: [PATCH 50/71] name the blueprint fastapi-boilerplate in blueprint.toml and fastro.toml's pin, and pin the new name in the catalog test --- backend/tests/unit/test_blueprint_catalog.py | 2 +- blueprint.toml | 2 +- blueprint/tests/test_deploy_templates.py | 2 +- fastro.toml | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index fe8808b4..b20d5fee 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -64,7 +64,7 @@ def _drill(): def test_the_catalog_parses(): - assert _catalog()["blueprint"]["name"] == "fastro" + assert _catalog()["blueprint"]["name"] == "fastapi-boilerplate" def test_it_names_itself_the_way_the_spec_allows(): diff --git a/blueprint.toml b/blueprint.toml index 7d3bafcc..c84035b3 100644 --- a/blueprint.toml +++ b/blueprint.toml @@ -1,5 +1,5 @@ [blueprint] -name = "fastro" +name = "fastapi-boilerplate" version = "0.20.0" schema = 1 requires_fastro = ">=0.1.0.dev0,<0.2" diff --git a/blueprint/tests/test_deploy_templates.py b/blueprint/tests/test_deploy_templates.py index 6c3ea73c..fb2c45dc 100644 --- a/blueprint/tests/test_deploy_templates.py +++ b/blueprint/tests/test_deploy_templates.py @@ -28,7 +28,7 @@ def _context( """The spec 6.2 context, as the tool builds it for a generator.""" return { "project": {"name": "example", "slug": "example"}, - "blueprint": {"name": "fastro", "version": "0.20.0"}, + "blueprint": {"name": "fastapi-boilerplate", "version": "0.20.0"}, "fastro": {"version": "0.1.0"}, "features": list(features), "options": {}, diff --git a/fastro.toml b/fastro.toml index ee853cbe..07e5abf0 100644 --- a/fastro.toml +++ b/fastro.toml @@ -1,6 +1,6 @@ source = true features = ["accounts", "rbac", "ratelimit", "tiers", "tier_limits", "api_keys", "admin", "cache", "taskiq"] -blueprint = { name = "fastro", version = "0.20.0" } +blueprint = { name = "fastapi-boilerplate", version = "0.20.0" } [project] name = "fastapi-boilerplate" From 4d1a889cf835a868556df893c1fbc529cd2c5b1f Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Tue, 17 Nov 2026 16:36:28 -0300 Subject: [PATCH 51/71] name the FastAPI-boilerplate blueprint in full in the overlay's AGENTS.md and README, keep the catalog id and version beside it in the README, and test both --- blueprint/overlay/AGENTS.md | 3 ++- blueprint/overlay/README.md.j2 | 4 ++-- blueprint/tests/test_overlay.py | 14 ++++++++++++++ 3 files changed, 18 insertions(+), 3 deletions(-) diff --git a/blueprint/overlay/AGENTS.md b/blueprint/overlay/AGENTS.md index 72be0aa3..d64f738b 100644 --- a/blueprint/overlay/AGENTS.md +++ b/blueprint/overlay/AGENTS.md @@ -1,6 +1,7 @@ # Working in this project -A FastAPI backend generated by fastro. `backend/` holds everything that runs. +A FastAPI backend generated from the FastAPI-boilerplate blueprint by fastro. `backend/` holds +everything that runs. ## The layers diff --git a/blueprint/overlay/README.md.j2 b/blueprint/overlay/README.md.j2 index 6660d50e..e965771b 100644 --- a/blueprint/overlay/README.md.j2 +++ b/blueprint/overlay/README.md.j2 @@ -1,7 +1,7 @@ # {{ project.name }} -A FastAPI backend, generated from the {{ blueprint.name }} blueprint ({{ blueprint.version }}) by -fastro {{ fastro.version }}. +A FastAPI backend, generated from the FastAPI-boilerplate blueprint (`{{ blueprint.name }}` +{{ blueprint.version }}) by fastro {{ fastro.version }}. {% if features %} Selected: {{ features | join(", ") }}. {%- else %} diff --git a/blueprint/tests/test_overlay.py b/blueprint/tests/test_overlay.py index 4d9c1064..f533459a 100644 --- a/blueprint/tests/test_overlay.py +++ b/blueprint/tests/test_overlay.py @@ -211,6 +211,20 @@ def test_the_readme_names_the_features_a_project_selected(): 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 From e440fc95fdf4e5488d98191eab8201276314ef2c Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Tue, 17 Nov 2026 16:52:43 -0300 Subject: [PATCH 52/71] call the blueprint FastAPI-boilerplate wherever the bare tool name stood, rename the conftest alias to FastroRunner, and test that no tracked file outside the changelog and the cover and card scripts uses the bare name --- README.md | 14 ++++---- backend/tests/unit/test_blueprint_catalog.py | 36 ++++++++++++++++++++ blueprint/tests/conftest.py | 4 +-- blueprint/tests/test_fastro.py | 4 +-- blueprint/tests/test_observability_recipe.py | 6 ++-- blueprint/tests/test_overlay.py | 2 +- docs/fastro-vs-fastroai.md | 12 +++---- docs/index.md | 8 ++--- docs/user-guide/database/neon.md | 2 +- zensical.toml | 4 +-- 10 files changed, 64 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index f72f94ec..ff9b3251 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -

Fastro · The Benav Labs FastAPI Boilerplate

+

FastAPI-boilerplate by Benav Labs

Batteries-included FastAPI starter - vertical-slice modules, swappable infrastructure, plugin-ready CLI.

@@ -7,7 +7,7 @@ - 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

@@ -74,11 +74,11 @@ * **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 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** | @@ -98,12 +98,12 @@ 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 diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index b20d5fee..236ea374 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -2911,3 +2911,39 @@ def test_the_project_is_named_the_way_its_python_package_is(): 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/blueprint/tests/conftest.py b/blueprint/tests/conftest.py index deb38cfb..e13b6c19 100644 --- a/blueprint/tests/conftest.py +++ b/blueprint/tests/conftest.py @@ -8,7 +8,7 @@ REPO_ROOT = Path(__file__).resolve().parents[2] -Fastro = Callable[..., subprocess.CompletedProcess[str]] +FastroRunner = Callable[..., subprocess.CompletedProcess[str]] @pytest.fixture @@ -32,7 +32,7 @@ def tracked_tree(tmp_path: Path) -> Path: @pytest.fixture -def fastro() -> Fastro: +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]: diff --git a/blueprint/tests/test_fastro.py b/blueprint/tests/test_fastro.py index 4ea1dcd0..e6e5ec34 100644 --- a/blueprint/tests/test_fastro.py +++ b/blueprint/tests/test_fastro.py @@ -3,12 +3,12 @@ import tomllib from pathlib import Path -from conftest import Fastro +from conftest import FastroRunner REPO_ROOT = Path(__file__).resolve().parents[2] -def test_plain_sync_regenerates_what_the_check_compares(tracked_tree: Path, fastro: Fastro): +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"] diff --git a/blueprint/tests/test_observability_recipe.py b/blueprint/tests/test_observability_recipe.py index e9148f5b..692bcb45 100644 --- a/blueprint/tests/test_observability_recipe.py +++ b/blueprint/tests/test_observability_recipe.py @@ -6,7 +6,7 @@ from pathlib import Path import pytest -from conftest import Fastro +from conftest import FastroRunner REPO_ROOT = Path(__file__).resolve().parents[2] RECIPE = REPO_ROOT / "docs" / "user-guide" / "observability.md" @@ -41,7 +41,7 @@ def _installers_slot() -> tuple[str, str]: ) -def test_the_recipe_registers_its_installer_through_fastro_toml_and_a_sync(tracked_tree: Path, fastro: Fastro): +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") @@ -97,7 +97,7 @@ def test_the_installer_configures_tracing_before_it_instruments_the_app(): @pytest.mark.parametrize("arguments", [("sync",), ("sync", "--check")]) -def test_the_pinned_fastro_cannot_sync_a_project_yet(tracked_tree: Path, fastro: Fastro, arguments: tuple[str, ...]): +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)) diff --git a/blueprint/tests/test_overlay.py b/blueprint/tests/test_overlay.py index f533459a..2eb5c383 100644 --- a/blueprint/tests/test_overlay.py +++ b/blueprint/tests/test_overlay.py @@ -24,7 +24,7 @@ """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 +"""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.""" diff --git a/docs/fastro-vs-fastroai.md b/docs/fastro-vs-fastroai.md index 9d67e720..a1013941 100644 --- a/docs/fastro-vs-fastroai.md +++ b/docs/fastro-vs-fastroai.md @@ -1,8 +1,8 @@ -# 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** | @@ -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/index.md b/docs/index.md index 882b3ece..f83a3ce0 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

@@ -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/database/neon.md b/docs/user-guide/database/neon.md index 699b9e0b..f80102d0 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 diff --git a/zensical.toml b/zensical.toml index cff4283a..ec6ea5d7 100644 --- a/zensical.toml +++ b/zensical.toml @@ -1,5 +1,5 @@ [project] -site_name = "Fastro · FastAPI Boilerplate" +site_name = "FastAPI-boilerplate" site_description = "Production-ready FastAPI starter with sessions, OAuth, SQLAdmin, Taskiq, Redis caching, and a plugin-aware CLI." site_url = "https://benavlabs.github.io/FastAPI-boilerplate" docs_dir = "docs" @@ -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" = [ From 56b5aa683268122f753e1f248179c6cd10100a88 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Tue, 17 Nov 2026 16:56:10 -0300 Subject: [PATCH 53/71] read the blueprint's name and version in the deploy template test's context from blueprint.toml, as the overlay test does --- blueprint/tests/test_deploy_templates.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/blueprint/tests/test_deploy_templates.py b/blueprint/tests/test_deploy_templates.py index fb2c45dc..2f578f55 100644 --- a/blueprint/tests/test_deploy_templates.py +++ b/blueprint/tests/test_deploy_templates.py @@ -4,6 +4,7 @@ ``StrictUndefined``: a template that reaches for anything the tool doesn't pass fails here. """ +import tomllib from pathlib import Path from typing import Any @@ -11,6 +12,10 @@ import yaml 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" INTERNAL_SUBNET = "172.31.240.0/24" @@ -28,7 +33,7 @@ def _context( """The spec 6.2 context, as the tool builds it for a generator.""" return { "project": {"name": "example", "slug": "example"}, - "blueprint": {"name": "fastapi-boilerplate", "version": "0.20.0"}, + "blueprint": {"name": CATALOG["blueprint"]["name"], "version": CATALOG["blueprint"]["version"]}, "fastro": {"version": "0.1.0"}, "features": list(features), "options": {}, From 6e8b50106230e656bc4a4745dcf4cf4305e99a1d Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Tue, 17 Nov 2026 17:42:29 -0300 Subject: [PATCH 54/71] pass a refused secret key to the core-checks production validator test so it stops depending on the environment's SECRET_KEY --- .../unit/infrastructure/security/test_production_validator.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/backend/tests/unit/infrastructure/security/test_production_validator.py b/backend/tests/unit/infrastructure/security/test_production_validator.py index c429be50..ce276021 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() From 3b88ea2035216df1734ce37555cfcc58920a2580 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Tue, 17 Nov 2026 19:05:03 -0300 Subject: [PATCH 55/71] switch the readme and docs from the old cli commands to fastro make deploy, env secret and env validate, and test that every fastro command a page shows is one the pinned fastro takes --- README.md | 33 ++-- .../security/test_production_validator.py | 2 +- blueprint/tests/retired.py | 36 ++++ blueprint/tests/test_docs_commands.py | 158 ++++++++++++++++++ docs/fastro-vs-fastroai.md | 2 +- docs/getting-started/index.md | 4 +- docs/getting-started/installation.md | 16 +- docs/index.md | 2 +- docs/user-guide/background-tasks/index.md | 2 +- docs/user-guide/configuration/docker-setup.md | 10 +- .../configuration/environment-variables.md | 2 +- docs/user-guide/database/migrations.md | 2 +- docs/user-guide/database/neon.md | 2 +- docs/user-guide/production.md | 6 +- zensical.toml | 2 +- 15 files changed, 235 insertions(+), 44 deletions(-) create mode 100644 blueprint/tests/retired.py create mode 100644 blueprint/tests/test_docs_commands.py diff --git a/README.md b/README.md index ff9b3251..c1f4de73 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@

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.

@@ -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,7 +72,7 @@ * **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 ## FastAPI-boilerplate vs FastroAI @@ -85,7 +85,7 @@ | 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 | | ✓ | @@ -117,7 +117,7 @@ fastapi-boilerplate/ │ ├── src/ # interfaces/, infrastructure/, modules/ │ ├── pyproject.toml │ └── Dockerfile # multi-stage: dev / migrate / prod -└── cli/ # `bp` - developer/operator tool (never ships in prod) +└── cli/ # the old developer tool, being replaced by fastro └── src/cli/ ``` @@ -132,17 +132,17 @@ uv sync --all-packages --all-extras # one venv at the root: both membe 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,19 +168,16 @@ 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/). diff --git a/backend/tests/unit/infrastructure/security/test_production_validator.py b/backend/tests/unit/infrastructure/security/test_production_validator.py index ce276021..435d2f65 100644 --- a/backend/tests/unit/infrastructure/security/test_production_validator.py +++ b/backend/tests/unit/infrastructure/security/test_production_validator.py @@ -639,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/blueprint/tests/retired.py b/blueprint/tests/retired.py new file mode 100644 index 00000000..0c22e476 --- /dev/null +++ b/blueprint/tests/retired.py @@ -0,0 +1,36 @@ +"""The developer CLI this repository used to ship, as the scans that keep it gone read it. + +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.""" + + +def tracked_text() -> Iterator[tuple[str, str]]: + """Every tracked file that reads as UTF-8, by its path from the root, with its text.""" + listed = subprocess.run(["git", "ls-files", "-z"], 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_docs_commands.py b/blueprint/tests/test_docs_commands.py new file mode 100644 index 00000000..e122f6e2 --- /dev/null +++ b/blueprint/tests/test_docs_commands.py @@ -0,0 +1,158 @@ +"""The commands the README and the docs tell a reader to run are ones the pinned fastro has.""" + +import re +import shlex +from collections.abc import Iterator + +import click +import pytest +import typer.main +from fastro.cli import app +from retired import OLD_COMMAND, RUNS_OLD_COMMAND, shown_pages + +NOT_YET_SWITCHED = ("docs/cli/",) +"""Pages B3 item 2b deletes, with the old command in them until it does.""" + +FASTRO = typer.main.get_command(app) + +LAUNCHERS = (("uv", "run", "--no-sync"), ("uv", "run"), ("uvx",), ("python", "-m")) + +STOPS = {"|", "&&", "||", ";"} + + +def _pages() -> Iterator[tuple[str, str]]: + for name, text in shown_pages(): + if not name.startswith(NOT_YET_SWITCHED): + yield name, text + + +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 _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 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 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 _pages() + for number, line in enumerate(text.splitlines(), 1) + if RUNS_OLD_COMMAND.search(line) + ] + + assert not found, 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`.", False), + ("Run `fastro make deploy prod|cat`.", 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 diff --git a/docs/fastro-vs-fastroai.md b/docs/fastro-vs-fastroai.md index a1013941..1495753c 100644 --- a/docs/fastro-vs-fastroai.md +++ b/docs/fastro-vs-fastroai.md @@ -9,7 +9,7 @@ | 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 | | ✓ | diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index f0927758..0b3bed41 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -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,7 +68,7 @@ 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 diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 7c13a09b..2ae759c1 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,7 +37,7 @@ 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 @@ -49,7 +49,7 @@ Docker Compose handles every service for you (Postgres + Redis + the app). ```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 lives in `backend/` and `cli/` holds the old developer tool, which fastro replaces. Both share a single virtual environment at the repo root. 2. **Install Python dependencies**: @@ -143,14 +143,14 @@ For development on your host machine. You provide PostgreSQL and Redis yourself. ```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 [CLI → Commands](../cli/commands.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): diff --git a/docs/index.md b/docs/index.md index f83a3ce0..7d886d58 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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 ``` diff --git a/docs/user-guide/background-tasks/index.md b/docs/user-guide/background-tasks/index.md index 5756da65..b44d5536 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 diff --git a/docs/user-guide/configuration/docker-setup.md b/docs/user-guide/configuration/docker-setup.md index 2191936d..15c65ea2 100644 --- a/docs/user-guide/configuration/docker-setup.md +++ b/docs/user-guide/configuration/docker-setup.md @@ -6,7 +6,7 @@ This page walks through running the boilerplate in containers. The Python projec `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). @@ -15,7 +15,7 @@ This page walks through running the boilerplate in containers. The Python projec ```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 ``` @@ -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..3c8d8c5e 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. diff --git a/docs/user-guide/database/migrations.md b/docs/user-guide/database/migrations.md index f1fac7e1..bc360aa7 100644 --- a/docs/user-guide/database/migrations.md +++ b/docs/user-guide/database/migrations.md @@ -453,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 f80102d0..75ddfb6d 100644 --- a/docs/user-guide/database/neon.md +++ b/docs/user-guide/database/neon.md @@ -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/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/zensical.toml b/zensical.toml index ec6ea5d7..d26771b1 100644 --- a/zensical.toml +++ b/zensical.toml @@ -1,6 +1,6 @@ [project] site_name = "FastAPI-boilerplate" -site_description = "Production-ready FastAPI starter with sessions, OAuth, SQLAdmin, Taskiq, Redis caching, and a plugin-aware CLI." +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" From df17128ae5db59d77f83de37681409ea6cfb6cda Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Tue, 17 Nov 2026 20:11:37 -0300 Subject: [PATCH 56/71] replace the cli docs section with one fastro page, redirect the old cli urls to it, fix the broken environment-variables anchor, and test that every docs link lands on a page and a heading and that the page's facts match fastro --- README.md | 2 +- blueprint/tests/retired.py | 10 +- blueprint/tests/test_docs_commands.py | 13 +- blueprint/tests/test_docs_links.py | 128 +++++++ blueprint/tests/test_fastro_page.py | 289 +++++++++++++++ docs/changelog.md | 4 + docs/cli/commands.md | 208 ----------- docs/cli/index.md | 109 ------ docs/cli/plugins.md | 334 ------------------ docs/getting-started/index.md | 2 +- docs/getting-started/installation.md | 4 +- docs/user-guide/authentication/index.md | 2 +- docs/user-guide/configuration/docker-setup.md | 2 +- docs/user-guide/fastro.md | 79 +++++ zensical.toml | 17 +- 15 files changed, 526 insertions(+), 677 deletions(-) create mode 100644 blueprint/tests/test_docs_links.py create mode 100644 blueprint/tests/test_fastro_page.py delete mode 100644 docs/cli/commands.md delete mode 100644 docs/cli/index.md delete mode 100644 docs/cli/plugins.md create mode 100644 docs/user-guide/fastro.md diff --git a/README.md b/README.md index c1f4de73..7f7a6ba9 100644 --- a/README.md +++ b/README.md @@ -180,7 +180,7 @@ cd backend && uv run --no-sync alembic revision --autogenerate -m "" && uv cd backend && uv run --no-sync pytest ``` -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/blueprint/tests/retired.py b/blueprint/tests/retired.py index 0c22e476..61f24c3a 100644 --- a/blueprint/tests/retired.py +++ b/blueprint/tests/retired.py @@ -17,8 +17,14 @@ def tracked_text() -> Iterator[tuple[str, str]]: - """Every tracked file that reads as UTF-8, by its path from the root, with its text.""" - listed = subprocess.run(["git", "ls-files", "-z"], cwd=REPO_ROOT, capture_output=True, text=True, check=True) + """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(): diff --git a/blueprint/tests/test_docs_commands.py b/blueprint/tests/test_docs_commands.py index e122f6e2..a767cdff 100644 --- a/blueprint/tests/test_docs_commands.py +++ b/blueprint/tests/test_docs_commands.py @@ -10,9 +10,6 @@ from fastro.cli import app from retired import OLD_COMMAND, RUNS_OLD_COMMAND, shown_pages -NOT_YET_SWITCHED = ("docs/cli/",) -"""Pages B3 item 2b deletes, with the old command in them until it does.""" - FASTRO = typer.main.get_command(app) LAUNCHERS = (("uv", "run", "--no-sync"), ("uv", "run"), ("uvx",), ("python", "-m")) @@ -20,12 +17,6 @@ STOPS = {"|", "&&", "||", ";"} -def _pages() -> Iterator[tuple[str, str]]: - for name, text in shown_pages(): - if not name.startswith(NOT_YET_SWITCHED): - yield name, text - - 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.""" @@ -64,7 +55,7 @@ def _fastro_words(code: str) -> list[str] | None: def _commands() -> list[tuple[str, list[str], bool]]: return [ (f"{name}: {code.strip()}", words, runs) - for name, text in _pages() + for name, text in shown_pages() for code, runs in _code(text) if (words := _fastro_words(code)) is not None ] @@ -97,7 +88,7 @@ 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 _pages() + for name, text in shown_pages() for number, line in enumerate(text.splitlines(), 1) if RUNS_OLD_COMMAND.search(line) ] diff --git a/blueprint/tests/test_docs_links.py b/blueprint/tests/test_docs_links.py new file mode 100644 index 00000000..2ce2f6db --- /dev/null +++ b/blueprint/tests/test_docs_links.py @@ -0,0 +1,128 @@ +"""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 + +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"cli/{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_fastro_page.py b/blueprint/tests/test_fastro_page.py new file mode 100644 index 00000000..b8ad0ea0 --- /dev/null +++ b/blueprint/tests/test_fastro_page.py @@ -0,0 +1,289 @@ +"""What the fastro page states about fastro's commands and the compose files they write. + +At the pin, `fastro make deploy` renders fastro's own legacy templates, not this repository's +`[generators.deploy]`, so the page's facts about what a mode writes are read from those. +""" + +import importlib.util +import re +import subprocess +import sys +import tomllib +from pathlib import Path +from types import SimpleNamespace +from typing import Any, cast + +import click +import pytest +import typer.main +import yaml +from fastro import _legacy_deploy as deploy +from fastro.cli import app +from fastro.commands import env +from fastro.lib.render import Renderer + +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()) + +FASTRO = typer.main.get_command(app) +MAKE_DEPLOY = "## Writing the compose files: `fastro make deploy`" + + +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() -> list[list[str]]: + return [row for row in _rows() if row[0].startswith("`-")] + + +def _plan(mode: str, root: Path, taskiq: bool = True, api_port: int = 8000, workers: int = 4, **params: Any) -> deploy.Plan: + backend = root / "backend" + backend.mkdir(parents=True, exist_ok=True) + if taskiq: + (backend / deploy.TASKIQ_PACKAGE).mkdir(parents=True) + project = SimpleNamespace(repo_root=root, backend_dir=backend) + + return deploy.plan(mode, cast(Any, project), root, api_port=api_port, workers=workers, **params) + + +def _rendered(plan: deploy.Plan) -> dict[str, str]: + renderer = Renderer(deploy.TEMPLATES) + + return {render.target.name: renderer.render(render.template, plan.context) for render in plan.files} + + +def _services(mode: str, root: Path, taskiq: bool = True) -> dict[str, Any]: + return dict(yaml.safe_load(_rendered(_plan(mode, root, taskiq))["docker-compose.yml"])["services"]) + + +def test_the_page_names_the_modes_fastro_takes(): + mode = next(param for param in _command("make", "deploy").params if param.name == "mode") + assert isinstance(mode.type, click.Choice) + + assert sorted(_mode_rows()) == sorted(mode.type.choices) + + +@pytest.mark.parametrize("mode", ["local", "prod", "nginx"]) +def test_each_mode_writes_the_files_and_the_stack_its_row_names(mode: str, tmp_path: Path): + row = _mode_rows()[mode] + plan = _plan(mode, tmp_path) + services = _services(mode, tmp_path / "rendered") + 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(str(render.target.relative_to(tmp_path)) for render in plan.files) == 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", ["local", "prod", "nginx"]) +def test_a_project_with_taskiq_gets_a_worker_and_one_scheduler_in_every_mode(mode: str, tmp_path: Path): + with_taskiq = _services(mode, tmp_path / "with") + without = _services(mode, tmp_path / "without", taskiq=False) + + assert "taskiq feature also gets a `worker` and one `scheduler` in every mode" in _section(MAKE_DEPLOY) + assert {"worker", "scheduler"} <= set(with_taskiq) + assert with_taskiq["scheduler"].get("deploy", {}).get("replicas", 1) == 1 + assert not {"worker", "scheduler"} & set(without) + + +def test_the_options_and_their_defaults_are_the_ones_fastro_has(): + options = {param.opts[0]: param for param in _command("make", "deploy").params if isinstance(param, click.Option)} + stated = {_ticked(row[0])[0]: row for row in _option_rows()} + + assert sorted(stated) == sorted(options) + for flag, row in stated.items(): + option = options[flag] + assert sorted(_ticked(row[0])) == sorted(option.opts), flag + if option.is_flag: + assert row[1] == "", flag + elif option.default is None: + assert (flag, row[1]) == ("--output-dir", "the repository root") + else: + assert row[1] == f"`{option.default}`", flag + + +def test_the_subnet_limits_are_the_catalogs_and_fastros(): + limits = CATALOG["generators"]["deploy"]["params"]["internal_subnet"]["max_prefix"] + + assert {4: limits["v4"], 6: limits["v6"]} == deploy.SMALLEST_TRUSTED_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( + ("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_the_subnet_refusals_the_pages_name(subnet: str, refused: bool): + try: + deploy.validated_subnet(subnet) + except ValueError: + assert refused, subnet + else: + assert not refused, subnet + + +def test_the_nginx_subnet_is_the_network_and_the_peers_uvicorn_trusts(tmp_path: Path): + subnet = "10.89.0.0/24" + compose = yaml.safe_load(_rendered(_plan("nginx", tmp_path, internal_subnet=subnet))["docker-compose.yml"]) + 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 + + +@pytest.mark.parametrize(("mode", "refused"), [("nginx", True), ("local", False), ("prod", False)]) +def test_only_nginx_reads_the_subnet(mode: str, refused: bool): + run = subprocess.run( + [sys.executable, "-m", "fastro", "make", "deploy", mode, "--internal-subnet", "*", "--dry-run"], + cwd=REPO_ROOT, + capture_output=True, + text=True, + ) + + assert (run.returncode != 0) is refused, run.stdout + run.stderr + assert "`local` and `prod` always use the default network" in _section(MAKE_DEPLOY) + + +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("## Preparing the environment: `fastro 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_every_command_the_page_heads_a_section_with_is_one_fastro_has(): + headed = re.findall(r"^#+ .*?`fastro ([a-z ]+)`", PAGE.read_text(), re.M) + + assert headed + for words in headed: + _command(*words.split()) + + +def _modes_named(cell: str) -> set[str]: + named = re.search(r"for ((?:`\w+`(?: and )?)+)$", cell) + + return set(_ticked(named[1])) if named else {"local", "prod", "nginx"} + + +@pytest.mark.parametrize("mode", ["local", "prod", "nginx"]) +def test_the_port_and_the_workers_reach_the_modes_their_rows_name(mode: str, tmp_path: Path): + rows = {_ticked(row[0])[0]: row for row in _option_rows()} + rendered = _rendered(_plan(mode, tmp_path, api_port=9123, workers=7)) + api = yaml.safe_load(rendered["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(rendered.values()) + if mode in _modes_named(rows["--workers"][2]): + assert environment["WORKERS"] == "7" + else: + assert "WORKERS" not in environment + + +def test_the_env_commands_run_the_scripts_the_page_names(): + section = _section("## Preparing the environment: `fastro env`") + + for module in (env.GEN_SECRET_MODULE, env.VALIDATE_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("## Preparing the environment: `fastro 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") diff --git a/docs/changelog.md b/docs/changelog.md index c79176b7..d9b7307b 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -39,6 +39,10 @@ ___ 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. ___ 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/getting-started/index.md b/docs/getting-started/index.md index 0b3bed41..f554740f 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -73,7 +73,7 @@ Pick whichever workflow fits you: `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 diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 2ae759c1..26c0cb0b 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -43,7 +43,7 @@ Docker Compose handles every service for you (Postgres + Redis + the app). `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**: @@ -146,7 +146,7 @@ For development on your host machine. You provide PostgreSQL and Redis yourself. # set a strong SECRET_KEY (or run `uv run --no-sync fastro env secret`), etc. ``` - fastro has 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 fastro env secret # print a fresh SECRET_KEY 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/configuration/docker-setup.md b/docs/user-guide/configuration/docker-setup.md index 15c65ea2..952397bc 100644 --- a/docs/user-guide/configuration/docker-setup.md +++ b/docs/user-guide/configuration/docker-setup.md @@ -8,7 +8,7 @@ This page walks through running the boilerplate in containers. The Python projec !!! info "The compose file is generated, not shipped" 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 diff --git a/docs/user-guide/fastro.md b/docs/user-guide/fastro.md new file mode 100644 index 00000000..7f65137f --- /dev/null +++ b/docs/user-guide/fastro.md @@ -0,0 +1,79 @@ +# 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` writes `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. + +| 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` | | Overwrite existing files without asking | +| `--yes`, `-y` | | Assume yes for every prompt | +| `--dry-run` | | Show what would be written, 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 +``` + +For `nginx`, `--internal-subnet` has to name a network of `/8` or smaller for IPv4, and `/48` or +smaller for IPv6. It is written as the compose network's subnet and as `FORWARDED_ALLOW_IPS` for +the API container, so a value with host bits set (`172.31.240.1/24`), a wildcard, or a wider +range is refused 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. In a project it runs the project's own `scripts.gen_secret`, 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 +``` + +Runs the project's `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). + +## 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/zensical.toml b/zensical.toml index d26771b1..a170537c 100644 --- a/zensical.toml +++ b/zensical.toml @@ -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" From 4ed8917c2131922c7b5301f616f9626a6e3c9504 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Tue, 17 Nov 2026 22:12:38 -0300 Subject: [PATCH 57/71] move the fastro pin from ddda03f to a07bbc1 --- pyproject.toml | 2 +- uv.lock | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 0ffcd34e..2c4e2011 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -33,7 +33,7 @@ dev = ["fastro", "packaging>=24.0", "pyyaml>=6.0.2", "types-pyyaml>=6.0.12"] members = ["backend", "cli"] [tool.uv.sources] -fastro = { git = "https://github.com/benavlabs/fastro", rev = "ddda03f1151b3233e083dd2d4354649dc997e4ec" } +fastro = { git = "https://github.com/benavlabs/fastro", rev = "a07bbc1b0a4a0c894bcd59edf5a602b36e34bae1" } [tool.pytest.ini_options] testpaths = ["blueprint/tests"] diff --git a/uv.lock b/uv.lock index 07f11706..e0eba0ab 100644 --- a/uv.lock +++ b/uv.lock @@ -992,7 +992,7 @@ dev = [ [package.metadata.requires-dev] dev = [ - { name = "fastro", git = "https://github.com/benavlabs/fastro?rev=ddda03f1151b3233e083dd2d4354649dc997e4ec" }, + { name = "fastro", git = "https://github.com/benavlabs/fastro?rev=a07bbc1b0a4a0c894bcd59edf5a602b36e34bae1" }, { name = "packaging", specifier = ">=24.0" }, { name = "pyyaml", specifier = ">=6.0.2" }, { name = "types-pyyaml", specifier = ">=6.0.12" }, @@ -1156,7 +1156,7 @@ wheels = [ [[package]] name = "fastro" version = "0.1.0.dev0" -source = { git = "https://github.com/benavlabs/fastro?rev=ddda03f1151b3233e083dd2d4354649dc997e4ec#ddda03f1151b3233e083dd2d4354649dc997e4ec" } +source = { git = "https://github.com/benavlabs/fastro?rev=a07bbc1b0a4a0c894bcd59edf5a602b36e34bae1#a07bbc1b0a4a0c894bcd59edf5a602b36e34bae1" } dependencies = [ { name = "jinja2" }, { name = "packaging" }, From 7d43d23aa751e94522110a627d72e28211c21773 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Tue, 17 Nov 2026 23:09:36 -0300 Subject: [PATCH 58/71] remove the old cli package and make backend the workspace's one member, check the deploy generator against fastro's own options, and test that nothing outside the changelog names the old package or runs its command --- .github/workflows/linting.yml | 4 +- .github/workflows/tests.yml | 3 - .github/workflows/type-checking.yml | 6 - .pre-commit-config.yaml | 8 - CONTRIBUTING.md | 4 +- README.md | 14 +- backend/Dockerfile | 1 - backend/tests/unit/test_blueprint_catalog.py | 59 ++--- blueprint.toml | 1 - blueprint/tests/retired.py | 9 + blueprint/tests/test_deploy_generator.py | 52 +++++ blueprint/tests/test_docs_commands.py | 19 +- blueprint/tests/test_docs_links.py | 3 +- blueprint/tests/test_overlay.py | 2 +- blueprint/tests/test_retired_cli.py | 107 +++++++++ cli/README.md | 48 ---- cli/pyproject.toml | 60 ----- cli/src/cli/__init__.py | 12 - cli/src/cli/app.py | 62 ----- cli/src/cli/commands/__init__.py | 0 cli/src/cli/commands/deploy.py | 107 --------- cli/src/cli/commands/env.py | 139 ----------- cli/src/cli/features/__init__.py | 25 -- cli/src/cli/features/_builtins/__init__.py | 0 .../cli/features/_builtins/deploy/__init__.py | 0 .../cli/features/_builtins/deploy/feature.py | 108 --------- .../templates/local/docker-compose.yml.j2 | 107 --------- .../deploy/templates/nginx/default.conf.j2 | 33 --- .../templates/nginx/docker-compose.yml.j2 | 147 ------------ .../templates/prod/docker-compose.yml.j2 | 126 ---------- cli/src/cli/features/base.py | 98 -------- cli/src/cli/features/installer.py | 88 ------- cli/src/cli/features/registry.py | 44 ---- cli/src/cli/lib/__init__.py | 0 cli/src/cli/lib/project.py | 70 ------ cli/src/cli/lib/prompts.py | 32 --- cli/src/cli/lib/render.py | 33 --- cli/src/cli/plugins.py | 109 --------- cli/src/cli/py.typed | 0 cli/tests/__init__.py | 0 cli/tests/test_deploy_command.py | 121 ---------- cli/tests/test_deploy_templates.py | 159 ------------- cli/tests/test_env_command.py | 216 ------------------ docs/changelog.md | 11 + docs/getting-started/index.md | 4 +- docs/getting-started/installation.md | 4 +- docs/user-guide/configuration/docker-setup.md | 6 +- docs/user-guide/development.md | 2 +- pyproject.toml | 25 +- uv.lock | 27 --- 50 files changed, 253 insertions(+), 2062 deletions(-) create mode 100644 blueprint/tests/test_deploy_generator.py create mode 100644 blueprint/tests/test_retired_cli.py delete mode 100644 cli/README.md delete mode 100644 cli/pyproject.toml delete mode 100644 cli/src/cli/__init__.py delete mode 100644 cli/src/cli/app.py delete mode 100644 cli/src/cli/commands/__init__.py delete mode 100644 cli/src/cli/commands/deploy.py delete mode 100644 cli/src/cli/commands/env.py delete mode 100644 cli/src/cli/features/__init__.py delete mode 100644 cli/src/cli/features/_builtins/__init__.py delete mode 100644 cli/src/cli/features/_builtins/deploy/__init__.py delete mode 100644 cli/src/cli/features/_builtins/deploy/feature.py delete mode 100644 cli/src/cli/features/_builtins/deploy/templates/local/docker-compose.yml.j2 delete mode 100644 cli/src/cli/features/_builtins/deploy/templates/nginx/default.conf.j2 delete mode 100644 cli/src/cli/features/_builtins/deploy/templates/nginx/docker-compose.yml.j2 delete mode 100644 cli/src/cli/features/_builtins/deploy/templates/prod/docker-compose.yml.j2 delete mode 100644 cli/src/cli/features/base.py delete mode 100644 cli/src/cli/features/installer.py delete mode 100644 cli/src/cli/features/registry.py delete mode 100644 cli/src/cli/lib/__init__.py delete mode 100644 cli/src/cli/lib/project.py delete mode 100644 cli/src/cli/lib/prompts.py delete mode 100644 cli/src/cli/lib/render.py delete mode 100644 cli/src/cli/plugins.py delete mode 100644 cli/src/cli/py.typed delete mode 100644 cli/tests/__init__.py delete mode 100644 cli/tests/test_deploy_command.py delete mode 100644 cli/tests/test_deploy_templates.py delete mode 100644 cli/tests/test_env_command.py diff --git a/.github/workflows/linting.yml b/.github/workflows/linting.yml index e652ba18..485458da 100644 --- a/.github/workflows/linting.yml +++ b/.github/workflows/linting.yml @@ -28,10 +28,10 @@ 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 blueprint/tests + run: uv run --no-sync ruff check backend/src backend/tests backend/scripts backend/migrations tools 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 blueprint/tests + run: uv run --no-sync ruff format --check backend/src backend/tests backend/scripts backend/migrations tools blueprint/tests - name: Wiring in sync run: uv run --no-sync fastro sync --check diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 746fd114..19092f81 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -31,9 +31,6 @@ 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 diff --git a/.github/workflows/type-checking.yml b/.github/workflows/type-checking.yml index cdcefaa2..8d6e7d8c 100644 --- a/.github/workflows/type-checking.yml +++ b/.github/workflows/type-checking.yml @@ -29,12 +29,6 @@ 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 env: diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index fe2ac28a..9cc1b795 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -46,14 +46,6 @@ repos: files: ^backend/(src|scripts|migrations|tests)/ types: [python] - - id: mypy_cli - name: Mypy (cli) - language: system - entry: bash -c 'cd cli && uv run --no-sync mypy -p cli' - pass_filenames: false - files: ^cli/src/ - types: [python] - - id: fastro_sync_check name: Wiring in sync (fastro) language: system diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d229a78d..79d263ee 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,8 +24,8 @@ 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` diff --git a/README.md b/README.md index 7f7a6ba9..b58ae108 100644 --- a/README.md +++ b/README.md @@ -108,17 +108,15 @@ ## 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/ # the old developer tool, being replaced by fastro - └── src/cli/ +└── backend/ # the deployable application + ├── src/ # interfaces/, infrastructure/, modules/ + ├── pyproject.toml + └── Dockerfile # multi-stage: dev / migrate / prod ``` ## Quickstart @@ -126,7 +124,7 @@ 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, plus fastro +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: 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/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index 236ea374..c7986340 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -486,6 +486,13 @@ def _workspace_members() -> list[str]: 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 @@ -544,7 +551,7 @@ def _hook_paths() -> list[str]: @pytest.mark.parametrize( ("pattern", "heads"), [ - ("^cli/src/", ["cli/src"]), + ("^tools/", ["tools"]), ("^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"]), @@ -571,7 +578,7 @@ def _readme_references() -> list[str]: POINTS_AT = { - "pyproject.toml": _workspace_members, + "pyproject.toml": _root_project_paths, ".pre-commit-config.yaml": _hook_paths, "README.md": _readme_references, } @@ -582,9 +589,10 @@ def _readme_references() -> list[str]: 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 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. + 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)) @@ -592,8 +600,8 @@ def test_no_file_a_project_receives_points_at_one_it_does_not(path: str): WITHHELD_POINTERS = { - "pyproject.toml": "cli", - ".pre-commit-config.yaml": "cli/src", + "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.""" @@ -604,8 +612,8 @@ 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. When `cli/` goes - in B3, this is where the question of shipping the workspace root comes back. + 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]() @@ -622,6 +630,11 @@ def _root_project() -> dict[str, Any]: 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") @@ -1232,7 +1245,7 @@ def _literals(module: Path) -> set[str]: def test_no_test_a_project_receives_names_a_tree_it_does_not_get(): - """A test that reaches for `docs/`, `tools/` or `cli/` is a test no project can run. + """A test that reaches for `docs/` or `tools/` is a test no project can run. `test_removal_drill.py` loads `tools/removal_drill.py`, and `test_baseline.py` read the migrations guide: both are files a project never receives, and the drill hid it by copying @@ -1257,10 +1270,10 @@ def test_no_test_a_project_receives_names_a_tree_it_does_not_get(): def test_the_things_projects_must_not_receive_are_listed(): - """The catalog, the drill, the docs and the tool's own tree belong to the blueprint only.""" + """The catalog, the drill and the docs belong to the blueprint only.""" listed = set(_catalog()["blueprint"]["blueprint_only"]) - assert {"blueprint/", "blueprint.toml", "fastro.toml", "docs/", "tools/", "cli/"} <= listed + assert {"blueprint/", "blueprint.toml", "fastro.toml", "docs/", "tools/"} <= listed assert "backend/tests/unit/test_blueprint_catalog.py" in listed @@ -2684,14 +2697,6 @@ def test_every_generators_templates_are_a_directory_this_repo_has(name: str): assert any(child.is_dir() for child in templates.iterdir()) -def test_the_deploy_modes_are_the_ones_this_repo_can_generate(): - """A mode with no template tree would be offered and then fail; a tree with no mode is dead.""" - templates = REPO_ROOT / _catalog()["generators"]["deploy"]["templates"] - offered = re.findall(r"^ (\w+) = \"\w+\"$", (REPO_ROOT / "cli/src/cli/commands/deploy.py").read_text(), re.M) - - assert sorted(child.name for child in templates.iterdir() if child.is_dir()) == sorted(offered) - - @pytest.mark.parametrize( ("generator", "param"), sorted((name, param) for name, declared in _catalog()["generators"].items() for param in declared["params"]), @@ -2739,20 +2744,6 @@ def test_every_param_the_templates_read_is_a_param_the_catalog_declares(): assert read == set(generator["params"]) -def test_the_defaults_are_what_this_repos_own_generator_already_uses(): - """`fastro make deploy` has to write what `bp deploy generate` writes, or the first run changes.""" - params = _catalog()["generators"]["deploy"]["params"] - source = (REPO_ROOT / "cli/src/cli/commands/deploy.py").read_text() - subnet = (REPO_ROOT / "cli/src/cli/features/_builtins/deploy/feature.py").read_text() - - assert f'typer.Option({params["api_port"]["default"]}, "--api-port"' in source - assert f'typer.Option({params["workers"]["default"]}, "--workers"' in source - assert f'DEFAULT_INTERNAL_SUBNET = "{params["internal_subnet"]["default"]}"' in subnet - - limits = params["internal_subnet"]["max_prefix"] - assert f"SMALLEST_TRUSTED_PREFIX = {{4: {limits['v4']}, 6: {limits['v6']}}}" in subnet - - 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. diff --git a/blueprint.toml b/blueprint.toml index c84035b3..bf1bd229 100644 --- a/blueprint.toml +++ b/blueprint.toml @@ -24,7 +24,6 @@ blueprint_only = [ "backend/tests/unit/test_tarball_contents.py", "blueprint/", "blueprint.toml", - "cli/", "docs/", "fastro.toml", "pyproject.toml", diff --git a/blueprint/tests/retired.py b/blueprint/tests/retired.py index 61f24c3a..78ea626c 100644 --- a/blueprint/tests/retired.py +++ b/blueprint/tests/retired.py @@ -15,6 +15,15 @@ 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.""" + +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.""" diff --git a/blueprint/tests/test_deploy_generator.py b/blueprint/tests/test_deploy_generator.py new file mode 100644 index 00000000..65735331 --- /dev/null +++ b/blueprint/tests/test_deploy_generator.py @@ -0,0 +1,52 @@ +"""The catalog's `[generators.deploy]` modes, defaults and subnet limits, against the pinned +`fastro make deploy`'s options and its legacy deploy module.""" + +import tomllib +from pathlib import Path + +import click +import typer.main +from fastro import _legacy_deploy as deploy +from fastro.cli import app + +REPO_ROOT = Path(__file__).resolve().parents[2] +GENERATOR = tomllib.loads((REPO_ROOT / "blueprint.toml").read_text())["generators"]["deploy"] + +FASTRO = typer.main.get_command(app) + + +def _make_deploy() -> click.Command: + group = FASTRO + assert isinstance(group, click.Group) + make = group.commands["make"] + assert isinstance(make, click.Group) + + return make.commands["deploy"] + + +def _params() -> dict[str, click.Parameter]: + return {str(param.name): param for param in _make_deploy().params} + + +def test_the_deploy_modes_are_the_ones_fastro_takes(): + """A mode with no template tree would be offered and then fail; a tree with no mode is dead.""" + templates = REPO_ROOT / GENERATOR["templates"] + mode = _params()["mode"] + assert isinstance(mode.type, click.Choice) + + assert sorted(child.name for child in templates.iterdir() if child.is_dir()) == sorted(mode.type.choices) + + +def test_the_port_and_the_workers_default_to_fastros(): + params = _params() + + assert GENERATOR["params"]["api_port"]["default"] == params["api_port"].default + assert GENERATOR["params"]["workers"]["default"] == params["workers"].default + + +def test_the_subnet_default_and_limits_are_fastros(): + subnet = GENERATOR["params"]["internal_subnet"] + limits = subnet["max_prefix"] + + assert subnet["default"] == deploy.DEFAULT_INTERNAL_SUBNET == _params()["internal_subnet"].default + assert {4: limits["v4"], 6: limits["v6"]} == deploy.SMALLEST_TRUSTED_PREFIX diff --git a/blueprint/tests/test_docs_commands.py b/blueprint/tests/test_docs_commands.py index a767cdff..ed342d1a 100644 --- a/blueprint/tests/test_docs_commands.py +++ b/blueprint/tests/test_docs_commands.py @@ -2,13 +2,14 @@ import re import shlex +import tomllib from collections.abc import Iterator import click import pytest import typer.main from fastro.cli import app -from retired import OLD_COMMAND, RUNS_OLD_COMMAND, shown_pages +from retired import OLD_COMMAND, REPO_ROOT, RUNS_OLD_COMMAND, shown_pages FASTRO = typer.main.get_command(app) @@ -147,3 +148,19 @@ def test_the_reader_refuses_what_fastro_would(page: str, refused: bool): ) 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()] == [] diff --git a/blueprint/tests/test_docs_links.py b/blueprint/tests/test_docs_links.py index 2ce2f6db..5ac75306 100644 --- a/blueprint/tests/test_docs_links.py +++ b/blueprint/tests/test_docs_links.py @@ -12,6 +12,7 @@ from typing import Any import pytest +from retired import OLD_PACKAGE REPO_ROOT = Path(__file__).resolve().parents[2] DOCS = REPO_ROOT / "docs" @@ -107,7 +108,7 @@ def test_every_page_is_in_the_nav_and_every_nav_entry_is_a_page(): def test_every_redirect_leaves_a_page_that_is_gone_for_one_that_is_there(): redirects = SITE["plugins"]["redirects"]["redirect_maps"] - assert redirects == {f"cli/{page}.md": "user-guide/fastro.md" for page in ("index", "commands", "plugins")} + 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 diff --git a/blueprint/tests/test_overlay.py b/blueprint/tests/test_overlay.py index 2eb5c383..19b417fa 100644 --- a/blueprint/tests/test_overlay.py +++ b/blueprint/tests/test_overlay.py @@ -292,7 +292,7 @@ def test_the_workflow_installs_the_project_rather_than_this_workspace(): def test_every_pre_commit_hook_watches_paths_a_project_has(): - """A `files:` pattern naming `cli/` or `tools/` is a hook over nothing: those are the + """A `files:` pattern naming `tools/` or `docs/` 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] diff --git a/blueprint/tests/test_retired_cli.py b/blueprint/tests/test_retired_cli.py new file mode 100644 index 00000000..f3ff0cbb --- /dev/null +++ b/blueprint/tests/test_retired_cli.py @@ -0,0 +1,107 @@ +"""Nothing outside the history names the developer tool's old package or the command it shipped.""" + +import importlib.metadata +import re +from collections.abc import Iterator + +import pytest +from fastro import compat +from retired import NAMES_OLD_COMMAND, NAMES_OLD_PACKAGE, OLD_COMMAND, OLD_PACKAGE, REPO_ROOT, tracked_text + +NEEDLES = {"package": NAMES_OLD_PACKAGE, "command": NAMES_OLD_COMMAND} + +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", +} +"""Which needle each exempted file carries, and the item that lifts the exemption.""" + +REDIRECTS = "[project.plugins.redirects.redirect_maps]" + + +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): + hits.setdefault((needle, name), []).append(f"{name}:{number}: {line.strip()}") + + return hits + + +def test_no_file_names_the_old_package_or_its_command(): + 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 + + +def _old_and_new_commands() -> list[tuple[str, str]]: + """The pairs the changelog's entry for the package's removal gives, old command first.""" + changelog = (REPO_ROOT / "docs" / "changelog.md").read_text() + unreleased = changelog.split("\n## Unreleased\n", 1)[1].split("\n## ", 1)[0] + removed = " ".join(unreleased.split("#### Removed", 1)[1].split("\n#### ", 1)[0].split()) + + return re.findall(rf"`{OLD_COMMAND} ([^`]+)` is `fastro ([^`]+)`", removed) + + +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/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/_builtins/deploy/templates/local/docker-compose.yml.j2 b/cli/src/cli/features/_builtins/deploy/templates/local/docker-compose.yml.j2 deleted file mode 100644 index 7f5d74f5..00000000 --- a/cli/src/cli/features/_builtins/deploy/templates/local/docker-compose.yml.j2 +++ /dev/null @@ -1,107 +0,0 @@ -# Generated by `bp deploy generate 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 }} - -services: - api: - build: - context: {{ build_context }} - dockerfile: {{ backend_dockerfile }} - target: dev - env_file: - - {{ env_file }} - 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 - ports: - - "{{ api_port }}:8000" - depends_on: - postgres: - condition: service_healthy - redis: - condition: service_healthy -{% if taskiq %} - worker: - build: - context: {{ build_context }} - dockerfile: {{ backend_dockerfile }} - target: dev - env_file: - - {{ env_file }} - environment: - POSTGRES_SERVER: postgres - CACHE_REDIS_HOST: redis - RATE_LIMITER_REDIS_HOST: redis - TASKIQ_REDIS_HOST: redis - working_dir: /app/src - command: > - taskiq worker src.infrastructure.taskiq.worker:default_broker - --reload - volumes: - - {{ backend_context }}/src:/app/src - depends_on: - postgres: - condition: service_healthy - redis: - condition: service_healthy - - # Run exactly one of these: each scheduler fires every schedule it finds. - scheduler: - build: - context: {{ build_context }} - dockerfile: {{ backend_dockerfile }} - target: dev - env_file: - - {{ env_file }} - environment: - POSTGRES_SERVER: postgres - CACHE_REDIS_HOST: redis - RATE_LIMITER_REDIS_HOST: redis - TASKIQ_REDIS_HOST: redis - working_dir: /app/src - command: > - taskiq scheduler src.infrastructure.taskiq.scheduler:scheduler - volumes: - - {{ backend_context }}/src:/app/src - depends_on: - postgres: - condition: service_healthy - redis: - condition: service_healthy -{% endif %} - postgres: - image: {{ postgres_image }} - env_file: - - {{ env_file }} - volumes: - - postgres-data:/var/lib/postgresql/data - ports: - - "127.0.0.1:5432:5432" - healthcheck: - test: ["CMD-SHELL", "pg_isready -U \"$${POSTGRES_USER:-postgres}\""] - interval: 5s - timeout: 3s - retries: 10 - - redis: - image: {{ redis_image }} - volumes: - - redis-data:/data - ports: - - "127.0.0.1:6379:6379" - healthcheck: - test: ["CMD", "redis-cli", "ping"] - interval: 5s - timeout: 3s - retries: 10 - -volumes: - postgres-data: - redis-data: diff --git a/cli/src/cli/features/_builtins/deploy/templates/nginx/default.conf.j2 b/cli/src/cli/features/_builtins/deploy/templates/nginx/default.conf.j2 deleted file mode 100644 index 4c06380a..00000000 --- a/cli/src/cli/features/_builtins/deploy/templates/nginx/default.conf.j2 +++ /dev/null @@ -1,33 +0,0 @@ -# Generated by `bp deploy generate nginx`. -# Drop-in nginx vhost in front of the FastAPI app container. - -upstream {{ project_name }}_api { - server api:8000; -} - -server { - listen 80; - server_name _; - - client_max_body_size 25M; - server_tokens off; - - # Forwarded headers. X-Forwarded-For and X-Forwarded-Proto are replaced with what - # nginx saw, dropping whatever the client sent. uvicorn trusts the headers only from - # the compose network (FORWARDED_ALLOW_IPS); crudauth counts hops from the right - # through TRUSTED_PROXY_HOPS. - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $remote_addr; - proxy_set_header X-Forwarded-Proto $scheme; - - # Long-running endpoints (exports, AI, etc.) want generous timeouts. - proxy_connect_timeout 60s; - proxy_send_timeout 300s; - proxy_read_timeout 300s; - - location / { - proxy_pass http://{{ project_name }}_api; - proxy_redirect off; - } -} diff --git a/cli/src/cli/features/_builtins/deploy/templates/nginx/docker-compose.yml.j2 b/cli/src/cli/features/_builtins/deploy/templates/nginx/docker-compose.yml.j2 deleted file mode 100644 index b5863e7d..00000000 --- a/cli/src/cli/features/_builtins/deploy/templates/nginx/docker-compose.yml.j2 +++ /dev/null @@ -1,147 +0,0 @@ -# Generated by `bp deploy generate 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 }} - -services: - # One-shot, and nothing waits on it: run it and only then restart the rest, so a - # migration that fails leaves the old code serving on the old schema. - # docker compose --profile migrate run --rm migrate - migrate: - build: - context: {{ build_context }} - dockerfile: {{ backend_dockerfile }} - target: migrate - env_file: - - {{ env_file }} - environment: - POSTGRES_SERVER: postgres - CONFIRM_PRODUCTION_MIGRATION: "yes" - profiles: ["migrate"] - depends_on: - postgres: - condition: service_healthy - restart: "no" - - api: - build: - context: {{ build_context }} - dockerfile: {{ backend_dockerfile }} - target: prod - env_file: - - {{ env_file }} - 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 }}" - expose: - - "8000" - depends_on: - postgres: - condition: service_healthy - redis: - condition: service_healthy - healthcheck: - test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health/ready').read()"] - interval: 15s - timeout: 5s - retries: 5 - start_period: 20s - restart: unless-stopped -{% if taskiq %} - worker: - build: - context: {{ build_context }} - dockerfile: {{ backend_dockerfile }} - target: prod - env_file: - - {{ env_file }} - environment: - POSTGRES_SERVER: postgres - CACHE_REDIS_HOST: redis - RATE_LIMITER_REDIS_HOST: redis - TASKIQ_REDIS_HOST: redis - working_dir: /app/src - command: taskiq worker src.infrastructure.taskiq.worker:default_broker --workers 2 - depends_on: - postgres: - condition: service_healthy - redis: - condition: service_healthy - restart: unless-stopped - - # Run exactly one of these: each scheduler fires every schedule it finds. - scheduler: - build: - context: {{ build_context }} - dockerfile: {{ backend_dockerfile }} - target: prod - env_file: - - {{ env_file }} - environment: - POSTGRES_SERVER: postgres - CACHE_REDIS_HOST: redis - RATE_LIMITER_REDIS_HOST: redis - TASKIQ_REDIS_HOST: redis - working_dir: /app/src - command: taskiq scheduler src.infrastructure.taskiq.scheduler:scheduler - depends_on: - postgres: - condition: service_healthy - redis: - condition: service_healthy - restart: unless-stopped -{% endif %} - nginx: - image: {{ nginx_image }} - ports: - - "80:80" - volumes: - - ./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro - depends_on: - - api - restart: unless-stopped - - postgres: - image: {{ postgres_image }} - env_file: - - {{ env_file }} - volumes: - - postgres-data:/var/lib/postgresql/data - healthcheck: - test: ["CMD-SHELL", "pg_isready -U \"$${POSTGRES_USER:-postgres}\""] - interval: 10s - timeout: 5s - retries: 10 - restart: unless-stopped - - redis: - image: {{ redis_image }} - command: ["redis-server", "--appendonly", "yes"] - volumes: - - redis-data:/data - healthcheck: - test: ["CMD", "redis-cli", "ping"] - interval: 10s - timeout: 5s - retries: 10 - restart: unless-stopped - -volumes: - postgres-data: - redis-data: - -# The API trusts forwarded headers only from this range, so a client can neither -# claim another address nor say the request arrived over HTTPS. Change both this -# subnet and FORWARDED_ALLOW_IPS together if it clashes with a network you use. -networks: - default: - ipam: - config: - - subnet: "{{ internal_subnet }}" diff --git a/cli/src/cli/features/_builtins/deploy/templates/prod/docker-compose.yml.j2 b/cli/src/cli/features/_builtins/deploy/templates/prod/docker-compose.yml.j2 deleted file mode 100644 index 22bec610..00000000 --- a/cli/src/cli/features/_builtins/deploy/templates/prod/docker-compose.yml.j2 +++ /dev/null @@ -1,126 +0,0 @@ -# Generated by `bp deploy generate 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 }} - -services: - # One-shot, and nothing waits on it: run it and only then restart the rest, so a - # migration that fails leaves the old code serving on the old schema. - # docker compose --profile migrate run --rm migrate - migrate: - build: - context: {{ build_context }} - dockerfile: {{ backend_dockerfile }} - target: migrate - env_file: - - {{ env_file }} - environment: - POSTGRES_SERVER: postgres - CONFIRM_PRODUCTION_MIGRATION: "yes" - profiles: ["migrate"] - depends_on: - postgres: - condition: service_healthy - restart: "no" - - api: - build: - context: {{ build_context }} - dockerfile: {{ backend_dockerfile }} - target: prod - env_file: - - {{ env_file }} - environment: - POSTGRES_SERVER: postgres - CACHE_REDIS_HOST: redis - RATE_LIMITER_REDIS_HOST: redis - TASKIQ_REDIS_HOST: redis - WORKERS: "{{ workers }}" - ports: - - "{{ api_port }}:8000" - depends_on: - postgres: - condition: service_healthy - redis: - condition: service_healthy - healthcheck: - test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health/ready').read()"] - interval: 15s - timeout: 5s - retries: 5 - start_period: 20s - restart: unless-stopped -{% if taskiq %} - worker: - build: - context: {{ build_context }} - dockerfile: {{ backend_dockerfile }} - target: prod - env_file: - - {{ env_file }} - environment: - POSTGRES_SERVER: postgres - CACHE_REDIS_HOST: redis - RATE_LIMITER_REDIS_HOST: redis - TASKIQ_REDIS_HOST: redis - working_dir: /app/src - command: taskiq worker src.infrastructure.taskiq.worker:default_broker --workers 2 - depends_on: - postgres: - condition: service_healthy - redis: - condition: service_healthy - restart: unless-stopped - - # Run exactly one of these: each scheduler fires every schedule it finds. - scheduler: - build: - context: {{ build_context }} - dockerfile: {{ backend_dockerfile }} - target: prod - env_file: - - {{ env_file }} - environment: - POSTGRES_SERVER: postgres - CACHE_REDIS_HOST: redis - RATE_LIMITER_REDIS_HOST: redis - TASKIQ_REDIS_HOST: redis - working_dir: /app/src - command: taskiq scheduler src.infrastructure.taskiq.scheduler:scheduler - depends_on: - postgres: - condition: service_healthy - redis: - condition: service_healthy - restart: unless-stopped -{% endif %} - postgres: - image: {{ postgres_image }} - env_file: - - {{ env_file }} - volumes: - - postgres-data:/var/lib/postgresql/data - healthcheck: - test: ["CMD-SHELL", "pg_isready -U \"$${POSTGRES_USER:-postgres}\""] - interval: 10s - timeout: 5s - retries: 10 - restart: unless-stopped - - redis: - image: {{ redis_image }} - command: ["redis-server", "--appendonly", "yes"] - volumes: - - redis-data:/data - healthcheck: - test: ["CMD", "redis-cli", "ping"] - interval: 10s - timeout: 5s - retries: 10 - restart: unless-stopped - -volumes: - postgres-data: - redis-data: 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_deploy_templates.py b/cli/tests/test_deploy_templates.py deleted file mode 100644 index 131b47e6..00000000 --- a/cli/tests/test_deploy_templates.py +++ /dev/null @@ -1,159 +0,0 @@ -"""What the generated compose files say about running this app behind a proxy.""" - -from pathlib import Path - -import pytest -import yaml -from jinja2 import Environment, FileSystemLoader - -from cli.features._builtins.deploy.feature import DEFAULT_INTERNAL_SUBNET - -TEMPLATES = Path(__file__).resolve().parents[1] / "src/cli/features/_builtins/deploy/templates" - -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 _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 _compose(mode: str, **overrides) -> dict: - return yaml.safe_load(_render(f"{mode}/docker-compose.yml.j2", mode, **overrides)) - - -@pytest.mark.parametrize("mode", ["prod", "nginx"]) -def test_the_api_reports_whether_it_is_ready(mode: str): - """Compose has no way to hold traffic back without one.""" - healthcheck = _compose(mode)["services"]["api"]["healthcheck"] - - assert "/health/ready" in " ".join(healthcheck["test"]) - - -@pytest.mark.parametrize("mode", ["prod", "nginx"]) -def test_the_worker_does_not_run_as_root(mode: str): - """The base stage has no USER, so building the worker from it would run it as root.""" - assert _compose(mode)["services"]["worker"]["build"]["target"] == "prod" - - -def test_behind_nginx_the_app_is_told_how_many_proxies_it_sits_behind(): - """Without this every client looks like the nginx container, and one attacker locks everyone out.""" - api = _compose("nginx")["services"]["api"]["environment"] - - assert api["TRUSTED_PROXY_HOPS"] == "1" - - -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}] - - -def test_nginx_hides_its_version(): - assert "server_tokens off;" in _render("nginx/default.conf.j2") - - -def test_the_local_compose_does_not_claim_a_proxy(): - """Nothing sits in front of it, so trusting forwarded headers would let a client forge its IP.""" - api = _compose("local")["services"]["api"] - - assert "TRUSTED_PROXY_HOPS" not in api.get("environment", {}) - - -def test_the_local_compose_publishes_its_databases_to_the_host_only(): - """Both database ports are bound to the loopback address.""" - services = _compose("local")["services"] - - assert services["postgres"]["ports"] == ["127.0.0.1:5432:5432"] - assert services["redis"]["ports"] == ["127.0.0.1:6379:6379"] - - -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") - - 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") - - assert f'- subnet: "{DEFAULT_INTERNAL_SUBNET}"' in rendered - - -SCHEDULER_COMMAND = "taskiq scheduler src.infrastructure.taskiq.scheduler:scheduler" - - -@pytest.mark.parametrize("mode", ["local", "prod", "nginx"]) -def test_a_project_with_taskiq_gets_one_scheduler(mode: str): - """Every schedule fires once per scheduler, so the stack runs a single one.""" - scheduler = _compose(mode)["services"]["scheduler"] - - assert SCHEDULER_COMMAND in " ".join(scheduler["command"].split()) - assert "deploy" not in scheduler - - -@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"] - - assert "worker" not in services - assert "scheduler" not in services - assert "api" in services - - -@pytest.mark.parametrize("mode", ["prod", "nginx"]) -def test_the_migration_runner_waits_to_be_asked(mode: str): - """A deploy runs it and only then restarts, so a failed migration leaves the old code serving.""" - migrate = _compose(mode)["services"]["migrate"] - - assert migrate["profiles"] == ["migrate"] - assert migrate["build"]["target"] == "migrate" - - -@pytest.mark.parametrize("mode", ["local", "prod", "nginx"]) -def test_nothing_depends_on_a_service_behind_a_profile(mode: str): - """Compose refuses the whole project when a service it starts depends on a profiled one.""" - services = _compose(mode)["services"] - behind_a_profile = {name for name, service in services.items() if service.get("profiles")} - - for name, service in services.items(): - assert behind_a_profile.isdisjoint(service.get("depends_on", {})), name - - -@pytest.mark.parametrize("mode", ["local", "prod", "nginx"]) -def test_the_database_takes_its_credentials_from_the_environment_file(mode: str): - """Compose interpolates ``${VAR}`` from the shell, never from ``env_file``, and - ``environment`` wins over it: a password set in ``backend/.env``, which is where every page - says to set it, was replaced in the container by the literal fallback. - """ - postgres = _compose(mode)["services"]["postgres"] - - assert postgres["env_file"] == ["./backend/.env"] - assert "${" not in yaml.safe_dump(postgres.get("environment", {})) - - -@pytest.mark.parametrize("mode", ["local", "prod", "nginx"]) -def test_the_database_probe_reads_the_user_inside_the_container(mode: str): - """A probe interpolated by compose asks for ``postgres`` whatever ``POSTGRES_USER`` says.""" - probe = " ".join(_compose(mode)["services"]["postgres"]["healthcheck"]["test"]) - - assert "$${POSTGRES_USER" in probe 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/changelog.md b/docs/changelog.md index d9b7307b..af600159 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -44,6 +44,17 @@ ___ [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. + ___ ## 0.20.0 - October 25, 2026 - Composable Features diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index f554740f..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 diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 26c0cb0b..1d80298f 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -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 `cli/` holds the old developer tool, which fastro replaces. 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,7 +136,7 @@ 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**: diff --git a/docs/user-guide/configuration/docker-setup.md b/docs/user-guide/configuration/docker-setup.md index 952397bc..43c719e1 100644 --- a/docs/user-guide/configuration/docker-setup.md +++ b/docs/user-guide/configuration/docker-setup.md @@ -2,8 +2,8 @@ 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. `fastro make deploy local` writes one at the repository root, @@ -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 . diff --git a/docs/user-guide/development.md b/docs/user-guide/development.md index 12a2cf5e..3168a082 100644 --- a/docs/user-guide/development.md +++ b/docs/user-guide/development.md @@ -103,7 +103,7 @@ The repo's `.pre-commit-config.yaml` runs these hooks. A row that names CI says | `pyupgrade` | rewrites to Python 3.11+ syntax | | `yesqa` | removes a `noqa` nothing needs any more | | `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`, `mypy_cli` | local hooks, the same invocations CI uses | +| `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/` | diff --git a/pyproject.toml b/pyproject.toml index 2c4e2011..c62d969d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,36 +1,31 @@ # 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 # -# Each package'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, and `cli` -# has to be importable. So the root's testpaths name the blueprint's tests and nothing else. -# -# 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 = "a07bbc1b0a4a0c894bcd59edf5a602b36e34bae1" } diff --git a/uv.lock b/uv.lock index e0eba0ab..d26e2a0a 100644 --- a/uv.lock +++ b/uv.lock @@ -11,7 +11,6 @@ resolution-markers = [ [manifest] members = [ "fastapi-boilerplate", - "fastapi-boilerplate-cli", "fastapi-boilerplate-workspace", ] @@ -949,32 +948,6 @@ 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" }, -] - -[package.optional-dependencies] -dev = [ - { name = "pytest" }, - { name = "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" From 5885aa3f5ad96e1c6327a16bbebbe69e0ad03f89 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Tue, 17 Nov 2026 23:35:34 -0300 Subject: [PATCH 59/71] give the mailpit tests a 120 second timeout and wait for mailpit to answer smtp and its api before they run, and give the collection-read auth rule its own skip reason when a project has no collection reads --- .../api/v1/test_read_endpoint_auth.py | 20 ++++- .../unit/infrastructure/email/test_senders.py | 89 ++++++++++++++++++- 2 files changed, 105 insertions(+), 4 deletions(-) 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/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.""" From 29bc4d7cacf21de9ed129d5f40049819320f4569 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Tue, 17 Nov 2026 23:45:51 -0300 Subject: [PATCH 60/71] run fastro blueprint verify in ci over every set it builds, one job each, and test that the matrix is those sets and that the testing guide says so --- .github/workflows/tests.yml | 12 +++---- blueprint/tests/test_verify_matrix.py | 51 +++++++++++++++++++++++++++ docs/user-guide/testing.md | 8 ++--- 3 files changed, 61 insertions(+), 10 deletions(-) create mode 100644 blueprint/tests/test_verify_matrix.py diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 19092f81..b0f469aa 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -34,7 +34,7 @@ jobs: - 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/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/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 From 6f7255393d03afcb2c89ceb29ca666520fac4d1f Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Wed, 18 Nov 2026 00:47:47 -0300 Subject: [PATCH 61/71] delete the removal drill and its test, drop it from ci, ruff, blueprint_only and the tarball rules, check the catalog against itself instead, point the docs at fastro blueprint verify, and test that nothing outside the docs names the drill --- .gitattributes | 1 - .github/workflows/linting.yml | 4 +- .github/workflows/type-checking.yml | 6 - .../unit/scripts/test_setup_initial_data.py | 4 +- backend/tests/unit/test_blueprint_catalog.py | 468 +++------- backend/tests/unit/test_removal_drill.py | 256 ------ backend/tests/unit/test_tarball_contents.py | 15 +- blueprint.toml | 2 - blueprint/tests/retired.py | 8 +- blueprint/tests/test_docs_commands.py | 34 +- blueprint/tests/test_observability_recipe.py | 1 - blueprint/tests/test_overlay.py | 2 +- blueprint/tests/test_retired_cli.py | 71 +- docs/changelog.md | 4 + docs/user-guide/composable-features.md | 6 +- tools/removal_drill.py | 823 ------------------ 16 files changed, 233 insertions(+), 1472 deletions(-) delete mode 100644 backend/tests/unit/test_removal_drill.py delete mode 100644 tools/removal_drill.py diff --git a/.gitattributes b/.gitattributes index c4926b32..470dc845 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,4 +1,3 @@ docs/ export-ignore -tools/ export-ignore zensical.toml export-ignore .github/ISSUE_TEMPLATE/ export-ignore diff --git a/.github/workflows/linting.yml b/.github/workflows/linting.yml index 485458da..cf4670bd 100644 --- a/.github/workflows/linting.yml +++ b/.github/workflows/linting.yml @@ -28,10 +28,10 @@ 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 tools blueprint/tests + 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 tools blueprint/tests + 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 diff --git a/.github/workflows/type-checking.yml b/.github/workflows/type-checking.yml index 8d6e7d8c..dae60fa6 100644 --- a/.github/workflows/type-checking.yml +++ b/.github/workflows/type-checking.yml @@ -29,12 +29,6 @@ jobs: ENVIRONMENT: local SECRET_KEY: test-secret-key-for-testing-only - - name: Mypy (tools) - run: uv run --no-sync mypy tools - env: - ENVIRONMENT: local - SECRET_KEY: test-secret-key-for-testing-only - - name: Mypy (blueprint tests) run: uv run --no-sync mypy blueprint/tests env: 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/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index c7986340..f05aa93c 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -1,18 +1,13 @@ -"""The catalog describes this repository, and `tools/removal_drill.py` is what it describes. +"""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 come from the drill, which is the repository's own account of -its features. - -This file goes when `fastro blueprint lint` and `fastro blueprint verify` replace the drill. +and the facts it checks against are the repository's own files. """ import ast import functools import importlib -import importlib.util -import inspect import ipaddress import itertools import keyword @@ -51,18 +46,6 @@ def _catalog() -> dict[str, Any]: return tomllib.load(handle) -@functools.cache -def _drill(): - """The drill's manifest, loaded as a module: its dataclasses need it in ``sys.modules``.""" - spec = importlib.util.spec_from_file_location("removal_drill_manifest", REPO_ROOT / "tools" / "removal_drill.py") - 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 test_the_catalog_parses(): assert _catalog()["blueprint"]["name"] == "fastapi-boilerplate" @@ -346,7 +329,7 @@ def test_no_file_a_project_keeps_imports_a_dependency_it_did_not_select(): assert needed["sqladmin"] == {"admin"} assert needed["aiomcache"] == set(), "an option's dependency is never guaranteed" - for chosen in _selections(_drill()): + for chosen in _selections(): removed = _removed_for(features, chosen) for name, owners in needed.items(): if owners & chosen: @@ -551,7 +534,7 @@ def _hook_paths() -> list[str]: @pytest.mark.parametrize( ("pattern", "heads"), [ - ("^tools/", ["tools"]), + ("^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"]), @@ -1245,13 +1228,11 @@ def _literals(module: Path) -> set[str]: def test_no_test_a_project_receives_names_a_tree_it_does_not_get(): - """A test that reaches for `docs/` or `tools/` is a test no project can run. + """A test that reaches for `docs/` or `blueprint/` is a test no project can run. - `test_removal_drill.py` loads `tools/removal_drill.py`, and `test_baseline.py` read the - migrations guide: both are files a project never receives, and the drill hid it by copying - the whole repository into every project it built. 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/`. + `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 = {} @@ -1270,10 +1251,10 @@ def test_no_test_a_project_receives_names_a_tree_it_does_not_get(): def test_the_things_projects_must_not_receive_are_listed(): - """The catalog, the drill and the docs belong to the blueprint only.""" + """The catalog and the docs belong to the blueprint only.""" listed = set(_catalog()["blueprint"]["blueprint_only"]) - assert {"blueprint/", "blueprint.toml", "fastro.toml", "docs/", "tools/"} <= listed + assert {"blueprint/", "blueprint.toml", "fastro.toml", "docs/"} <= listed assert "backend/tests/unit/test_blueprint_catalog.py" in listed @@ -1285,15 +1266,6 @@ def test_the_docs_reading_tests_stay_in_the_blueprint(): assert f"backend/tests/unit/{name}.py" in listed -def test_the_verify_sets_are_the_drills_presets(): - """`everything` is implied by the spec, and declaring it is an error, so the sets are the other eight.""" - expected = {name: list(features) for name, features in _drill().PRESETS.items() if name != "everything"} - sets = _catalog()["verify"]["sets"] - - assert "everything" not in sets - assert sets == expected - - @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.""" @@ -1302,15 +1274,12 @@ def test_every_preset_and_verify_set_is_named_the_way_the_spec_allows(name: str) 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.""" - requires = _drill().REQUIRES - for name, features in _catalog()["presets"].items(): - for feature in features: - assert set(requires.get(feature, ())) <= set(features), f"{name} is missing what {feature} requires" + assert _closed(features) == set(features), f"{name} is missing what its features require" def test_the_presets_name_features_this_repository_has(): - known = set(_drill().FEATURES) + known = set(_catalog()["features"]) for name, features in _catalog()["presets"].items(): assert set(features) <= known, name @@ -1319,7 +1288,7 @@ def test_the_presets_name_features_this_repository_has(): def test_full_is_every_feature(): - assert sorted(_catalog()["presets"]["full"]) == sorted(_drill().FEATURES) + assert sorted(_catalog()["presets"]["full"]) == sorted(_catalog()["features"]) ONE_OF_EACH = {"root_routers", "docs_guard", "email_sender", "cache_decorator"} @@ -1350,9 +1319,9 @@ def _binding(entry: str) -> tuple[str, str, str]: 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: the drill merges names from one module - into a single statement and wraps long ones over several lines, and neither shape - contains the single-name line a substring check would look for. + 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: @@ -1406,21 +1375,6 @@ def test_the_points_a_project_may_fill_once_are_the_ones_rendered_as_a_value(): assert single == ONE_OF_EACH -def test_the_database_checks_belong_to_no_feature(): - """The drill wires them whatever is selected, so the catalog gives them to core.""" - core = _catalog()["core"]["contributes"]["critical_readiness"] - with_nothing_selected = _drill()._wiring_hooks(set()) - rendered = with_nothing_selected.split("CRITICAL_READINESS_CHECKS: tuple[ReadinessCheck, ...] = (")[1] - - assert [_ref(entry)[2] for entry in core] == [name.strip() for name in rendered.split(")")[0].split(",") if name.strip()] - - -@pytest.mark.parametrize("entry", _catalog()["core"]["contributes"]["critical_readiness"]) -def test_every_core_contribution_is_imported_the_way_the_drill_imports_it(entry: str): - """The names alone would accept a ref that kept the alias and changed the module.""" - assert _binding(entry) in _bindings(_drill()._wiring_hooks(set())) - - @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.""" @@ -1429,23 +1383,23 @@ def test_every_core_contribution_names_something_that_exists(entry: str): assert _defines(module, attribute), entry -def test_the_import_reader_sees_a_name_the_drill_merges(): - """Two names from one module become one statement, whose second name no line contains.""" - bindings = _bindings(_drill()._wiring_hooks({"accounts"})) +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_the_drill_wraps(): - """The composition import is written over several lines, so no single line holds it.""" - bindings = _bindings(_drill()._wiring_hooks(set())) +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" -"""The drill deletes it with the admin feature; the catalog's `[[wiring]]` entry omits it instead.""" +"""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]]: @@ -1463,40 +1417,93 @@ def _kept_by_the_catalog(features: dict[str, Any], chosen: set[str]) -> set[str] for name, feature in features.items() if name in chosen for path, condition in _declared(feature) - if condition is None or condition in chosen + if condition is None or _true(condition, chosen) } -def _kept_by_the_drill(manifest: Any, chosen: set[str]) -> set[str]: - """What `build` leaves on disk: a combination path needs both of its features.""" - kept: set[str] = set() - for name, feature in manifest.FEATURES.items(): - if name not in chosen: - continue +@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"}), + ], +) +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) - kept.update(path for path in feature.paths if path != GENERATED_BY_WIRING) - for partner, paths in feature.combination_paths.items(): - if partner in chosen: - kept.update(paths) - return kept +def _local_names(point: str, chosen: set[str]) -> list[str]: + return [_ref(entry["ref"])[2] for entry in _contributed(_catalog(), point, chosen)] -def _selections(manifest: Any) -> list[set[str]]: +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_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 = [] - for size in range(len(manifest.FEATURES) + 1): - for combination in itertools.combinations(manifest.FEATURES, size): - selection = manifest._selected_from(combination) + 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_the_features_are_the_ones_the_drill_knows(): - """In the drill's order: spec 6.2 hands templates the selection in catalog order.""" - assert list(_catalog()["features"]) == list(_drill().FEATURES) +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"])) @@ -1510,21 +1517,13 @@ def test_every_feature_is_declared_the_way_the_spec_asks(name: str): assert feature["group"] in {"Accounts", "Operations"} -def test_every_feature_requires_what_the_drill_says_it_requires(): - """A requires that drifts would generate a project whose imports have nothing to bind.""" - requires = _drill().REQUIRES - - for name, feature in _catalog()["features"].items(): - assert list(feature.get("requires", ())) == list(requires.get(name, ())) - - @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 _drill().FEATURES + assert condition in _catalog()["features"] assert condition != name @@ -1563,28 +1562,10 @@ 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 _drill().FEATURES["admin"].paths + assert GENERATED_BY_WIRING in [entry["path"] for entry in _entries()] assert GENERATED_BY_WIRING not in declared -def test_every_selection_keeps_the_files_the_drill_keeps(): - """The catalog gives a shared file to the feature whose subtree holds it, and the drill to both. - - `src/modules/user/admin.py` is admin's work inside accounts' package, and the drill lists it - under both. One declaration owns it here, so what's compared is the file surviving a - selection, not which feature spoke for it. - """ - manifest = _drill() - features = _catalog()["features"] - - for chosen in _selections(manifest): - assert _kept_by_the_catalog(features, chosen) == _kept_by_the_drill(manifest, chosen), sorted(chosen) - - -TOOLCHAIN_ONLY = {"PATH", "PYTHONPATH", "HOME"} -"""What the drill's environment holds beyond the settings: paths, not configuration.""" - - 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 @@ -1599,16 +1580,13 @@ def test_the_app_the_verification_imports_is_this_project_s_own(): def test_the_toolchain_environment_is_what_the_app_needs_to_import(): - """Spec 2.12: names and string values only. These are the settings the drill sets itself - before it imports anything, and 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. + """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"] - source = inspect.getsource(_drill().check) - set_by_the_drill = set(re.findall(r'^\s+"([A-Z][A-Z0-9_]*)":', source, re.M)) - TOOLCHAIN_ONLY - assert set(declared) == set_by_the_drill + 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 @@ -1617,59 +1595,6 @@ def test_the_toolchain_environment_is_what_the_app_needs_to_import(): assert declared["SECRET_KEY"] not in ENV_EXAMPLE.read_text(), "not the example's placeholder" -POINTS: dict[str, tuple[str, str]] = { - "routers": ("_wiring_app", "ROUTER_MOUNTS"), - "root_routers": ("_wiring_app", "ROOT_ROUTERS"), - "api_throttle": ("_wiring_app", "API_THROTTLE"), - "lifecycles": ("_wiring_app", "LIFECYCLES"), - "installers": ("_wiring_app", "INSTALLERS"), - "docs_guard": ("_wiring_app", "DOCS_GUARD"), - "settings": ("_wiring_settings", "Settings"), - "permission_sources": ("_wiring_hooks", "PERMISSION_SOURCES"), - "rate_limit_resolvers": ("_wiring_hooks", "RATE_LIMIT_RESOLVERS"), - "tier_delete_guards": ("_wiring_hooks", "TIER_DELETE_GUARDS"), - "tier_delete_releases": ("_wiring_hooks", "TIER_DELETE_RELEASES"), - "critical_readiness": ("_wiring_hooks", "CRITICAL_READINESS_CHECKS"), - "informational_readiness": ("_wiring_hooks", "INFORMATIONAL_READINESS_CHECKS"), - "user_model": ("_wiring_models", "UserModelExtensions"), - "user_schema": ("_wiring_models", "UserSchemaExtensions"), - "admin_views": ("_wiring_admin", "ADMIN_VIEWS"), - "email_sender": ("_wiring_email", "EMAIL_SENDER"), - "cache_decorator": ("_wiring_cache", "cached"), - "task_modules": ("_wiring_tasks", "TASK_MODULES"), - "table_modules": ("_wiring_tables", "TABLE_MODULES"), - "extra_transports": ("_wiring_transports", "EXTRA_TRANSPORTS"), - "seeders": ("_seeders", "SEEDERS"), - "test_plugins": ("_tests_wiring", "PYTEST_PLUGINS"), -} -"""Where the drill writes each point: the generator, and the name it assigns or defines.""" - - -def _slot_of(point: str) -> dict[str, Any]: - """The one slot that collects this point, which `[[wiring]]` declares exactly once.""" - slots: list[dict[str, Any]] = [ - slot for entry in _catalog()["wiring"] for slot in entry["slots"] if slot.get("point") == point - ] - assert len(slots) == 1, point - - return slots[0] - - -def _fallback_of(point: str) -> str | None: - """How a point renders with nothing contributed: an expression, or a ref's local name.""" - slot = _slot_of(point) - fallback = slot.get("fallback") - if fallback is None: - return None - - return _ref(fallback)[2] if slot["kind"] in {"class", "reexport"} else fallback - - -def _appended_to(point: str) -> list[str]: - """The bases a `class` slot always adds last, by the name they are bound under.""" - return [_ref(ref)[2] for ref in _slot_of(point).get("append", ())] - - def _true(condition: str, chosen: set[str]) -> bool: """Whether a spec 1.3 condition holds for this selection.""" tokens = re.findall(r"\(|\)|[^\s()]+", condition) @@ -1751,14 +1676,6 @@ def _contributed(catalog: dict[str, Any], point: str, chosen: set[str]) -> list[ return [table for *_, table in sorted(collected, key=lambda entry: entry[:3])] -def _named(entry: dict[str, Any]) -> Any: - """The local name a contribution binds, or the literal it contributes.""" - if "value" in entry: - return entry["value"] - - return _ref(entry["ref"])[2] - - 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: @@ -1772,69 +1689,6 @@ def _defined(source: str, name: str) -> ast.AST | None: return None -def _leading_name(element: ast.AST) -> Any: - """What a rendered item is built around: ``RouterMount(users_router, …)`` is ``users_router``.""" - if isinstance(element, ast.Constant): - return element.value - if isinstance(element, ast.Name): - return element.id - if isinstance(element, ast.Call): - return _leading_name(element.args[0]) if element.args else _leading_name(element.func) - - raise AssertionError(ast.unparse(element)) - - -def _rendered(source: str, point: str, name: str) -> list[Any]: - """The names the drill rendered into this point, in the order it wrote them.""" - if _slot_of(point)["kind"] == "reexport": - fallback, _, _ = _binding(_slot_of(point)["fallback"]) - bound = [module for module, _, alias in _bindings(source) if alias == name] - - return [] if bound == [fallback] else [name] - - defined = _defined(source, name) - assert defined is not None, name - - if isinstance(defined, ast.ClassDef): - bases = [base.id for base in defined.bases if isinstance(base, ast.Name)] - appended = _appended_to(point) - if appended: - assert bases[-len(appended) :] == appended, bases - bases = bases[: -len(appended)] - - return [] if bases == [_fallback_of(point)] else bases - - if isinstance(defined, ast.Tuple | ast.List): - return [_leading_name(element) for element in defined.elts] - - return [] if ast.unparse(defined) == _fallback_of(point) else [_leading_name(defined)] - - -def _written_for(manifest: Any, generator: str, chosen: set[str]) -> str: - written: str = getattr(manifest, generator)(chosen) - - return written - - -def _constant(node: ast.expr) -> Any: - """The value of a rendered literal, such as a mount's prefix or its throttle flag.""" - assert isinstance(node, ast.Constant), ast.unparse(node) - - return node.value - - -def test_every_declared_point_is_one_the_drill_writes_somewhere(): - """A point missing from this table would skip the comparison below without saying so.""" - assert set(POINTS) == set(_catalog()["points"]) - - -@pytest.mark.parametrize("point", sorted(POINTS)) -def test_every_point_is_written_by_a_generator_the_drill_has(point: str): - generator, _ = POINTS[point] - - assert hasattr(_drill(), generator) - - 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() @@ -1866,77 +1720,17 @@ def test_a_point_a_project_fills_once_never_receives_two_contributions(): catalog = _catalog() single = {name for name, point in catalog["points"].items() if point["cardinality"] == "one"} - for chosen in _selections(_drill()): + for chosen in _selections(): for point in single: assert len(_contributed(catalog, point, chosen)) <= 1, (point, sorted(chosen)) -@pytest.mark.parametrize("point", sorted(POINTS)) -def test_the_catalog_says_what_the_drill_renders(point: str): - """For every selection a project could carry, what reaches a point is what the drill wrote. - - All 164 of them, not the verify sets: a set builds and tests a project, so the sets are - few, and a generator is a function of the selection alone, so it costs nothing to ask it - about combinations no set builds. - """ - catalog = _catalog() - manifest = _drill() - generator, name = POINTS[point] - - for chosen in _selections(manifest): - expected = [_named(entry) for entry in _contributed(catalog, point, chosen)] - if generator == "_wiring_admin" and "admin" not in chosen: - assert expected == [], sorted(chosen) - continue - - assert _rendered(_written_for(manifest, generator, chosen), point, name) == expected, sorted(chosen) - - -def test_every_mounted_router_is_mounted_where_the_drill_mounts_it(): - """The prefix and the throttle are the catalog's to carry now, so they are compared too.""" - catalog = _catalog() - manifest = _drill() - - for chosen in _selections(manifest): - declared = [(_named(entry), entry["prefix"], entry["throttled"]) for entry in _contributed(catalog, "routers", chosen)] - mounts = _defined(_written_for(manifest, "_wiring_app", chosen), "ROUTER_MOUNTS") - assert isinstance(mounts, ast.Tuple) - - rendered = [ - ( - _leading_name(element.args[0]), - _constant(element.args[1]), - next(_constant(word.value) for word in element.keywords if word.arg == "throttled"), - ) - for element in mounts.elts - if isinstance(element, ast.Call) - ] - - assert rendered == declared, sorted(chosen) - - -def test_every_contribution_is_imported_the_way_the_drill_imports_it(): - """A ref that kept the local name and changed the module would render the same line.""" - catalog = _catalog() - manifest = _drill() - everything = set(manifest.FEATURES) - - for point, (generator, _) in POINTS.items(): - source = _written_for(manifest, generator, everything) - bound = _bindings(source) - for entry in _contributed(catalog, point, everything): - if "value" in entry: - continue - - assert _binding(entry["ref"]) in bound, (point, entry) - - 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(_written_for(_drill(), "_wiring_transports", everything), "EXTRA_TRANSPORTS") + 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) @@ -2325,13 +2119,6 @@ def test_every_option_marks_the_line_it_rewrites(feature: str, option: str): """Spec 2.6. A kind the engine doesn't know would be a slot nothing renders.""" -def _written_by_build(manifest: Any) -> list[str]: - """The files `build` writes, read out of its source rather than listed again here.""" - source = inspect.getsource(manifest.build) - - return re.findall(r'\(project / "([^"]+)"\)\.write_text', source) - - def _entries() -> list[dict[str, Any]]: return list(_catalog()["wiring"]) @@ -2349,14 +2136,6 @@ def _annotated(source: str, name: str) -> str | None: return None -def test_the_wiring_entries_are_the_files_the_drill_writes(): - """One entry per generated file, both ways. The entries' order carries nothing, so it is free.""" - written = _written_by_build(_drill()) - - assert sorted(entry["path"] for entry in _entries()) == sorted(written) - assert len(written) == 12 - - @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.""" @@ -2430,10 +2209,8 @@ def test_every_point_a_project_fills_once_is_rendered_as_one_value(): 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")) - build = inspect.getsource(_drill().build) assert admin["if"] == "admin" - assert 'if "admin" in chosen:' in build assert [entry.get("if") for entry in _entries()].count(None) == 11 @@ -2570,12 +2347,6 @@ def test_every_generated_file_carries_its_doc_and_then_the_header(path: str): assert _docstring(_committed(path)) == f"{entry['doc'].strip()}\n\n{header.strip()}\n" -@pytest.mark.parametrize("path", [entry["path"] for entry in _entries()]) -def test_no_generated_file_names_the_drill(path: str): - """The header names fastro as the author, and the drill goes in B3: two authors is one too many.""" - assert "removal_drill" not in _committed(path), path - - 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)) @@ -2585,31 +2356,6 @@ def test_the_hand_written_module_says_who_writes_the_ones_beside_it(): assert "fastro" in docstring assert "blueprint.toml" in docstring assert "imports and literals" in docstring - assert "removal_drill" not in docstring - - -@pytest.mark.parametrize("path", [entry["path"] for entry in _entries()]) -def test_the_catalog_accounts_for_what_the_file_imports_for_every_selection(path: str): - """The fallbacks, where the committed files cannot reach: nothing falls back with all nine. - - `fallback_imports`, the pydantic base and the uncached decorator are only written into a - project that left the feature out, so only a smaller selection compares them. - """ - catalog = _catalog() - manifest = _drill() - entry = next(entry for entry in _entries() if entry["path"] == path) - generator = next( - drill_generator - for point, (drill_generator, _) in POINTS.items() - if any(slot.get("point") == point for slot in entry["slots"]) - ) - - for chosen in _selections(manifest): - if generator == "_wiring_admin" and "admin" not in chosen: - continue - - written = _bindings(_written_for(manifest, generator, chosen)) - assert _declared_bindings(catalog, entry, chosen) == written, sorted(chosen) LINE_LENGTH = _catalog()["wiring_defaults"]["line_length"] @@ -2859,11 +2605,11 @@ def test_every_selection_carries_the_commands_whose_module_it_keeps(): project that cannot run it is worse than no command, and one a project could run but is never offered is work thrown away. """ - manifest = _drill() + features = _catalog()["features"] owned = _owned_paths() - for chosen in _selections(manifest): - kept = _kept_by_the_drill(manifest, chosen) + 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 diff --git a/backend/tests/unit/test_removal_drill.py b/backend/tests/unit/test_removal_drill.py deleted file mode 100644 index 0a9f52a2..00000000 --- a/backend/tests/unit/test_removal_drill.py +++ /dev/null @@ -1,256 +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_a_project_is_kept_from_everything_the_catalog_reserves(): - """A project that received the catalog, this drill or the docs would run the blueprint's own - tests against itself, and they describe a repository it is not. Spec 1.1: an entry with a - trailing slash reserves the whole subtree, not just the directory.""" - reserved = drill.blueprint_only() - - assert reserved, "the catalog reserves nothing, so this reads it wrongly" - for entry in reserved: - assert drill.withheld(entry.rstrip("/")), entry - if entry.endswith("/"): - assert drill.withheld(f"{entry}somewhere/deeper.py"), entry - - -def test_nothing_a_drill_step_needs_is_kept_from_the_project(): - """Every step runs from `backend/`, and reads its configuration and its tests from there.""" - for needed in ("backend", "backend/pyproject.toml", "backend/tests/conftest.py", "backend/src/wiring/app.py"): - assert not drill.withheld(needed), needed - - -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 diff --git a/backend/tests/unit/test_tarball_contents.py b/backend/tests/unit/test_tarball_contents.py index 84b82b84..406d0c14 100644 --- a/backend/tests/unit/test_tarball_contents.py +++ b/backend/tests/unit/test_tarball_contents.py @@ -1,9 +1,9 @@ """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, the -removal drill and the issue templates are things to read or run in this repository, not things -a reader builds the project from. +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 @@ -13,7 +13,7 @@ REPO_ROOT = Path(__file__).resolve().parents[3] -LEFT_OUT = (".github/ISSUE_TEMPLATE/", "docs/", "tools/", "zensical.toml") +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") @@ -57,3 +57,10 @@ 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/blueprint.toml b/blueprint.toml index bf1bd229..90e26442 100644 --- a/blueprint.toml +++ b/blueprint.toml @@ -20,14 +20,12 @@ blueprint_only = [ "backend/tests/unit/test_docs_scripts.py", "backend/tests/unit/test_docs_wiring.py", "backend/tests/unit/test_image_contents.py", - "backend/tests/unit/test_removal_drill.py", "backend/tests/unit/test_tarball_contents.py", "blueprint/", "blueprint.toml", "docs/", "fastro.toml", "pyproject.toml", - "tools/", "uv.lock", "zensical.toml", ] diff --git a/blueprint/tests/retired.py b/blueprint/tests/retired.py index 78ea626c..c0bbda10 100644 --- a/blueprint/tests/retired.py +++ b/blueprint/tests/retired.py @@ -1,4 +1,5 @@ -"""The developer CLI this repository used to ship, as the scans that keep it gone read it. +"""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. """ @@ -24,6 +25,11 @@ """The old package as a word: its folder, a path into it, its module, its distribution. Not `redis-cli`, `fastro.cli` or "CLI".""" +OLD_DRILL = "removal" + "_drill" + +NAMES_OLD_DRILL = re.compile(rf"{OLD_DRILL}|\b{OLD_COMMAND}-and-fastro\b") +"""The drill's module, its test, or the directory it left out of the copies it built.""" + def tracked_text() -> 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.""" diff --git a/blueprint/tests/test_docs_commands.py b/blueprint/tests/test_docs_commands.py index ed342d1a..514b6b45 100644 --- a/blueprint/tests/test_docs_commands.py +++ b/blueprint/tests/test_docs_commands.py @@ -9,7 +9,10 @@ import pytest import typer.main from fastro.cli import app -from retired import OLD_COMMAND, REPO_ROOT, RUNS_OLD_COMMAND, shown_pages +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, shown_pages FASTRO = typer.main.get_command(app) @@ -97,6 +100,15 @@ def test_no_page_a_reader_sees_runs_the_retired_command(): 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()) @@ -164,3 +176,23 @@ def test_every_root_sync_a_page_shows_installs_the_backend(): 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_observability_recipe.py b/blueprint/tests/test_observability_recipe.py index 692bcb45..1c2a28e1 100644 --- a/blueprint/tests/test_observability_recipe.py +++ b/blueprint/tests/test_observability_recipe.py @@ -176,7 +176,6 @@ def test_the_feature_section_names_the_tables_a_feature_is_declared_with(): assert feature, section name = feature[1] - assert "tools/removal_drill.py" not in section assert "`blueprint.toml`" in section and "`[app]`" in section assert "`paths`" in section and f"`[features.{name}.contributes]`" in section assert any( diff --git a/blueprint/tests/test_overlay.py b/blueprint/tests/test_overlay.py index 19b417fa..66a5a7f9 100644 --- a/blueprint/tests/test_overlay.py +++ b/blueprint/tests/test_overlay.py @@ -292,7 +292,7 @@ def test_the_workflow_installs_the_project_rather_than_this_workspace(): def test_every_pre_commit_hook_watches_paths_a_project_has(): - """A `files:` pattern naming `tools/` or `docs/` is a hook over nothing: those are the + """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] diff --git a/blueprint/tests/test_retired_cli.py b/blueprint/tests/test_retired_cli.py index f3ff0cbb..f33ead5a 100644 --- a/blueprint/tests/test_retired_cli.py +++ b/blueprint/tests/test_retired_cli.py @@ -1,19 +1,41 @@ -"""Nothing outside the history names the developer tool's old package or the command it shipped.""" +"""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 retired import NAMES_OLD_COMMAND, NAMES_OLD_PACKAGE, OLD_COMMAND, OLD_PACKAGE, REPO_ROOT, tracked_text +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, + tracked_text, +) -NEEDLES = {"package": NAMES_OLD_PACKAGE, "command": NAMES_OLD_COMMAND} +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.""" @@ -41,7 +63,7 @@ def _hits() -> dict[tuple[str, str], list[str]]: return hits -def test_no_file_names_the_old_package_or_its_command(): +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 == [] @@ -88,13 +110,46 @@ def test_the_command_needle(line: str, named: bool): assert bool(NAMES_OLD_COMMAND.search(line)) is named -def _old_and_new_commands() -> list[tuple[str, str]]: - """The pairs the changelog's entry for the package's removal gives, old command first.""" +@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] - removed = " ".join(unreleased.split("#### Removed", 1)[1].split("\n#### ", 1)[0].split()) - return re.findall(rf"`{OLD_COMMAND} ([^`]+)` is `fastro ([^`]+)`", removed) + 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(): diff --git a/docs/changelog.md b/docs/changelog.md index af600159..87fc1088 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -54,6 +54,10 @@ ___ `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. ___ diff --git a/docs/user-guide/composable-features.md b/docs/user-guide/composable-features.md index 9d05a6e2..943ccbf6 100644 --- a/docs/user-guide/composable-features.md +++ b/docs/user-guide/composable-features.md @@ -109,9 +109,9 @@ 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 scratch copies ``` The presets run in CI as a matrix: diff --git a/tools/removal_drill.py b/tools/removal_drill.py deleted file mode 100644 index 2d689f9d..00000000 --- a/tools/removal_drill.py +++ /dev/null @@ -1,823 +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 -import tomllib -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 blueprint_only() -> tuple[str, ...]: - """The paths a project never receives, as `blueprint.toml` lists them.""" - with (REPO / "blueprint.toml").open("rb") as handle: - return tuple(tomllib.load(handle)["blueprint"]["blueprint_only"]) - - -def withheld(path: str) -> bool: - """Whether a project is kept from receiving this path: a trailing slash means its subtree.""" - return any(path == entry.rstrip("/") or (entry.endswith("/") and path.startswith(entry)) for entry in blueprint_only()) - - -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 entry in blueprint_only(): - _remove(project / entry.rstrip("/")) - - 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()) From 1c72c0c697439385acc5d42420b506e9c36586c5 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Wed, 18 Nov 2026 00:53:34 -0300 Subject: [PATCH 62/71] point the composable features steps, its ci table and the new module steps at blueprint.toml and fastro blueprint verify instead of the deleted drill, and test what they say --- backend/tests/unit/test_docs_wiring.py | 41 ++++++++++++++++++++++++-- docs/user-guide/composable-features.md | 22 ++++++++------ docs/user-guide/project-structure.md | 2 +- 3 files changed, 53 insertions(+), 12 deletions(-) diff --git a/backend/tests/unit/test_docs_wiring.py b/backend/tests/unit/test_docs_wiring.py index 85fbd3b8..9f16ff07 100644 --- a/backend/tests/unit/test_docs_wiring.py +++ b/backend/tests/unit/test_docs_wiring.py @@ -19,6 +19,11 @@ 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]: return sorted(path.name for path in WIRING.glob("*.py") if path.name != "__init__.py") @@ -61,9 +66,41 @@ def test_the_diagram_draws_every_module_of_the_composition_root(): 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.""" - with (REPO_ROOT / "blueprint.toml").open("rb") as handle: - sets = tomllib.load(handle)["verify"]["sets"] + 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] diff --git a/docs/user-guide/composable-features.md b/docs/user-guide/composable-features.md index 943ccbf6..1e84676d 100644 --- a/docs/user-guide/composable-features.md +++ b/docs/user-guide/composable-features.md @@ -111,12 +111,13 @@ RabbitMQ one where the taskiq feature is present): ```sh 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 scratch copies +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 +129,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/project-structure.md b/docs/user-guide/project-structure.md index 9694c951..97e44b3f 100644 --- a/docs/user-guide/project-structure.md +++ b/docs/user-guide/project-structure.md @@ -346,7 +346,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` From ccb2a7451f48e5960a1fa04c31f4a39481720bef Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Wed, 18 Nov 2026 10:53:33 -0300 Subject: [PATCH 63/71] read settings from the environment and the env file when each class is built instead of at import, through an EnvSettings base that keeps starlette's flag, number and literal-file rules, default CREATE_TABLES_ON_STARTUP from the environment the settings are built with, and pin every value against tables taken at the last commit --- backend/src/infrastructure/auth/settings.py | 87 +++---- backend/src/infrastructure/cache/settings.py | 30 +-- backend/src/infrastructure/config/base.py | 245 ++++++++++++------ .../src/infrastructure/ratelimit/settings.py | 12 +- backend/src/infrastructure/taskiq/settings.py | 29 +-- backend/src/interfaces/admin/settings.py | 10 +- backend/src/modules/api_keys/settings.py | 9 +- backend/src/modules/tier/settings.py | 8 +- backend/tests/settings_defaults.py | 31 +-- .../unit/infrastructure/config/conftest.py | 23 ++ .../unit/infrastructure/config/defaults.json | 138 ++++++++++ .../infrastructure/config/example_values.json | 138 ++++++++++ .../infrastructure/config/test_env_file.py | 16 +- .../config/test_settings_build.py | 209 +++++++++++++++ .../config/test_settings_tables.py | 38 +++ backend/tests/unit/test_blueprint_catalog.py | 2 +- blueprint.toml | 3 + blueprint/tests/test_docs_settings.py | 131 ++++++++++ docs/changelog.md | 15 ++ docs/user-guide/configuration/index.md | 16 +- .../configuration/settings-classes.md | 93 ++++--- docs/user-guide/development.md | 7 +- 22 files changed, 1018 insertions(+), 272 deletions(-) create mode 100644 backend/tests/unit/infrastructure/config/conftest.py create mode 100644 backend/tests/unit/infrastructure/config/defaults.json create mode 100644 backend/tests/unit/infrastructure/config/example_values.json create mode 100644 backend/tests/unit/infrastructure/config/test_settings_build.py create mode 100644 backend/tests/unit/infrastructure/config/test_settings_tables.py create mode 100644 blueprint/tests/test_docs_settings.py 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/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/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/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/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/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_build.py b/backend/tests/unit/infrastructure/config/test_settings_build.py new file mode 100644 index 00000000..d4b60b8d --- /dev/null +++ b/backend/tests/unit/infrastructure/config/test_settings_build.py @@ -0,0 +1,209 @@ +"""Settings read the environment and the environment file when they're built, not when imported.""" + +from pathlib import Path + +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(): + with pytest.raises(ValidationError): + Settings(SECRET_KEYY="x") + + +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, Settings): + 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/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index f05aa93c..baf6d8dd 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -257,7 +257,7 @@ def test_the_two_the_database_needs_are_the_blueprint_s_to_declare(): asked = requires("sqlalchemy") or () base = (REPO_ROOT / "backend/src/infrastructure/config/base.py").read_text() - assert 'POSTGRES_ASYNC_PREFIX", default="postgresql+asyncpg://"' in base + 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" diff --git a/blueprint.toml b/blueprint.toml index 90e26442..bdf4c08b 100644 --- a/blueprint.toml +++ b/blueprint.toml @@ -14,6 +14,9 @@ blueprint_only = [ "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", 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/docs/changelog.md b/docs/changelog.md index 87fc1088..ce6c084c 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -12,6 +12,21 @@ ___ #### 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. - **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 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..d43de27b 100644 --- a/docs/user-guide/configuration/settings-classes.md +++ b/docs/user-guide/configuration/settings-classes.md @@ -1,15 +1,11 @@ # 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 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. 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 class Settings( @@ -78,19 +74,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 +107,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 +118,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 +130,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 +162,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 +189,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 +229,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`. diff --git a/docs/user-guide/development.md b/docs/user-guide/development.md index 3168a082..eb099b26 100644 --- a/docs/user-guide/development.md +++ b/docs/user-guide/development.md @@ -395,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`. From b6e910a09e578f88dd5a74ea8811ee07f4e85f82 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Wed, 18 Nov 2026 15:04:48 -0300 Subject: [PATCH 64/71] keep the settings build tests type-clean in every selection by passing the misspelt name through a dict and composing the old-style class with CoreSettings --- .../unit/infrastructure/config/test_settings_build.py | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/backend/tests/unit/infrastructure/config/test_settings_build.py b/backend/tests/unit/infrastructure/config/test_settings_build.py index d4b60b8d..476aacd7 100644 --- a/backend/tests/unit/infrastructure/config/test_settings_build.py +++ b/backend/tests/unit/infrastructure/config/test_settings_build.py @@ -1,6 +1,7 @@ """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 @@ -81,8 +82,10 @@ def test_a_partial_class_ignores_the_names_other_classes_read(tmp_path: Path): def test_a_misspelt_name_handed_to_the_constructor_is_refused(): + misspelt: dict[str, Any] = {"SECRET_KEYY": "x"} + with pytest.raises(ValidationError): - Settings(SECRET_KEYY="x") + Settings(**misspelt) def test_a_bad_environment_is_reported_without_the_other_settings(monkeypatch: pytest.MonkeyPatch): @@ -168,7 +171,7 @@ def test_a_class_written_the_old_way_still_composes_and_reads_its_variable(monke class OldStyle(BaseSettings): OLD_STYLE_VALUE: str = facade.config("OLD_STYLE_VALUE", default="declared") - class Composed(OldStyle, Settings): + class Composed(OldStyle, CoreSettings): pass monkeypatch.setenv("OLD_STYLE_VALUE", "from the environment") From decd2f9fbed2722e6b6e4044a7acd62a8b0af607 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Wed, 18 Nov 2026 15:04:54 -0300 Subject: [PATCH 65/71] sign auth_client, auth_client_2 and superuser_auth_client in for real, each with its own client, session and csrf token, instead of overwriting the shared dependency overrides, and test that the two clients are two users at once --- backend/tests/fixtures/accounts.py | 101 +++++++----------- .../integration/api/v1/api_keys/test_read.py | 7 +- .../integration/api/v1/users/test_delete.py | 15 ++- .../integration/auth/test_two_clients.py | 24 +++++ 4 files changed, 78 insertions(+), 69 deletions(-) create mode 100644 backend/tests/integration/auth/test_two_clients.py diff --git a/backend/tests/fixtures/accounts.py b/backend/tests/fixtures/accounts.py index b08a397a..4084d064 100644 --- a/backend/tests/fixtures/accounts.py +++ b/backend/tests/fixtures/accounts.py @@ -1,21 +1,17 @@ """Fixtures of the accounts feature: users, and clients signed in as them.""" import time +from collections.abc import AsyncIterator 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 @@ -100,72 +96,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 override_get_current_principal(): - return _principal_for(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. - 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 override_get_current_user(): - return test_superuser - - async def override_get_current_principal(): - return _principal_for(test_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_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/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_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"] From ec01a8fda0f8861b64173f8a5694d8b3c55e0ac6 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Thu, 19 Nov 2026 18:03:12 -0300 Subject: [PATCH 66/71] pin fastro at the commit that replaces the legacy deploy command with fastro make, declare the deploy modes, move the nginx config under the nginx mode's own nginx directory, and test the fastro page through fastro make deploy --- blueprint.toml | 1 + .../deploy/nginx/{ => nginx}/default.conf.j2 | 0 blueprint/tests/retired.py | 3 + blueprint/tests/test_deploy_generator.py | 53 +-- blueprint/tests/test_deploy_templates.py | 4 +- blueprint/tests/test_docs_commands.py | 28 +- blueprint/tests/test_fastro_page.py | 325 +++++++++++++----- blueprint/tests/test_retired_cli.py | 5 +- docs/changelog.md | 8 + docs/user-guide/fastro.md | 42 ++- pyproject.toml | 2 +- 11 files changed, 318 insertions(+), 153 deletions(-) rename blueprint/templates/deploy/nginx/{ => nginx}/default.conf.j2 (100%) diff --git a/blueprint.toml b/blueprint.toml index bdf4c08b..b4c985f6 100644 --- a/blueprint.toml +++ b/blueprint.toml @@ -708,6 +708,7 @@ literal = true [generators.deploy] templates = "blueprint/templates/deploy" +modes = ["local", "prod", "nginx"] [generators.deploy.params.api_port] type = "int" diff --git a/blueprint/templates/deploy/nginx/default.conf.j2 b/blueprint/templates/deploy/nginx/nginx/default.conf.j2 similarity index 100% rename from blueprint/templates/deploy/nginx/default.conf.j2 rename to blueprint/templates/deploy/nginx/nginx/default.conf.j2 diff --git a/blueprint/tests/retired.py b/blueprint/tests/retired.py index c0bbda10..ef3b8061 100644 --- a/blueprint/tests/retired.py +++ b/blueprint/tests/retired.py @@ -19,6 +19,9 @@ 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"(? click.Command: - group = FASTRO - assert isinstance(group, click.Group) - make = group.commands["make"] - assert isinstance(make, click.Group) - - return make.commands["deploy"] - -def _params() -> dict[str, click.Parameter]: - return {str(param.name): param for param in _make_deploy().params} - - -def test_the_deploy_modes_are_the_ones_fastro_takes(): +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"] - mode = _params()["mode"] - assert isinstance(mode.type, click.Choice) - - assert sorted(child.name for child in templates.iterdir() if child.is_dir()) == sorted(mode.type.choices) - - -def test_the_port_and_the_workers_default_to_fastros(): - params = _params() + offered = subprocess.run( + [sys.executable, "-m", "fastro", "make", "deploy", "--help"], cwd=REPO_ROOT, capture_output=True, text=True + ) - assert GENERATOR["params"]["api_port"]["default"] == params["api_port"].default - assert GENERATOR["params"]["workers"]["default"] == params["workers"].default + 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_subnet_default_and_limits_are_fastros(): - subnet = GENERATOR["params"]["internal_subnet"] - limits = subnet["max_prefix"] +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 subnet["default"] == deploy.DEFAULT_INTERNAL_SUBNET == _params()["internal_subnet"].default - assert {4: limits["v4"], 6: limits["v6"]} == deploy.SMALLEST_TRUSTED_PREFIX + assert (tree / "nginx" / "default.conf.j2").is_file() + assert "./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro" in compose diff --git a/blueprint/tests/test_deploy_templates.py b/blueprint/tests/test_deploy_templates.py index 2f578f55..707c5a35 100644 --- a/blueprint/tests/test_deploy_templates.py +++ b/blueprint/tests/test_deploy_templates.py @@ -87,7 +87,7 @@ def test_forwarded_headers_are_trusted_only_from_the_compose_network(): 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(): @@ -107,7 +107,7 @@ 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 diff --git a/blueprint/tests/test_docs_commands.py b/blueprint/tests/test_docs_commands.py index 514b6b45..daa61e62 100644 --- a/blueprint/tests/test_docs_commands.py +++ b/blueprint/tests/test_docs_commands.py @@ -8,11 +8,12 @@ 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, shown_pages +from retired import OLD_COMMAND, OLD_DRILL, REPO_ROOT, RUNS_OLD_COMMAND, SAYS_OLD_COMMAND_EXITS, shown_pages FASTRO = typer.main.get_command(app) @@ -78,6 +79,8 @@ def _refusal(words: list[str], runs: bool = True) -> str | None: 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: @@ -88,13 +91,28 @@ def _refusal(words: list[str], runs: bool = True) -> str | None: 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) + 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 @@ -134,8 +152,12 @@ def test_every_fastro_command_a_page_shows_is_one_the_pinned_fastro_takes(where: (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`.", 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), diff --git a/blueprint/tests/test_fastro_page.py b/blueprint/tests/test_fastro_page.py index b8ad0ea0..866a0672 100644 --- a/blueprint/tests/test_fastro_page.py +++ b/blueprint/tests/test_fastro_page.py @@ -1,34 +1,55 @@ """What the fastro page states about fastro's commands and the compose files they write. -At the pin, `fastro make deploy` renders fastro's own legacy templates, not this repository's -`[generators.deploy]`, so the page's facts about what a mode writes are read from those. +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 types import SimpleNamespace -from typing import Any, cast +from typing import Any import click import pytest import typer.main import yaml -from fastro import _legacy_deploy as deploy from fastro.cli import app -from fastro.commands import env -from fastro.lib.render import Renderer +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: @@ -64,47 +85,33 @@ 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() -> list[list[str]]: - return [row for row in _rows() if row[0].startswith("`-")] - - -def _plan(mode: str, root: Path, taskiq: bool = True, api_port: int = 8000, workers: int = 4, **params: Any) -> deploy.Plan: - backend = root / "backend" - backend.mkdir(parents=True, exist_ok=True) - if taskiq: - (backend / deploy.TASKIQ_PACKAGE).mkdir(parents=True) - project = SimpleNamespace(repo_root=root, backend_dir=backend) +def _option_rows() -> dict[str, list[str]]: + return {_ticked(row[0])[0]: row for row in _rows() if row[0].startswith("`-")} - return deploy.plan(mode, cast(Any, project), root, api_port=api_port, workers=workers, **params) +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() -def _rendered(plan: deploy.Plan) -> dict[str, str]: - renderer = Renderer(deploy.TEMPLATES) + return [re.findall(r"--?[a-z][a-z-]*", line.split(" ")[1]) for line in options if line.startswith(" -")] - return {render.target.name: renderer.render(render.template, plan.context) for render in plan.files} +def test_the_page_names_the_modes_the_catalog_declares(): + assert sorted(_mode_rows()) == sorted(MODES) -def _services(mode: str, root: Path, taskiq: bool = True) -> dict[str, Any]: - return dict(yaml.safe_load(_rendered(_plan(mode, root, taskiq))["docker-compose.yml"])["services"]) - -def test_the_page_names_the_modes_fastro_takes(): - mode = next(param for param in _command("make", "deploy").params if param.name == "mode") - assert isinstance(mode.type, click.Choice) - - assert sorted(_mode_rows()) == sorted(mode.type.choices) - - -@pytest.mark.parametrize("mode", ["local", "prod", "nginx"]) +@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] - plan = _plan(mode, tmp_path) - services = _services(mode, tmp_path / "rendered") + 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(str(render.target.relative_to(tmp_path)) for render in plan.files) == sorted(_ticked(row[2])) + 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) @@ -113,41 +120,99 @@ def test_each_mode_writes_the_files_and_the_stack_its_row_names(mode: str, tmp_p assert (f"{port[1]}:{port[1]}" in published) if port else not published -@pytest.mark.parametrize("mode", ["local", "prod", "nginx"]) +@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 = _services(mode, tmp_path / "with") - without = _services(mode, tmp_path / "without", taskiq=False) + 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(without) + assert not {"worker", "scheduler"} & set(_rendered_directly(mode, [])["services"]) def test_the_options_and_their_defaults_are_the_ones_fastro_has(): - options = {param.opts[0]: param for param in _command("make", "deploy").params if isinstance(param, click.Option)} - stated = {_ticked(row[0])[0]: row for row in _option_rows()} + 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(options) + assert sorted(stated) == sorted(listed) for flag, row in stated.items(): - option = options[flag] - assert sorted(_ticked(row[0])) == sorted(option.opts), flag - if option.is_flag: - assert row[1] == "", flag - elif option.default is None: - assert (flag, row[1]) == ("--output-dir", "the repository root") + 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] == f"`{option.default}`", flag + assert row[1] == "", flag -def test_the_subnet_limits_are_the_catalogs_and_fastros(): - limits = CATALOG["generators"]["deploy"]["params"]["internal_subnet"]["max_prefix"] +def test_the_subnet_limits_are_the_catalogs(): + limits = GENERATOR["params"]["internal_subnet"]["max_prefix"] - assert {4: limits["v4"], 6: limits["v6"]} == deploy.SMALLEST_TRUSTED_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"), [ @@ -159,18 +224,18 @@ def test_the_subnet_limits_are_the_catalogs_and_fastros(): ("fd00::/48", False), ], ) -def test_the_subnet_refusals_the_pages_name(subnet: str, refused: bool): - try: - deploy.validated_subnet(subnet) - except ValueError: - assert refused, subnet - else: - assert not refused, subnet +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 = yaml.safe_load(_rendered(_plan("nginx", tmp_path, internal_subnet=subnet))["docker-compose.yml"]) + 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 = ( @@ -185,64 +250,123 @@ def test_the_nginx_subnet_is_the_network_and_the_peers_uvicorn_trusts(tmp_path: assert "`FORWARDED_ALLOW_IPS`" in section and "compose network's subnet" in section -@pytest.mark.parametrize(("mode", "refused"), [("nginx", True), ("local", False), ("prod", False)]) -def test_only_nginx_reads_the_subnet(mode: str, refused: bool): +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( - [sys.executable, "-m", "fastro", "make", "deploy", mode, "--internal-subnet", "*", "--dry-run"], - cwd=REPO_ROOT, - capture_output=True, - text=True, + [str(Path(sys.executable).parent / command[0]), *command[1:]], cwd=tmp_path, capture_output=True, text=True ) + section = _section(MAKE_DEPLOY) - assert (run.returncode != 0) is refused, run.stdout + run.stderr - assert "`local` and `prod` always use the default network" in _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("## Preparing the environment: `fastro env`") + 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_every_command_the_page_heads_a_section_with_is_one_fastro_has(): - headed = re.findall(r"^#+ .*?`fastro ([a-z ]+)`", PAGE.read_text(), re.M) +def test_the_built_in_secret_prints_a_token_outside_a_project(tmp_path: Path): + run = _fastro("env", "secret", cwd=tmp_path) - assert headed - for words in headed: - _command(*words.split()) + 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) -def _modes_named(cell: str) -> set[str]: - named = re.search(r"for ((?:`\w+`(?: and )?)+)$", cell) +@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) - return set(_ticked(named[1])) if named else {"local", "prod", "nginx"} + 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 -@pytest.mark.parametrize("mode", ["local", "prod", "nginx"]) -def test_the_port_and_the_workers_reach_the_modes_their_rows_name(mode: str, tmp_path: Path): - rows = {_ticked(row[0])[0]: row for row in _option_rows()} - rendered = _rendered(_plan(mode, tmp_path, api_port=9123, workers=7)) - api = yaml.safe_load(rendered["docker-compose.yml"])["services"]["api"] - environment = api.get("environment", {}) +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) - 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(rendered.values()) - if mode in _modes_named(rows["--workers"][2]): - assert environment["WORKERS"] == "7" - else: - assert "WORKERS" not in environment + 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("## Preparing the environment: `fastro env`") + section = _section(ENV) - for module in (env.GEN_SECRET_MODULE, env.VALIDATE_MODULE): + 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() @@ -260,7 +384,7 @@ def test_validate_exits_and_reports_the_way_the_page_says( exited = script.main() printed = capsys.readouterr().out - section = _section("## Preparing the environment: `fastro env`") + section = _section(ENV) assert exited == code assert "exits 1 when anything is critical and 0 otherwise" in section @@ -287,3 +411,14 @@ def test_the_root_dev_group_installs_fastro(): 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_retired_cli.py b/blueprint/tests/test_retired_cli.py index f33ead5a..0a0ed761 100644 --- a/blueprint/tests/test_retired_cli.py +++ b/blueprint/tests/test_retired_cli.py @@ -21,6 +21,7 @@ OLD_DRILL, OLD_PACKAGE, REPO_ROOT, + SAYS_OLD_COMMAND_EXITS, tracked_text, ) @@ -41,6 +42,8 @@ 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.""" @@ -57,7 +60,7 @@ def _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): + 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 diff --git a/docs/changelog.md b/docs/changelog.md index ce6c084c..0d7ae5e4 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -27,6 +27,14 @@ ___ `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 diff --git a/docs/user-guide/fastro.md b/docs/user-guide/fastro.md index 7f65137f..bb7ef090 100644 --- a/docs/user-guide/fastro.md +++ b/docs/user-guide/fastro.md @@ -10,8 +10,14 @@ through `uv run --no-sync`. Every command has `--help`. uv run --no-sync fastro make deploy local ``` -`fastro make deploy` writes `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. +`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 | |---|---|---| @@ -29,9 +35,9 @@ A project with the taskiq feature also gets a `worker` and one `scheduler` in ev | `--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` | | Overwrite existing files without asking | -| `--yes`, `-y` | | Assume yes for every prompt | -| `--dry-run` | | Show what would be written, and write nothing | +| `--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 @@ -39,10 +45,16 @@ 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 ``` -For `nginx`, `--internal-subnet` has to name a network of `/8` or smaller for IPv4, and `/48` or -smaller for IPv6. It is written as the compose network's subnet and as `FORWARDED_ALLOW_IPS` for -the API container, so a value with host bits set (`172.31.240.1/24`), a wildcard, or a wider -range is refused before any file is written. `local` and `prod` always use the default network. +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` @@ -55,8 +67,9 @@ uv run --no-sync fastro env secret | gh secret set SECRET_KEY --repo my-org/my-a ``` Prints a hex key for `SECRET_KEY`: `--bytes` random bytes, from `16` to `128`, `32` by default, -so 64 hex characters. In a project it runs the project's own `scripts.gen_secret`, which draws -again while the app's secret-key rules would refuse the key. +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` @@ -64,12 +77,15 @@ again while the app's secret-key rules would refuse the key. uv run --no-sync fastro env validate ``` -Runs the project's `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 +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 diff --git a/pyproject.toml b/pyproject.toml index c62d969d..fbdef785 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -28,7 +28,7 @@ dev = ["fastro", "packaging>=24.0", "pyyaml>=6.0.2", "types-pyyaml>=6.0.12"] members = ["backend"] [tool.uv.sources] -fastro = { git = "https://github.com/benavlabs/fastro", rev = "a07bbc1b0a4a0c894bcd59edf5a602b36e34bae1" } +fastro = { git = "https://github.com/benavlabs/fastro", rev = "640caae2d6f7c129ab0f03ee6a34088d4dede65f" } [tool.pytest.ini_options] testpaths = ["blueprint/tests"] From 1258c861bbd0cfb3969ad111e9fbd42666e24379 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Thu, 19 Nov 2026 18:09:14 -0300 Subject: [PATCH 67/71] relock fastro at 640caae now that it's pushed, so the locked sync in ci matches the pin in pyproject.toml --- uv.lock | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/uv.lock b/uv.lock index d26e2a0a..d60774a7 100644 --- a/uv.lock +++ b/uv.lock @@ -965,7 +965,7 @@ dev = [ [package.metadata.requires-dev] dev = [ - { name = "fastro", git = "https://github.com/benavlabs/fastro?rev=a07bbc1b0a4a0c894bcd59edf5a602b36e34bae1" }, + { 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" }, @@ -1129,7 +1129,7 @@ wheels = [ [[package]] name = "fastro" version = "0.1.0.dev0" -source = { git = "https://github.com/benavlabs/fastro?rev=a07bbc1b0a4a0c894bcd59edf5a602b36e34bae1#a07bbc1b0a4a0c894bcd59edf5a602b36e34bae1" } +source = { git = "https://github.com/benavlabs/fastro?rev=640caae2d6f7c129ab0f03ee6a34088d4dede65f#640caae2d6f7c129ab0f03ee6a34088d4dede65f" } dependencies = [ { name = "jinja2" }, { name = "packaging" }, From d188bc7b8352e051671ba30f3c7fc61c6daa11f7 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Thu, 19 Nov 2026 20:17:05 -0300 Subject: [PATCH 68/71] let accounts contribute the scope fingerprint through the generated src/wiring/scope.py so a project with the cache and without accounts imports, ship the cached tier listing test only with the cache, and check over all 164 selections that no kept file imports a module the selection removed --- backend/src/infrastructure/cache/utils.py | 4 +- backend/src/wiring/scope.py | 15 +++++ .../infrastructure/cache/test_decorator.py | 18 ------ .../cache/test_scoped_callers.py | 55 ++++++++++++++++ .../unit/infrastructure/cache/test_utils.py | 26 +++----- backend/tests/unit/test_blueprint_catalog.py | 63 ++++++++++++++++++- backend/tests/unit/test_docs_wiring.py | 30 +++++++++ blueprint.toml | 31 +++++++++ docs/assets/build-diagrams.cjs | 3 +- docs/changelog.md | 8 +++ docs/user-guide/composable-features.md | 1 + docs/user-guide/project-structure.md | 1 + 12 files changed, 215 insertions(+), 40 deletions(-) create mode 100644 backend/src/wiring/scope.py create mode 100644 backend/tests/unit/infrastructure/cache/test_scoped_callers.py 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/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/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/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index baf6d8dd..a21fdffe 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -343,6 +343,53 @@ def test_no_file_a_project_keeps_imports_a_dependency_it_did_not_select(): 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( @@ -1291,7 +1338,7 @@ 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"} +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.""" @@ -1439,6 +1486,8 @@ def _kept_by_the_catalog(features: dict[str, Any], chosen: set[str]) -> set[str] ("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]): @@ -1469,6 +1518,16 @@ def test_a_project_with_a_worker_queues_its_mail_and_one_without_hands_it_over() 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_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.""" @@ -2211,7 +2270,7 @@ def test_the_file_a_feature_brings_with_it_is_generated_only_for_that_feature(): 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) == 11 + assert [entry.get("if") for entry in _entries()].count(None) == 12 def test_the_statement_a_raw_slot_carries_is_in_the_file(): diff --git a/backend/tests/unit/test_docs_wiring.py b/backend/tests/unit/test_docs_wiring.py index 9f16ff07..a72eeac2 100644 --- a/backend/tests/unit/test_docs_wiring.py +++ b/backend/tests/unit/test_docs_wiring.py @@ -15,6 +15,7 @@ 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" DRAWN_TREE = re.compile(r"```text\n(.*?)```", re.DOTALL) @@ -104,3 +105,32 @@ def test_the_new_module_steps_declare_its_paths_in_the_catalog(): 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 diff --git a/blueprint.toml b/blueprint.toml index b4c985f6..bc37b770 100644 --- a/blueprint.toml +++ b/blueprint.toml @@ -170,6 +170,10 @@ doc = "A module outside src/modules that declares tables on the metadata." 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.seeders] cardinality = "many" doc = "A step the initial-data script runs, in order." @@ -220,6 +224,7 @@ critical_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" @@ -340,6 +345,12 @@ 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" @@ -427,6 +438,12 @@ 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" @@ -638,6 +655,20 @@ 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/transports.py" doc = "The authentication transports this project registers beside the session one." diff --git a/docs/assets/build-diagrams.cjs b/docs/assets/build-diagrams.cjs index 5a26d110..b3c14c07 100644 --- a/docs/assets/build-diagrams.cjs +++ b/docs/assets/build-diagrams.cjs @@ -52,7 +52,7 @@ const compositionRoot = ({ primary, body, muted, line, panel }) => ` contributes - + app.pyROUTER_MOUNTS, LIFECYCLES settings.pythe settings mixins @@ -64,6 +64,7 @@ const compositionRoot = ({ primary, body, muted, line, panel }) => `tables.pyTABLE_MODULES transports.pyEXTRA_TRANSPORTS cache.pycached + scope.pySCOPE_FINGERPRINT diff --git a/docs/changelog.md b/docs/changelog.md index 0d7ae5e4..e1d9695b 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -82,6 +82,14 @@ ___ 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. + ___ ## 0.20.0 - October 25, 2026 - Composable Features diff --git a/docs/user-guide/composable-features.md b/docs/user-guide/composable-features.md index 1e84676d..cd2a5736 100644 --- a/docs/user-guide/composable-features.md +++ b/docs/user-guide/composable-features.md @@ -29,6 +29,7 @@ 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 | 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. diff --git a/docs/user-guide/project-structure.md b/docs/user-guide/project-structure.md index 97e44b3f..ab196643 100644 --- a/docs/user-guide/project-structure.md +++ b/docs/user-guide/project-structure.md @@ -179,6 +179,7 @@ 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 └── admin.py # ADMIN_VIEWS (absent without the admin feature) ``` From c0f0b553e6e71d9c74522dfb71f37aeddbc793b8 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Thu, 19 Nov 2026 22:58:59 -0300 Subject: [PATCH 69/71] narrow the fastro command to a click group so mypy checks its subcommands, build every fixture user's username and email from a fresh uuid so two thousand in one session never collide, and drop a hook line's trailing paths without a backtracking regex --- backend/tests/fixtures/accounts.py | 44 +++++++--------- .../integration/auth/test_fixture_users.py | 21 ++++++++ backend/tests/unit/test_blueprint_catalog.py | 50 ++++++++++++++++++- blueprint/tests/test_docs_commands.py | 10 +++- 4 files changed, 97 insertions(+), 28 deletions(-) create mode 100644 backend/tests/integration/auth/test_fixture_users.py diff --git a/backend/tests/fixtures/accounts.py b/backend/tests/fixtures/accounts.py index 4084d064..b6a65c91 100644 --- a/backend/tests/fixtures/accounts.py +++ b/backend/tests/fixtures/accounts.py @@ -2,6 +2,7 @@ import time from collections.abc import AsyncIterator +from uuid import uuid4 import pytest import pytest_asyncio @@ -17,18 +18,23 @@ 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) @@ -47,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) @@ -73,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() 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/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index a21fdffe..ddea61af 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -14,6 +14,7 @@ import re import subprocess import sys +import time import tomllib from collections.abc import Iterable from importlib.metadata import packages_distributions, requires @@ -873,7 +874,54 @@ 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 re.sub(r"(?: [\w.-]*[/.][\w./-]*)+$", "", line) in _workflow_runs() + 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(): diff --git a/blueprint/tests/test_docs_commands.py b/blueprint/tests/test_docs_commands.py index daa61e62..7050ab56 100644 --- a/blueprint/tests/test_docs_commands.py +++ b/blueprint/tests/test_docs_commands.py @@ -15,7 +15,15 @@ from fastro.verify import verify_sets from retired import OLD_COMMAND, OLD_DRILL, REPO_ROOT, RUNS_OLD_COMMAND, SAYS_OLD_COMMAND_EXITS, shown_pages -FASTRO = typer.main.get_command(app) + +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")) From 09bab0c5967becb61dfac5c6e06fdaa37aa9cba3 Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Fri, 20 Nov 2026 00:31:13 -0300 Subject: [PATCH 70/71] give a new account the tier DEFAULT_TIER_NAME names on the signup route and on a provider's first sign-in, through the new_account_fields point and the generated src/wiring/signup.py, filter out the columns crudauth owns on both paths, and stop the signup route promising a tier in projects without tiers --- backend/src/infrastructure/auth/setup.py | 12 +++- backend/src/infrastructure/composition.py | 5 ++ backend/src/modules/tier/hooks.py | 15 +++++ backend/src/modules/user/routes.py | 3 +- backend/src/modules/user/schemas.py | 7 +- backend/src/modules/user/service.py | 15 +++-- backend/src/wiring/signup.py | 12 ++++ .../integration/tiers/test_signup_tier.py | 65 +++++++++++++++++++ .../unit/infrastructure/auth/test_setup.py | 23 +++++-- .../tests/unit/modules/user/test_service.py | 40 ++++++++++++ .../unit/modules/user/test_signup_route.py | 12 ++++ backend/tests/unit/test_blueprint_catalog.py | 8 ++- backend/tests/unit/test_docs_wiring.py | 38 +++++++++++ blueprint.toml | 18 +++++ docs/assets/build-diagrams.cjs | 11 ++-- docs/changelog.md | 4 ++ docs/user-guide/composable-features.md | 1 + .../configuration/environment-variables.md | 4 ++ docs/user-guide/project-structure.md | 1 + 19 files changed, 275 insertions(+), 19 deletions(-) create mode 100644 backend/src/modules/tier/hooks.py create mode 100644 backend/src/wiring/signup.py create mode 100644 backend/tests/integration/tiers/test_signup_tier.py create mode 100644 backend/tests/unit/modules/user/test_signup_route.py 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/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/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/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/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/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/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/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/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py index ddea61af..98aecbe7 100644 --- a/backend/tests/unit/test_blueprint_catalog.py +++ b/backend/tests/unit/test_blueprint_catalog.py @@ -1576,6 +1576,12 @@ def test_a_project_with_accounts_wires_the_scope_fingerprint_and_one_without_wir 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.""" @@ -2318,7 +2324,7 @@ def test_the_file_a_feature_brings_with_it_is_generated_only_for_that_feature(): 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) == 12 + assert [entry.get("if") for entry in _entries()].count(None) == 13 def test_the_statement_a_raw_slot_carries_is_in_the_file(): diff --git a/backend/tests/unit/test_docs_wiring.py b/backend/tests/unit/test_docs_wiring.py index a72eeac2..9e38a3ba 100644 --- a/backend/tests/unit/test_docs_wiring.py +++ b/backend/tests/unit/test_docs_wiring.py @@ -10,12 +10,15 @@ import tomllib from pathlib import Path +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) @@ -134,3 +137,38 @@ def test_the_composable_features_page_says_the_scope_fingerprint_is_none_without (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 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/blueprint.toml b/blueprint.toml index bc37b770..d6773e9a 100644 --- a/blueprint.toml +++ b/blueprint.toml @@ -174,6 +174,10 @@ doc = "An authentication transport registered beside the session one." 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." @@ -313,6 +317,7 @@ 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" @@ -669,6 +674,19 @@ 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." diff --git a/docs/assets/build-diagrams.cjs b/docs/assets/build-diagrams.cjs index b3c14c07..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 @@ -65,6 +65,7 @@ const compositionRoot = ({ primary, body, muted, line, panel }) => `transports.pyEXTRA_TRANSPORTS cache.pycached scope.pySCOPE_FINGERPRINT + signup.pyNEW_ACCOUNT_FIELDS @@ -81,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 e1d9695b..a346835b 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -89,6 +89,10 @@ ___ 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/user-guide/composable-features.md b/docs/user-guide/composable-features.md index cd2a5736..175459f5 100644 --- a/docs/user-guide/composable-features.md +++ b/docs/user-guide/composable-features.md @@ -30,6 +30,7 @@ plain objects at stable paths, and one package collects them. | `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. diff --git a/docs/user-guide/configuration/environment-variables.md b/docs/user-guide/configuration/environment-variables.md index 3c8d8c5e..79d4a07c 100644 --- a/docs/user-guide/configuration/environment-variables.md +++ b/docs/user-guide/configuration/environment-variables.md @@ -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/project-structure.md b/docs/user-guide/project-structure.md index ab196643..74d7d3e1 100644 --- a/docs/user-guide/project-structure.md +++ b/docs/user-guide/project-structure.md @@ -180,6 +180,7 @@ wiring/ ├── 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) ``` From 856a6b8269bd88475b4c381deaf3e0baf573fbfb Mon Sep 17 00:00:00 2001 From: Igor Benav Date: Fri, 20 Nov 2026 01:37:28 -0300 Subject: [PATCH 71/71] name the settings classes the docs point to as the code has them, DEFAULT_TIER_NAME on TierSettings, the admin and limiter settings on the classes and modules that hold them, and test that every settings class a page names exists, sits in the file the page gives, and has the settings its row lists --- backend/tests/unit/test_docs_settings.py | 127 ++++++++++++++++++ blueprint.toml | 1 + docs/user-guide/admin-panel/configuration.md | 7 +- .../user-guide/admin-panel/user-management.md | 2 +- docs/user-guide/authentication/sessions.md | 2 +- docs/user-guide/background-tasks/index.md | 2 +- docs/user-guide/caching/client-cache.md | 2 +- docs/user-guide/caching/index.md | 2 +- docs/user-guide/caching/redis-cache.md | 2 +- .../configuration/settings-classes.md | 46 +++---- docs/user-guide/rate-limiting/index.md | 2 +- 11 files changed, 158 insertions(+), 37 deletions(-) create mode 100644 backend/tests/unit/test_docs_settings.py 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/blueprint.toml b/blueprint.toml index d6773e9a..7360703c 100644 --- a/blueprint.toml +++ b/blueprint.toml @@ -21,6 +21,7 @@ blueprint_only = [ "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", diff --git a/docs/user-guide/admin-panel/configuration.md b/docs/user-guide/admin-panel/configuration.md index 48e76706..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 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/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 b44d5536..c1deca12 100644 --- a/docs/user-guide/background-tasks/index.md +++ b/docs/user-guide/background-tasks/index.md @@ -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/configuration/settings-classes.md b/docs/user-guide/configuration/settings-classes.md index d43de27b..6cc22257 100644 --- a/docs/user-guide/configuration/settings-classes.md +++ b/docs/user-guide/configuration/settings-classes.md @@ -1,42 +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. 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 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 +# 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 @@ -48,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_*` | @@ -249,7 +241,7 @@ class Settings( AppSettings, LoggingSettings, # CacheSettings — removed - # RateLimiterSettings — removed + # RateLimitSettings — removed # TaskiqSettings — removed ): pass 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