`. Luego cambia a `engine: presidio` (tras instalar
+ `pyfly[pii]` y `en_core_web_sm`) y compara la salida.
+
+2. **HealthIndicator personalizado.** Escribe un `StripeHealthIndicator` que llame
+ a `https://status.stripe.com/api/v2/status.json` con `httpx`, parsee
+ `indicator.status` y devuelva `UP` si el valor es `"none"` o `DOWN` en caso
+ contrario. Regístralo como `@component` y verifica que `/actuator/health`
+ incluye un componente `StripeHealthIndicator`. Pruébalo con una llamada `httpx`
+ simulada que lance `httpx.ConnectError` y verifica que el estado agregado pasa a
+ `DOWN`.
+
+3. **Aspecto de métricas con umbrales por método.** Extiende `MetricsAspect` del
+ Listado 15.13 con un `slow_threshold` configurable (0,5 s por defecto)
+ inyectado desde `pyfly.yaml` vía `@config_properties`. Cuando un método de
+ servicio supere el umbral, emite un `logger.warning("slow_method", …)` con los
+ campos `method_name` y `elapsed`. Escribe una prueba de pytest que use un
+ `FakeClock` o `unittest.mock.patch("time.perf_counter")` para simular una
+ llamada lenta y aserte que se registra la advertencia.
diff --git a/book/manuscript-es/16-testing.md b/book/manuscript-es/16-testing.md
new file mode 100644
index 00000000..48a18aa2
--- /dev/null
+++ b/book/manuscript-es/16-testing.md
@@ -0,0 +1,1428 @@
+Capítulo 16
+
+# Pruebas de aplicaciones PyFly {.chtitle}
+
+::: figure art/openers/ch16.svg |
+
+El monedero (wallet) funciona. Los depósitos entran, los saldos se actualizan, los eventos se propagan por el bus y el coordinador de la saga revierte limpiamente ante un fallo. Lo que todavía no tienes es la **confianza** de que seguirá funcionando tras la próxima refactorización. Esa confianza viene de las pruebas: pruebas que se ejecutan en milisegundos, que demuestran que el modelo de dominio hace cumplir sus invariantes, que verifican que la canalización CQRS despacha correctamente, que ejercitan las consultas derivadas y los predicados de tipo Specification del repositorio contra una base de datos SQLite real, y que arrancan el contexto de aplicación completo en una prueba de integración que demuestra la composición entera de inyección de dependencias + persistencia.
+
+PyFly trata las pruebas como un asunto de primer orden. El módulo `pyfly.testing` incluye ayudantes de más alto nivel —`PyFlyTestCase`, `create_test_container`, `assert_event_published`, el cableado de Testcontainers— a los que puedes recurrir cuando los necesites. La propia suite de pruebas de Lumen no los usa: cablea componentes reales directamente desde `conftest.py`, emplea fixtures estándar de pytest y cubre cada nivel de la pirámide sin código repetitivo. Ese es el enfoque que enseña este capítulo.
+
+::: figure art/figures/16-testing.svg | Figura 16.1 — La pirámide de pruebas de PyFly. Las pruebas unitarias rápidas forman la base ancha; las pruebas de integración ocupan el centro; las pruebas de adaptador contra una BD real y una prueba de integración con el contexto arrancado coronan la cima.
+
+La pirámide tiene cuatro niveles. Las **pruebas unitarias** están en la base —muchas de ellas, ejecutándose en milisegundos, ejercitando el modelo de dominio sin dependencias—. Las **pruebas de flujo CQRS** ocupan el siguiente escalón: el ciclo completo de apertura/depósito/retiro/consulta enrutado a través del bus real y del repositorio real, todo cableado en `conftest.py`. Las **pruebas de repositorio** ejercitan las consultas derivadas, la paginación y los predicados de tipo Specification contra SQLite. En la cúspide, una **prueba de integración con el contexto arrancado** inicia el `ApplicationContext` real —escaneo de inyección de dependencias, autoconfiguración de CQRS, `RepositoryBeanPostProcessor`, la costura `@transactional`, la arquitectura orientada a eventos (EDA)— y recorre el ciclo de vida completo.
+
+| Nivel | Dependencias | Velocidad | Enfoque de Lumen |
+|-------------------------|---------------------------------------|-----------|------------------------------------|
+| Unitario | Ninguna | Rápido | pytest puro, sin fixtures |
+| Flujo CQRS | Bus real + repositorio sobre SQLite | Rápido | fixtures de conftest.py |
+| Repositorio | SQLite + aiosqlite | Rápido | `tmp_path` + SQLAlchemy |
+| Contexto arrancado | ApplicationContext completo + SQLite | Rápido | sustitución de entorno `monkeypatch` |
+
+El proyecto usa pytest con `pytest-asyncio` en **modo automático**. Actívalo una vez en `pyproject.toml` y cada función `async def test_*` se recopila automáticamente:
+
+```ini
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+pythonpath = ["src"]
+```
+
+Una glosa rápida antes de empezar, ya que tres términos se repiten en este capítulo. Un
+**fixture** es una pieza reutilizable de preparación de prueba: pytest la construye una vez, se la
+entrega a tu prueba y la desmonta después. Un **conftest.py** es un archivo especial que pytest
+descubre automáticamente; cualquier fixture que declares ahí pasa a estar disponible para cada
+prueba del paquete sin necesidad de importarla. Y el **modo automático de `pytest-asyncio`** simplemente
+significa que puedes escribir `async def test_...` y pytest hará el `await` por ti: no hace falta
+un decorador por prueba. Cada uno de estos vuelve a aparecer con un ejemplo concreto
+más adelante; esto es solo el mapa.
+
+Instala las dependencias de desarrollo y ejecuta la suite:
+
+```bash
+uv run --extra dev pytest -q
+```
+
+El `uv sync` a secas (sin `--extra dev`) omite el grupo de desarrollo, así que pytest no queda
+instalado. Incluye siempre `--extra dev` al ejecutar las pruebas.
+
+**Ejecútalo.** Desde el directorio `samples/lumen`, ejecuta toda la suite una vez ahora para que tengas
+una referencia de base antes de cambiar nada:
+
+```bash
+uv run --extra dev pytest -q
+```
+
+Deberías ver una hilera de puntos —uno por prueba— seguida de una línea de resumen:
+
+```text
+......................................... [100%]
+41 passed in 0.28s
+```
+
+Cuarenta y una pruebas superadas, en menos de un tercio de segundo, sin Docker ni proceso
+externo alguno. Esa velocidad es el sentido entero de la pirámide: la base rápida atrapa la mayoría
+de las regresiones antes de que lleguen a ejecutarse las capas de integración más lentas. Si en cambio ves
+`No module named pytest`, es que olvidaste `--extra dev`; vuelve a ejecutarlo con esa opción.
+
+---
+
+## Pruebas unitarias del dominio
+
+El modelo de dominio —`Money` y `Wallet`— no tiene dependencias del framework. Nunca toca una base de datos, un bus de mensajes ni un cliente HTTP. Esa pureza lo convierte en el objetivo ideal para pruebas unitarias rápidas: construye objetos, llama a métodos, comprueba resultados. Sin mocks, sin fixtures, sin `async`.
+
+### Pruebas de Money
+
+`Money` es una dataclass congelada (frozen). Cada operación o bien tiene éxito y devuelve una nueva instancia de `Money`, o bien lanza `BusinessRuleViolation`. Cada violación lleva una cadena `.rule` que nombra el invariante incumplido, útil para verificar la regla exacta en las pruebas.
+
+Una glosa rápida sobre dos términos. Un **objeto de valor** es un objeto definido por completo por sus
+valores: dos instancias de `Money(1050, EUR)` son iguales porque sus campos son iguales,
+no porque sean el mismo objeto en memoria. Una **dataclass congelada (frozen)** es la forma que tiene Python
+de hacer inmutable ese objeto: una vez construido, no puedes reasignar sus
+campos. Juntos hacen que `Money` sea seguro de pasar libremente: ningún consumidor puede
+mutarlo a tus espaldas, así que nunca necesita copia defensiva.
+
+Construyamos el archivo de pruebas un grupo de aserciones a la vez. Cada paso de abajo se corresponde con
+una función `def test_...` del listado que sigue.
+
+**Paso 1 — la igualdad es estructural.** `test_value_equality_is_structural` comprueba
+que dos valores `Money` con el mismo importe y la misma moneda son iguales, y que
+diferir en cualquiera de los dos campos los hace distintos. Este es el contrato del objeto de valor.
+
+**Paso 2 — la inmutabilidad se hace cumplir.** `test_money_is_immutable` intenta asignar a
+`money.amount` y espera una excepción. La dataclass congelada lanza
+`FrozenInstanceError`, demostrando que no puedes mutar un valor tras su construcción.
+
+**Paso 3 — la aritmética devuelve valores nuevos.** `test_add_and_subtract_same_currency`
+comprueba que `add` y `subtract` producen el `Money` esperado, sin mutar nunca los
+operandos.
+
+**Paso 4 — la superficie de conveniencia.** `test_zero_factory_and_major_units` cubre la
+fábrica `Money.zero(currency)`, la propiedad `major_units` y el formateo de
+`__str__`.
+
+**Paso 5 — los invariantes rechazan la entrada inválida.** Las dos últimas pruebas comprueban que mezclar
+monedas y pasar un importe no entero lanzan cada una `BusinessRuleViolation` con
+una cadena `.rule` específica: `"money-currency-mismatch"` y
+`"money-amount-integer"`.
+
+::: listing tests/test_money.py | Listado 16.1 — Pruebas unitarias puras del objeto de valor Money
+from __future__ import annotations
+
+import pytest
+from lumen.interfaces.enums.v1.currency import Currency
+from lumen.models.entities.v1.money import Money
+
+from pyfly.domain import BusinessRuleViolation
+
+
+def test_value_equality_is_structural() -> None:
+ assert Money(1050, Currency.EUR) == Money(1050, Currency.EUR)
+ assert Money(1050, Currency.EUR) != Money(1050, Currency.USD)
+ assert Money(1050, Currency.EUR) != Money(999, Currency.EUR)
+
+
+def test_money_is_immutable() -> None:
+ money = Money(1050, Currency.EUR)
+ with pytest.raises(Exception): # frozen dataclass -> FrozenInstanceError
+ money.amount = 0 # type: ignore[misc]
+
+
+def test_add_and_subtract_same_currency() -> None:
+ a = Money(1050, Currency.EUR)
+ b = Money(450, Currency.EUR)
+ assert a.add(b) == Money(1500, Currency.EUR)
+ assert a.subtract(b) == Money(600, Currency.EUR)
+
+
+def test_zero_factory_and_major_units() -> None:
+ assert Money.zero(Currency.USD) == Money(0, Currency.USD)
+ assert Money(1050, Currency.EUR).major_units == 10.5
+ assert str(Money(1050, Currency.EUR)) == "10.50 EUR"
+
+
+def test_currency_mismatch_is_rejected() -> None:
+ with pytest.raises(BusinessRuleViolation) as exc:
+ Money(100, Currency.EUR).add(Money(100, Currency.USD))
+ assert exc.value.rule == "money-currency-mismatch"
+
+
+def test_non_integer_amount_is_rejected() -> None:
+ with pytest.raises(BusinessRuleViolation) as exc:
+ Money(10.5, Currency.EUR) # type: ignore[arg-type]
+ assert exc.value.rule == "money-amount-integer"
+:::
+
+Cada prueba es síncrona: sin `async`, sin `await`, sin fixtures. Pytest recopila las funciones a nivel de módulo automáticamente. `Currency.EUR` es un valor de enumeración, no una cadena simple, ajustándose exactamente al contrato de tipos del modelo de dominio.
+
+**Ejecútalo.** Ejecuta solo este archivo para ver en acción la base unitaria de la pirámide:
+
+```bash
+uv run --extra dev pytest tests/test_money.py -q
+```
+
+Salida esperada:
+
+```text
+...... [100%]
+6 passed in 0.02s
+```
+
+Seis pruebas, veinte milisegundos. Sin base de datos conectada, sin bus de eventos iniciado: estas
+pruebas construyen un objeto simple y comprueban su comportamiento. Eso es lo que hace que la
+base de la pirámide sea tan ancha y tan rápida.
+
+*Qué acaba de pasar.* Has demostrado todo el contrato de `Money` —igualdad,
+inmutabilidad, aritmética y cada invariante— sin tocar una sola pieza de
+infraestructura del framework. El código de dominio puro permanece probable como dominio puro. Cuando una de
+estas falla, sabes que el error está en el propio objeto de valor, no en el cableado, una
+sesión o el bus.
+
+!!! tip "Aritmética de unidades menores"
+ `Money` almacena los importes en **unidades menores** (céntimos enteros). `Money(1050,
+ Currency.EUR)` representa 10,50 € —verificado por `major_units == 10.5` y
+ `str(...) == "10.50 EUR"`—. La fábrica `Money.zero(currency)` devuelve un
+ `Money(0, currency)`, útil para inicializar los saldos de los monederos.
+
+### Pruebas de la raíz de agregado Wallet
+
+`Wallet` hace cumplir varios invariantes: el propietario debe ser una cadena no vacía, los depósitos deben ser positivos, los retiros no deben dejar el saldo en descubierto y los importes deben coincidir con la moneda del monedero. Cada violación lleva un atributo `.rule` para una verificación precisa.
+
+Un término primero. Un **agregado** (o **raíz de agregado**) es un grupo de objetos de
+dominio tratado como una sola unidad de coherencia; aquí, el `Wallet` y su
+saldo. Todo cambio pasa por los métodos del agregado, así que el agregado es el
+único lugar que garantiza que sus invariantes se cumplen. Eso lo convierte en la unidad natural para
+probar: recórrelo a través de sus métodos públicos y comprueba que las reglas nunca se rompen.
+
+El patrón que sigue cada prueba de agregado es **organizar, actuar, comprobar** (arrange, act, assert). Organizar:
+construir el monedero en un estado conocido. Actuar: llamar a un método. Comprobar: verificar el
+saldo, el evento emitido o la violación lanzada. Búscalo en cada prueba:
+
+**Paso 1 — la apertura emite un evento.** `test_open_creates_empty_wallet` abre un monedero
+y comprueba que el saldo es cero y que se encola exactamente un evento `WalletOpened`.
+
+**Paso 2 — la apertura valida sus argumentos.** `test_open_requires_owner` pasa un
+propietario en blanco y espera `BusinessRuleViolation` con la regla
+`"wallet-owner-required"`.
+
+**Paso 3 — el camino feliz de depósito y luego retiro.**
+`test_deposit_then_withdraw_happy_path` deposita, comprueba el saldo y el
+evento `FundsDeposited`, luego retira y comprueba el saldo y el
+evento `FundsWithdrawn`. Fíjate en la llamada a `clear_events()` en el paso de organización; más sobre esto
+justo debajo del listado.
+
+**Paso 4 — los invariantes rechazan las operaciones inválidas.** Las tres pruebas finales demuestran que un
+retiro no puede dejar el saldo en descubierto, que un depósito debe ser positivo y que un importe debe coincidir con la
+moneda del monedero. Cada una comprueba la cadena `.rule` exacta, y la prueba de descubierto también
+comprueba que el saldo quedó sin cambios y que no se lanzó ningún evento, prueba de que el invariante
+se disparó *antes* de que cambiara ningún estado.
+
+::: listing tests/test_wallet_aggregate.py | Listado 16.2 — Pruebas unitarias de la raíz de agregado Wallet
+from __future__ import annotations
+
+import pytest
+from lumen.interfaces.enums.v1.currency import Currency
+from lumen.models.entities.v1.money import Money
+from lumen.models.entities.v1.wallet_entity import (
+ FundsDeposited,
+ FundsWithdrawn,
+ Wallet,
+ WalletOpened,
+)
+
+from pyfly.domain import BusinessRuleViolation
+
+
+def test_open_creates_empty_wallet() -> None:
+ wallet = Wallet.open("wlt-1", "owner-1", Currency.EUR)
+ assert wallet.owner_id == "owner-1"
+ assert wallet.currency is Currency.EUR
+ assert wallet.balance == Money.zero(Currency.EUR)
+ [event] = wallet.pending_events()
+ assert isinstance(event, WalletOpened)
+ assert event.wallet_id == "wlt-1"
+ assert event.currency == "EUR"
+
+
+def test_open_requires_owner() -> None:
+ with pytest.raises(BusinessRuleViolation) as exc:
+ Wallet.open("wlt-x", " ", Currency.EUR)
+ assert exc.value.rule == "wallet-owner-required"
+
+
+def test_deposit_then_withdraw_happy_path() -> None:
+ wallet = Wallet.open("wlt-2", "owner-2", Currency.EUR)
+ wallet.clear_events()
+
+ wallet.deposit(Money(1000, Currency.EUR))
+ assert wallet.balance == Money(1000, Currency.EUR)
+ [event] = wallet.clear_events()
+ assert isinstance(event, FundsDeposited)
+ assert event.amount == 1000
+ assert event.balance == 1000
+
+ wallet.withdraw(Money(400, Currency.EUR))
+ assert wallet.balance == Money(600, Currency.EUR)
+ [event] = wallet.clear_events()
+ assert isinstance(event, FundsWithdrawn)
+ assert event.amount == 400
+ assert event.balance == 600
+
+
+def test_withdraw_cannot_overdraw() -> None:
+ wallet = Wallet.open("wlt-3", "owner-3", Currency.EUR)
+ wallet.deposit(Money(500, Currency.EUR))
+ wallet.clear_events()
+ with pytest.raises(BusinessRuleViolation) as exc:
+ wallet.withdraw(Money(501, Currency.EUR))
+ assert exc.value.rule == "wallet-insufficient-funds"
+ # invariant held: balance unchanged, no event raised
+ assert wallet.balance == Money(500, Currency.EUR)
+ assert wallet.pending_events() == []
+
+
+def test_deposit_must_be_positive() -> None:
+ wallet = Wallet.open("wlt-4", "owner-4", Currency.EUR)
+ with pytest.raises(BusinessRuleViolation) as exc:
+ wallet.deposit(Money(0, Currency.EUR))
+ assert exc.value.rule == "wallet-deposit-positive"
+
+
+def test_currency_mismatch_is_rejected() -> None:
+ wallet = Wallet.open("wlt-5", "owner-5", Currency.EUR)
+ with pytest.raises(BusinessRuleViolation) as exc:
+ wallet.deposit(Money(100, Currency.USD))
+ assert exc.value.rule == "wallet-currency-mismatch"
+:::
+
+Tres detalles merecen atención. Primero, `Wallet.open` toma tres argumentos posicionales: un `wallet_id` pregenerado, un `owner_id` y un valor de enumeración `Currency`; el agregado no genera su propio ID. Segundo, `pending_events()` devuelve los eventos almacenados en búfer sin vaciarlos; `clear_events()` los devuelve y los vacía. La prueba `test_deposit_then_withdraw_happy_path` llama a `clear_events()` tras la apertura para que cada aserción vea exactamente un evento. Tercero, `FundsDeposited` y `FundsWithdrawn` llevan `amount` (el importe de la operación en unidades menores) y `balance` (el saldo acumulado tras la operación), no `new_balance`. Verifica siempre los campos reales de la dataclass del evento antes de comprobarlos.
+
+**Ejecútalo.**
+
+```bash
+uv run --extra dev pytest tests/test_wallet_aggregate.py -q
+```
+
+Salida esperada:
+
+```text
+...... [100%]
+6 passed in 0.02s
+```
+
+*Qué acaba de pasar.* La línea más difícil de leer es la asignación
+`[event] = wallet.clear_events()`. Eso es un desempaquetado de lista: comprueba que la lista devuelta
+tiene **exactamente un** elemento y lo enlaza a `event` en un solo paso. Si el
+agregado hubiera lanzado cero o dos eventos, el propio desempaquetado lanzaría un
+`ValueError` y la prueba fallaría, así que la forma del flujo de eventos se comprueba
+gratis. Por eso la prueba del camino feliz llama a `clear_events()` justo después de la apertura:
+vacía el evento `WalletOpened` para que el siguiente desempaquetado vea solo el
+evento `FundsDeposited` que realmente estás comprobando.
+
+!!! spring "Equivalencia con Spring"
+ Probar un agregado DDD de forma aislada es la misma disciplina en cualquier stack. En
+ Spring / jMolecules llamarías a los métodos del agregado directamente y
+ comprobarías `aggregate.domainEvents()` (proporcionado por `AbstractAggregateRoot`)
+ antes de llamar a `afterDomainEventPublication()` para vaciar el búfer. El
+ `clear_events()` de PyFly cumple el mismo papel: vaciar, comprobar, seguir.
+
+---
+
+## Cableado del stack de pruebas con conftest.py
+
+Las pruebas de CQRS y de listeners de eventos necesitan infraestructura real: un `WalletRepository` respaldado por SQLite, un bus de eventos, manejadores de comandos y consultas y un bus en marcha. En lugar de recrear esto en cada módulo de prueba, Lumen declara el cableado una sola vez en `tests/conftest.py`. Pytest descubre el archivo automáticamente y pone los fixtures a disposición de cada prueba del paquete.
+
+La diferencia clave respecto a una prueba de adaptador montada a mano es que el fixture `repository` usa el **`WalletRepository` real del framework** —la misma clase al estilo Spring Data que arranca la aplicación— y lo ejecuta a través del **`RepositoryBeanPostProcessor` real**, que compila los esbozos de consulta derivada a partir de los nombres de método al arrancar.
+
+Este archivo es el corazón del capítulo, así que lo leeremos de arriba abajo como una serie
+de pasos pequeños y por capas. Cada fixture se construye sobre el anterior. Lo que hay que tener
+presente: pytest enlaza los fixtures por **nombre**. Cuando una función de fixture declara un
+parámetro, pytest busca un fixture con ese nombre, lo construye y lo inyecta. Así
+es como un pequeño grafo de fixtures independientes se compone en un stack de pruebas completo.
+
+**Paso 1 — hacer que la muestra sea importable.** Las primeras líneas añaden el `src/` de la
+muestra a `sys.path` para que `import lumen...` se resuelva. El ajuste `pythonpath = ["src"]`
+de `pyproject.toml` hace lo mismo para la recopilación de la propia pytest; esta
+línea cubre las importaciones directas dentro de `conftest.py` antes de que se apliquen los ajustes de ruta de pytest.
+
+**Paso 2 — `session_factory`: un motor de base de datos.** Este fixture asíncrono crea un
+motor SQLite en memoria, ejecuta `Base.metadata.create_all` para construir el esquema y
+entrega un `async_sessionmaker`. Una **fábrica de sesiones** es un invocable que reparte
+sesiones de base de datos nuevas; la autoconfiguración relacional del framework crea una
+exactamente así al arrancar. El único motor compartido mantiene la base de datos en memoria
+viva durante toda la prueba: ciérralo y los datos se esfuman.
+
+**Paso 3 — `repository`: el repositorio real al estilo Spring Data.** Construye el
+`WalletRepository` del framework, luego llama a
+`RepositoryBeanPostProcessor().after_init(repo, "walletRepository")`. Un
+**post-procesador** es un gancho que se ejecuta contra un bean recién creado; aquí lee
+nombres de método como `find_by_owner_id` y los compila en consultas reales. Si te saltas esta
+llamada, esos métodos siguen siendo esbozos que lanzan `NotImplementedError`.
+
+**Paso 4 — `event_bus`: el bus de eventos en memoria.** Un fixture de una línea que entrega un
+`InMemoryEventBus`, el mismo publicador que usa la aplicación en despliegues sin Kafka.
+
+**Paso 5 — `audit_listener`: un suscriptor en ese bus.** Crea el
+`WalletAuditListener` y suscribe su manejador al bus, leyendo los patrones de
+evento directamente del atributo `__pyfly_event_patterns__` del método decorado:
+exactamente lo que hace el `ApplicationContext` cuando autocablea los listeners al arrancar.
+
+**Paso 6 — `command_bus` y `query_bus`: los despachadores de CQRS.** Cada uno construye un
+`HandlerRegistry`, registra los manejadores reales (pasándoles el `repository`,
+el `event_bus` y la `session_factory` que necesitan) y entrega un bus. **CQRS**
+—Command/Query Responsibility Segregation— significa simplemente que las escrituras van por un bus de
+comandos y las lecturas por un bus de consultas; un **manejador (handler)** es la función que de hecho
+procesa un comando o una consulta.
+
+::: listing tests/conftest.py | Listado 16.3 — conftest.py: componentes reales del framework cableados sin mocks
+from __future__ import annotations
+
+import sys
+from collections.abc import AsyncIterator
+from pathlib import Path
+
+import pytest_asyncio
+from sqlalchemy.ext.asyncio import (
+ AsyncSession,
+ async_sessionmaker,
+ create_async_engine,
+)
+
+# Make the sample's `src/` importable
+_HERE = Path(__file__).resolve().parent
+_SRC = _HERE.parent / "src"
+sys.path.insert(0, str(_SRC))
+
+from lumen.core.services.listeners import WalletAuditListener
+from lumen.core.services.wallets import (
+ DepositFundsHandler,
+ GetBalanceHandler,
+ GetWalletHandler,
+ ListRichWalletsHandler,
+ ListWalletsHandler,
+ OpenWalletHandler,
+ WithdrawFundsHandler,
+)
+from lumen.models.entities.v1.wallet_orm import WalletEntity
+from lumen.models.repositories import WalletRepository
+
+from pyfly.cqrs import DefaultCommandBus, DefaultQueryBus, HandlerRegistry
+from pyfly.data.relational.sqlalchemy import Base
+from pyfly.data.relational.sqlalchemy.post_processor import (
+ RepositoryBeanPostProcessor,
+)
+from pyfly.eda.adapters.memory import InMemoryEventBus
+
+
+@pytest_asyncio.fixture
+async def session_factory() -> AsyncIterator[async_sessionmaker[AsyncSession]]:
+ """An in-memory SQLite engine + session factory, schema created.
+
+ Mirrors the framework's relational auto-configuration: build the
+ async engine and run Base.metadata.create_all.
+ """
+ engine = create_async_engine("sqlite+aiosqlite:///:memory:")
+ async with engine.begin() as conn:
+ await conn.run_sync(Base.metadata.create_all)
+ factory = async_sessionmaker(engine, expire_on_commit=False)
+ try:
+ yield factory
+ finally:
+ await engine.dispose()
+
+
+@pytest_asyncio.fixture
+async def repository(
+ session_factory: async_sessionmaker[AsyncSession],
+) -> AsyncIterator[WalletRepository]:
+ """The framework WalletRepository, post-processed.
+
+ RepositoryBeanPostProcessor compiles derived-query stubs
+ (e.g. find_by_owner_id) onto the bean — the same step the
+ ApplicationContext runs at startup.
+ """
+ session = session_factory()
+ repo = WalletRepository(WalletEntity, session)
+ RepositoryBeanPostProcessor().after_init(repo, "walletRepository")
+ try:
+ yield repo
+ finally:
+ await session.close()
+
+
+@pytest_asyncio.fixture
+async def event_bus() -> AsyncIterator[InMemoryEventBus]:
+ """A real in-memory EDA bus — the same EventPublisher used in
+ production."""
+ yield InMemoryEventBus()
+
+
+@pytest_asyncio.fixture
+async def audit_listener(
+ event_bus: InMemoryEventBus,
+) -> AsyncIterator[WalletAuditListener]:
+ """The wallet audit projection, subscribed to the bus exactly as the
+ ApplicationContext auto-wires it at startup."""
+ listener = WalletAuditListener()
+ method = listener.on_wallet_event
+ for pattern in method.__pyfly_event_patterns__:
+ event_bus.subscribe(pattern, method)
+ yield listener
+
+
+@pytest_asyncio.fixture
+async def command_bus(
+ repository: WalletRepository,
+ event_bus: InMemoryEventBus,
+ session_factory: async_sessionmaker[AsyncSession],
+) -> AsyncIterator[DefaultCommandBus]:
+ registry = HandlerRegistry()
+ registry.register_command_handler(
+ OpenWalletHandler(
+ repository=repository,
+ events=event_bus,
+ session_factory=session_factory,
+ )
+ )
+ registry.register_command_handler(
+ DepositFundsHandler(
+ repository=repository,
+ events=event_bus,
+ session_factory=session_factory,
+ )
+ )
+ registry.register_command_handler(
+ WithdrawFundsHandler(
+ repository=repository,
+ events=event_bus,
+ session_factory=session_factory,
+ )
+ )
+ yield DefaultCommandBus(registry=registry)
+
+
+@pytest_asyncio.fixture
+async def query_bus(
+ repository: WalletRepository,
+) -> AsyncIterator[DefaultQueryBus]:
+ registry = HandlerRegistry()
+ registry.register_query_handler(GetWalletHandler(repository=repository))
+ registry.register_query_handler(GetBalanceHandler(repository=repository))
+ registry.register_query_handler(
+ ListWalletsHandler(repository=repository)
+ )
+ registry.register_query_handler(
+ ListRichWalletsHandler(repository=repository)
+ )
+ yield DefaultQueryBus(registry=registry)
+:::
+
+Cada fixture se declara con `@pytest_asyncio.fixture` (no con el `@pytest.fixture` pelado) para que pytest-asyncio gestione el ciclo de vida del iterador asíncrono. `asyncio_mode = "auto"` en `pyproject.toml` hace que los fixtures y las pruebas asíncronas funcionen sin decoradores por función, pero el propio decorador del fixture debe seguir siendo `pytest_asyncio.fixture`.
+
+El fixture `session_factory` es compartido. Tanto `repository` como `command_bus` lo reciben, así que el mismo motor SQLite en memoria respalda las lecturas, las escrituras y la frontera `@transactional` que abren los manejadores. Los fixtures `audit_listener` y `command_bus` reciben ambos `event_bus`; pytest lo instancia una vez por prueba y lo comparte entre ellos, así que los eventos publicados por los manejadores de comandos son visibles para el listener.
+
+*Qué acaba de pasar.* Has cableado un stack de pruebas completo, con forma de producción —motor,
+repositorio, bus de eventos, listener y ambos buses de CQRS— enteramente desde fixtures, sin
+mocks. Los dos hechos que lo hacen funcionar merecen retenerse. Primero, **los fixtures
+se componen por nombre**: `command_bus` pide `repository`, `event_bus` y
+`session_factory` simplemente nombrándolos como parámetros, y pytest entrelaza el grafo
+por ti. Segundo, **un fixture solicitado por otros dos se construye una vez por prueba**: tanto
+`repository` como `command_bus` nombran `session_factory`, así que comparten un solo motor;
+la escritura que hace un comando es la lectura que ve una consulta. Acierta con este
+archivo y cada prueba de las siguientes cuatro secciones será una llamada de dos líneas.
+
+!!! spring "Equivalencia con Spring"
+ `conftest.py` es el `@TestConfiguration` de PyFly más el compartido
+ `application-test.properties` de un proyecto Spring Boot: un único lugar que
+ declara los beans que cada prueba reutiliza. Un `@pytest_asyncio.fixture` es el equivalente
+ aproximado de un método `@Bean` en esa configuración: pytest lo construye de forma perezosa, lo inyecta
+ donde se solicita su nombre y lo desmonta después, igual que el contexto de pruebas de Spring
+ gestiona el ciclo de vida y la inyección de los beans.
+
+!!! tip "Nada de mocks en ningún sitio"
+ Cada componente de `conftest.py` es la implementación real de producción.
+ `WalletRepository` es la misma clase que arranca la aplicación.
+ `RepositoryBeanPostProcessor` es el mismo post-procesador que el
+ `ApplicationContext` ejecuta al arrancar para compilar los esbozos de consulta derivada.
+ `InMemoryEventBus` es el mismo bus que se usa en despliegues sin Kafka. El
+ objetivo es probar los caminos de código reales, no el cableado.
+
+---
+
+## Pruebas del flujo CQRS de extremo a extremo
+
+Con los fixtures de `conftest.py`, ejercitar el ciclo completo de comando/consulta es cuestión de llamar a `command_bus.send(...)` y `query_bus.query(...)`. No se instancia ningún manejador en el cuerpo de la prueba: el bus despacha al manejador ya registrado en el fixture.
+
+Fíjate en lo corto que se vuelve el cuerpo de cada prueba ahora que el cableado vive en `conftest.py`.
+Una prueba declara los fixtures que necesita como parámetros y luego se lee como una narración llana:
+
+**Paso 1 — solicitar los buses.** La firma de cada prueba enumera `command_bus` o
+`query_bus`. pytest ve esos nombres, construye el grafo de fixtures desde `conftest.py`
+e inyecta los buses listos.
+
+**Paso 2 — enviar comandos.** `await command_bus.send(OpenWallet(...))` devuelve el id del nuevo
+monedero; los comandos `DepositFunds` y `WithdrawFunds` posteriores devuelven el saldo
+acumulado. Compruebas cada valor de retorno sobre la marcha.
+
+**Paso 3 — consultar el lado de lectura.** `await query_bus.query(GetWallet(...))` y
+`GetBalance(...)` recargan el estado persistido y devuelven DTO (objetos de transferencia de datos,
+modelos de lectura simples). Compruebas que sus campos coinciden con lo que escribieron los comandos.
+
+**Paso 4 — demostrar los caminos de error.** Las pruebas restantes envían un comando que debe fallar
+—un descubierto, un depósito no positivo, un monedero desconocido— envuelto en
+`pytest.raises(CommandProcessingException)`. Ese gestor de contexto comprueba que el bloque
+lanza la excepción nombrada; si no lo hace, la prueba falla.
+
+::: listing tests/test_cqrs_flow.py | Listado 16.4 — Pruebas CQRS de extremo a extremo a través del bus real
+from __future__ import annotations
+
+import pytest
+from lumen.core.services.wallets.deposit_funds_command import DepositFunds
+from lumen.core.services.wallets.get_balance_query import GetBalance
+from lumen.core.services.wallets.get_wallet_query import GetWallet
+from lumen.core.services.wallets.open_wallet_command import OpenWallet
+from lumen.core.services.wallets.withdraw_funds_command import WithdrawFunds
+from lumen.interfaces.enums.v1.currency import Currency
+
+from pyfly.cqrs import DefaultCommandBus, DefaultQueryBus
+
+
+@pytest.mark.asyncio
+async def test_full_wallet_lifecycle(
+ command_bus: DefaultCommandBus,
+ query_bus: DefaultQueryBus,
+) -> None:
+ wallet_id = await command_bus.send(
+ OpenWallet(owner_id="u-1", currency=Currency.EUR)
+ )
+ assert isinstance(wallet_id, str) and wallet_id.startswith("wlt-")
+
+ balance = await command_bus.send(
+ DepositFunds(wallet_id=wallet_id, amount=1500)
+ )
+ assert balance == 1500
+
+ balance = await command_bus.send(
+ WithdrawFunds(wallet_id=wallet_id, amount=500)
+ )
+ assert balance == 1000
+
+ wallet = await query_bus.query(GetWallet(wallet_id=wallet_id))
+ assert wallet is not None
+ assert wallet.id == wallet_id
+ assert wallet.owner_id == "u-1"
+ assert wallet.currency is Currency.EUR
+ assert wallet.balance_minor == 1000
+ assert wallet.balance == 10.0
+
+ balance_dto = await query_bus.query(GetBalance(wallet_id=wallet_id))
+ assert balance_dto is not None
+ assert balance_dto.balance_minor == 1000
+ assert balance_dto.balance == 10.0
+
+
+@pytest.mark.asyncio
+async def test_get_wallet_returns_none_for_unknown_id(
+ query_bus: DefaultQueryBus,
+) -> None:
+ assert await query_bus.query(
+ GetWallet(wallet_id="wlt-does-not-exist")
+ ) is None
+
+
+@pytest.mark.asyncio
+async def test_overdraw_is_rejected_through_the_bus(
+ command_bus: DefaultCommandBus,
+) -> None:
+ from pyfly.cqrs.exceptions import CommandProcessingException
+
+ wallet_id = await command_bus.send(
+ OpenWallet(owner_id="u-2", currency=Currency.EUR)
+ )
+ await command_bus.send(DepositFunds(wallet_id=wallet_id, amount=100))
+
+ with pytest.raises(CommandProcessingException):
+ await command_bus.send(
+ WithdrawFunds(wallet_id=wallet_id, amount=999)
+ )
+
+
+@pytest.mark.asyncio
+async def test_validation_rejects_non_positive_deposit(
+ command_bus: DefaultCommandBus,
+) -> None:
+ from pyfly.cqrs.exceptions import CommandProcessingException
+
+ wallet_id = await command_bus.send(
+ OpenWallet(owner_id="u-3", currency=Currency.EUR)
+ )
+ with pytest.raises(CommandProcessingException):
+ await command_bus.send(DepositFunds(wallet_id=wallet_id, amount=0))
+
+
+@pytest.mark.asyncio
+async def test_deposit_to_unknown_wallet_is_rejected(
+ command_bus: DefaultCommandBus,
+) -> None:
+ from pyfly.cqrs.exceptions import CommandProcessingException
+
+ with pytest.raises(CommandProcessingException):
+ await command_bus.send(
+ DepositFunds(wallet_id="wlt-nope", amount=100)
+ )
+:::
+
+`test_full_wallet_lifecycle` es la prueba de humo principal: envía cada comando en el orden natural y luego consulta tanto el DTO completo del monedero como el DTO de saldo. El DTO del monedero expone `balance_minor` (unidades menores enteras) y `balance` (unidades mayores como float); ambos derivan de la misma fila `WalletEntity` almacenada a través del repositorio.
+
+Las pruebas de los caminos de error verifican que el bus aflora correctamente las violaciones de dominio. **`CommandProcessingException`** es el envoltorio del bus para cualquier excepción lanzada dentro de un manejador, incluida `BusinessRuleViolation` del agregado. El código que llama nunca ve la excepción de dominio en bruto; siempre ve el envoltorio del bus.
+
+**Ejecútalo.**
+
+```bash
+uv run --extra dev pytest tests/test_cqrs_flow.py -q
+```
+
+Salida esperada:
+
+```text
+..... [100%]
+5 passed in 0.05s
+```
+
+*Qué acaba de pasar.* Esta es la primera capa que toca infraestructura real, y
+aun así se ejecuta en milisegundos. El comando pasó por el bus real, el manejador
+real abrió una unidad de trabajo `@transactional` real sobre una sesión SQLite real,
+la confirmó (commit), y la consulta la leyó de vuelta: el camino exacto que se ejecuta en producción,
+menos la capa HTTP. Como el manejador se registra en el fixture en lugar de
+construirse en la prueba, estás probando el *despacho* además de la lógica: si el
+enrutamiento de comando a manejador se rompiera, estas pruebas lo atraparían.
+
+!!! note "asyncio_mode = \"auto\" y @pytest.mark.asyncio"
+ Con `asyncio_mode = "auto"`, cada prueba asíncrona se recopila y ejecuta
+ automáticamente. El decorador `@pytest.mark.asyncio` **no es obligatorio** pero
+ es inocuo y hace que la intención asíncrona resulte explícita de un vistazo. Lumen lo conserva
+ por claridad.
+
+---
+
+## Pruebas del adaptador del repositorio
+
+Las pruebas de flujo CQRS demuestran la canalización completa de apertura/depósito/retiro/consulta. Las pruebas del adaptador del repositorio van un nivel más hondo: ejercitan directamente la API de `WalletRepository` —CRUD, **consultas derivadas** compiladas a partir de nombres de método, paginación con **`Pageable`/`Page`** y predicados de tipo **`Specification`**— contra una base de datos SQLite en un archivo temporal. Sin Docker, sin proceso externo, sin red. El fixture integrado `tmp_path` de pytest proporciona un directorio temporal que se limpia automáticamente tras cada prueba.
+
+El fixture local `_make_repo` refleja lo que hace el `ApplicationContext` al arrancar: construir el repositorio y ejecutar `RepositoryBeanPostProcessor.after_init` para compilar los esbozos de consulta derivada. Sin esa llamada, métodos como `find_by_owner_id` lanzarían `NotImplementedError`.
+
+Dos términos antes del listado. Una **consulta derivada** es un método de repositorio cuyo cuerpo
+se genera a partir de su *nombre*: `find_by_owner_id` se convierte en `WHERE owner_id = :value`,
+sin SQL escrito a mano. Una **Specification** es un objeto predicado reutilizable y componible
+que pasas a una consulta —`balance_at_least(1000)` es uno— para filtros demasiado
+dinámicos como para incrustarlos en un nombre de método. La **paginación** envuelve ambos: `Pageable.of(page,
+size, sort)` describe qué porción quieres, y la consulta devuelve una `Page` que lleva
+los elementos más `total`, `total_pages` y `has_next`.
+
+Esta sección usa una base de datos SQLite **basada en archivo** (vía `tmp_path`) en lugar de la
+de en memoria, para poder demostrar una propiedad más fuerte: la durabilidad tras una reconexión.
+Esta es la forma de cada prueba:
+
+**Paso 1 — `sqlite_factory`: un motor sobre archivo temporal.** El fixture construye un motor SQLite
+respaldado por un archivo real bajo el `tmp_path` de pytest (un directorio temporal nuevo por prueba,
+autoeliminado después), crea el esquema y entrega tanto la fábrica como la URL.
+Entregar la URL es lo que permite que una prueba se reconecte con un motor totalmente nuevo.
+
+**Paso 2 — CRUD y persistencia.**
+`test_upsert_inserts_then_updates_and_persists` hace un upsert de una fila, lo repite con
+un nuevo saldo para demostrar la actualización en sitio, hace commit, la lee de vuelta y luego desecha el
+motor y se reconecta con uno *nuevo* para demostrar que los datos realmente llegaron al disco.
+
+**Paso 3 — el camino de id desconocido.** `test_find_by_id_unknown_returns_none` confirma que un
+fallo devuelve `None`, no un error.
+
+**Paso 4 — consulta derivada.** `test_derived_find_by_owner_id` inserta monederos para dos
+propietarios y comprueba que `find_by_owner_id("alice")` devuelve solo los de Alice: prueba de que el
+post-procesador compiló correctamente la convención de nombres de método.
+
+**Paso 5 — Specification + paginación.**
+`test_specification_find_rich_paged_and_sorted` y
+`test_find_all_pageable_counts_and_pages` ejercitan el camino del predicado `find_rich` /
+`find_all_by_spec` y el camino de paginación `find_all(pageable)`, comprobando
+`total`, `total_pages`, `has_next` y el orden exacto de `page.items`.
+
+::: listing tests/test_sql_wallet_repository.py | Listado 16.5 — Pruebas de repositorio: CRUD, consulta derivada, paginación, Specification
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+
+import pytest
+import pytest_asyncio
+from sqlalchemy.ext.asyncio import (
+ AsyncSession,
+ async_sessionmaker,
+ create_async_engine,
+)
+
+from lumen.models.entities.v1.wallet_orm import WalletEntity
+from lumen.models.repositories.wallet_repository import (
+ WalletRepository,
+ balance_at_least,
+)
+from pyfly.data import Pageable, Sort
+from pyfly.data.relational.sqlalchemy import Base
+from pyfly.data.relational.sqlalchemy.post_processor import (
+ RepositoryBeanPostProcessor,
+)
+
+
+def _entity(
+ wid: str,
+ owner: str,
+ minor: int,
+ *,
+ currency: str = "EUR",
+ age_days: int = 0,
+) -> WalletEntity:
+ created = datetime.now(UTC) - timedelta(days=age_days)
+ return WalletEntity(
+ id=wid,
+ owner_id=owner,
+ currency=currency,
+ balance_minor=minor,
+ created_at=created,
+ )
+
+
+def _make_repo(session: AsyncSession) -> WalletRepository:
+ repo = WalletRepository(WalletEntity, session)
+ # Mirror the ApplicationContext: compile derived-query stubs.
+ RepositoryBeanPostProcessor().after_init(repo, "walletRepository")
+ return repo
+
+
+@pytest_asyncio.fixture
+async def sqlite_factory(
+ tmp_path: Path,
+) -> AsyncIterator[tuple[async_sessionmaker[AsyncSession], str]]:
+ """A temp-file SQLite engine + session factory, schema created.
+
+ Yields the session factory and the database URL so the test can
+ reconnect with a fresh engine to verify true persistence.
+ """
+ db_url = f"sqlite+aiosqlite:///{tmp_path / 'wallets.db'}"
+ engine = create_async_engine(db_url)
+ async with engine.begin() as conn:
+ await conn.run_sync(Base.metadata.create_all)
+ factory = async_sessionmaker(engine, expire_on_commit=False)
+ try:
+ yield factory, db_url
+ finally:
+ await engine.dispose()
+
+
+@pytest.mark.asyncio
+async def test_upsert_inserts_then_updates_and_persists(
+ sqlite_factory: tuple[async_sessionmaker[AsyncSession], str],
+) -> None:
+ factory, db_url = sqlite_factory
+
+ async with factory() as session:
+ repo = _make_repo(session)
+ await repo.upsert(_entity("wlt-1", "owner-42", 0, currency="USD"))
+ # update: same PK, new balance
+ await repo.upsert(_entity("wlt-1", "owner-42", 2500, currency="USD"))
+ await session.commit()
+
+ got = await repo.find_by_id("wlt-1")
+ assert got is not None
+ assert got.owner_id == "owner-42"
+ assert got.currency == "USD"
+ assert got.balance_minor == 2500
+ assert await repo.count() == 1
+
+ # prove persistence: reconnect with a brand-new engine/session
+ fresh_engine = create_async_engine(db_url)
+ fresh_factory = async_sessionmaker(fresh_engine, expire_on_commit=False)
+ try:
+ async with fresh_factory() as fresh_session:
+ fresh_repo = _make_repo(fresh_session)
+ persisted = await fresh_repo.find_by_id("wlt-1")
+ assert persisted is not None, "wallet should survive a reconnect"
+ assert persisted.balance_minor == 2500
+ finally:
+ await fresh_engine.dispose()
+
+
+@pytest.mark.asyncio
+async def test_find_by_id_unknown_returns_none(
+ sqlite_factory: tuple[async_sessionmaker[AsyncSession], str],
+) -> None:
+ factory, _ = sqlite_factory
+ async with factory() as session:
+ repo = _make_repo(session)
+ assert await repo.find_by_id("wlt-nope") is None
+
+
+@pytest.mark.asyncio
+async def test_derived_find_by_owner_id(
+ sqlite_factory: tuple[async_sessionmaker[AsyncSession], str],
+) -> None:
+ factory, _ = sqlite_factory
+ async with factory() as session:
+ repo = _make_repo(session)
+ await repo.upsert(_entity("wlt-1", "alice", 100))
+ await repo.upsert(_entity("wlt-2", "alice", 200))
+ await repo.upsert(_entity("wlt-3", "bob", 300))
+ await session.commit()
+
+ owned = await repo.find_by_owner_id("alice")
+ assert sorted(w.id for w in owned) == ["wlt-1", "wlt-2"]
+ assert await repo.find_by_owner_id("nobody") == []
+
+
+@pytest.mark.asyncio
+async def test_specification_find_rich_paged_and_sorted(
+ sqlite_factory: tuple[async_sessionmaker[AsyncSession], str],
+) -> None:
+ factory, _ = sqlite_factory
+ async with factory() as session:
+ repo = _make_repo(session)
+ # age_days drives created_at so we can assert newest-first ordering.
+ await repo.upsert(_entity("wlt-poor", "a", 50, age_days=3))
+ await repo.upsert(_entity("wlt-mid", "b", 1000, age_days=2))
+ await repo.upsert(_entity("wlt-rich", "c", 5000, age_days=1))
+ await session.commit()
+
+ # Specification: balance_minor >= 1000, newest first, page size 1.
+ newest_first = Sort.by("created_at").descending()
+ page = await repo.find_rich(1000, Pageable.of(1, 1, newest_first))
+ assert page.total == 2 # mid + rich
+ assert page.total_pages == 2
+ assert page.has_next is True
+ assert [w.id for w in page.items] == ["wlt-rich"]
+
+ page2 = await repo.find_rich(1000, Pageable.of(2, 1, newest_first))
+ assert [w.id for w in page2.items] == ["wlt-mid"]
+
+ # The bare predicate also works through find_all_by_spec.
+ rich = await repo.find_all_by_spec(balance_at_least(5000))
+ assert [w.id for w in rich] == ["wlt-rich"]
+
+
+@pytest.mark.asyncio
+async def test_find_all_pageable_counts_and_pages(
+ sqlite_factory: tuple[async_sessionmaker[AsyncSession], str],
+) -> None:
+ factory, _ = sqlite_factory
+ async with factory() as session:
+ repo = _make_repo(session)
+ for i in range(5):
+ await repo.upsert(
+ _entity(f"wlt-{i}", "owner", i * 100, age_days=5 - i)
+ )
+ await session.commit()
+
+ page = await repo.find_all(
+ Pageable.of(1, 2, Sort.by("created_at").descending())
+ )
+ assert page.total == 5
+ assert page.total_pages == 3
+ assert len(page.items) == 2
+ # newest first -> wlt-4 (age 1 day), then wlt-3
+ assert [w.id for w in page.items] == ["wlt-4", "wlt-3"]
+:::
+
+Cuatro cosas a destacar. Primero, `_make_repo` llama a `RepositoryBeanPostProcessor().after_init(repo, ...)`; sin esto, `find_by_owner_id` sigue siendo un esbozo y lanza `NotImplementedError`. El post-procesador compila el nombre de método en una cláusula `WHERE owner_id = :owner_id` de SQLAlchemy. Segundo, `upsert` es la inserción-o-actualización del repositorio; tras cada lote de upserts, `await session.commit()` vuelca a SQLite. Tercero, `find_rich` toma un saldo mínimo y un `Pageable`; delega en `find_all_by_spec_paged(balance_at_least(min), pageable)`. Cuarto, el patrón de dos motores en `test_upsert_inserts_then_updates_and_persists` demuestra la durabilidad verdadera: los datos confirmados a través de un motor son legibles por un motor y una sesión completamente nuevos.
+
+**Ejecútalo.**
+
+```bash
+uv run --extra dev pytest tests/test_sql_wallet_repository.py -q
+```
+
+Salida esperada:
+
+```text
+..... [100%]
+5 passed in 0.06s
+```
+
+*Qué acaba de pasar.* Lo más notable es la reconexión de dos motores en la primera prueba.
+Muchas pruebas de "persistencia" pasan incluso cuando no se ha escrito nada en el disco, porque la misma
+sesión cachea el objeto en memoria y lo devuelve en la lectura. Al desechar el
+motor por completo y abrir un *segundo* motor contra la misma URL de archivo, esta prueba
+fuerza un viaje de ida y vuelta real al almacenamiento; si `upsert` o `commit` no estuvieran
+persistiendo silenciosamente, la reconexión devolvería `None` y la prueba fallaría. Esa es la
+diferencia entre probar tu código y probar tu caché.
+
+!!! spring "Equivalencia con Spring"
+ Esta capa de prueba es el equivalente en Python de `@DataJpaTest` con una base de datos
+ H2 embebida en Spring Boot. `@DataJpaTest` carga solo la capa JPA (entidades,
+ repositorios, Flyway) y cablea una H2 en memoria nueva para cada clase de prueba.
+ El fixture `sqlite_factory` hace lo mismo: crear el esquema, ejecutar las pruebas,
+ desechar el motor. Sin Docker, sin proceso externo.
+
+!!! tip "Las consultas derivadas son convenciones de nombre de método"
+ `WalletRepository.find_by_owner_id` se declara como un esbozo
+ (`raise NotImplementedError`). `RepositoryBeanPostProcessor` inspecciona el
+ nombre del método al arrancar —`find_by_owner_id` → `WHERE owner_id = :value`—
+ y reemplaza el esbozo por una corrutina real. Por tanto, probar este método
+ también prueba que la convención del post-procesador funciona correctamente.
+
+---
+
+## Pruebas del listener de eventos
+
+`WalletAuditListener` escucha los eventos de dominio publicados por los manejadores de comandos. Probarlo de extremo a extremo —el comando se ejecuta en el bus, el manejador publica eventos, el listener los recibe— requiere que los tres componentes compartan el mismo `InMemoryEventBus`. Los fixtures de `conftest.py` ya lo disponen: tanto `command_bus` como `audit_listener` aceptan un argumento `event_bus`, y pytest inyecta la misma instancia en ambos.
+
+Un **listener de eventos** es simplemente un método que el framework suscribe al bus para que se
+ejecute cada vez que se publica un evento coincidente. El `WalletAuditListener` de Lumen mantiene un
+registro de auditoría en memoria y un saldo acumulado por monedero: una pequeña **proyección** (un modelo de
+lectura construido plegando eventos). Probarlo es la demostración más clara del
+truco del fixture compartido: como `command_bus` y `audit_listener` nombran el mismo
+`event_bus`, un evento que publica un comando es un evento que observa el listener, sin
+pegamento alguno en el cuerpo de la prueba.
+
+Las pruebas siguen un solo ritmo:
+
+**Paso 1 — recorrer comandos.** Abrir un monedero, depositar, retirar; todo a través de
+`command_bus`.
+
+**Paso 2 — leer la proyección.** Llamar a `audit_listener.entries_for(wallet_id)` y
+comprobar los tipos de evento registrados, en orden, más el `running_total`.
+
+**Paso 3 — comprobar el negativo.** Una prueba deja deliberadamente el saldo en descubierto —un comando que
+debe fallar— y comprueba que el registro de auditoría no anota nada de él. Una operación fallida
+no deja rastro.
+
+::: listing tests/test_event_listener.py | Listado 16.6 — Pruebas del listener de eventos: el comando publica, el listener observa
+from __future__ import annotations
+
+import pytest
+from lumen.core.services.listeners import WalletAuditListener
+from lumen.core.services.wallets.deposit_funds_command import DepositFunds
+from lumen.core.services.wallets.open_wallet_command import OpenWallet
+from lumen.core.services.wallets.withdraw_funds_command import WithdrawFunds
+from lumen.interfaces.enums.v1.currency import Currency
+
+from pyfly.cqrs import DefaultCommandBus
+
+
+@pytest.mark.asyncio
+async def test_listener_observes_wallet_events(
+ command_bus: DefaultCommandBus,
+ audit_listener: WalletAuditListener,
+) -> None:
+ wallet_id = await command_bus.send(
+ OpenWallet(owner_id="u-1", currency=Currency.EUR)
+ )
+ await command_bus.send(DepositFunds(wallet_id=wallet_id, amount=1500))
+ await command_bus.send(WithdrawFunds(wallet_id=wallet_id, amount=400))
+
+ entries = audit_listener.entries_for(wallet_id)
+ assert [e.event_type for e in entries] == [
+ "WalletOpened",
+ "FundsDeposited",
+ "FundsWithdrawn",
+ ]
+
+ # The payload carried the real domain-event fields.
+ deposited = entries[1]
+ assert deposited.payload["amount"] == 1500
+ assert deposited.payload["currency"] == "EUR"
+ assert deposited.payload["balance"] == 1500
+ assert deposited.event_id # the aggregate's DomainEvent.event_id
+
+ # The running-total projection reflects deposit − withdrawal.
+ assert audit_listener.running_total(wallet_id) == 1100
+
+
+@pytest.mark.asyncio
+async def test_listener_records_nothing_before_any_command(
+ audit_listener: WalletAuditListener,
+) -> None:
+ assert audit_listener.entries == []
+ assert audit_listener.running_total("anything") == 0
+
+
+@pytest.mark.asyncio
+async def test_event_type_matches_domain_event_class_names(
+ command_bus: DefaultCommandBus,
+ audit_listener: WalletAuditListener,
+) -> None:
+ # A rejected withdrawal raises no event — it must not appear in the log.
+ wallet_id = await command_bus.send(
+ OpenWallet(owner_id="u-2", currency=Currency.USD)
+ )
+ await command_bus.send(DepositFunds(wallet_id=wallet_id, amount=100))
+
+ from pyfly.cqrs.exceptions import CommandProcessingException
+
+ with pytest.raises(CommandProcessingException):
+ await command_bus.send(
+ WithdrawFunds(wallet_id=wallet_id, amount=9999)
+ )
+
+ types = [e.event_type for e in audit_listener.entries_for(wallet_id)]
+ assert types == ["WalletOpened", "FundsDeposited"]
+ assert audit_listener.running_total(wallet_id) == 100
+:::
+
+`test_listener_observes_wallet_events` es la prueba de integración central: tres comandos producen tres eventos, el listener los registra los tres en orden, los campos del payload coinciden con los campos de la dataclass de evento del agregado y la proyección `running_total` es igual al resultado aritmético. Sin mock del bus, sin lista de captura de eventos: el listener de producción se ejecuta sobre el bus de producción.
+
+`test_event_type_matches_domain_event_class_names` demuestra un invariante de dominio: un comando rechazado (descubierto) no lanza ningún evento. El registro de auditoría nunca debe anotar un efecto secundario de una operación fallida.
+
+**Ejecútalo.**
+
+```bash
+uv run --extra dev pytest tests/test_event_listener.py -q
+```
+
+Salida esperada:
+
+```text
+... [100%]
+3 passed in 0.04s
+```
+
+*Qué acaba de pasar.* Ninguna parte de la prueba conectó el listener al bus: el
+fixture `audit_listener` hizo eso en `conftest.py`, suscribiendo el manejador al
+mismo `event_bus` por el que publica el `command_bus`. Así que enviar un comando y luego
+leer `entries_for(...)` ejercita el camino real de publicación/suscripción de extremo a extremo. La
+prueba negativa es la sutil: demuestra que el registro de auditoría se rige por *eventos*, no
+por *intentos*; un retiro rechazado lanza un `BusinessRuleViolation` antes de que se emita ningún
+evento, así que nada llega al listener.
+
+!!! tip "event_type es el nombre de la clase"
+ El publicador de eventos de PyFly fija `event_type` al nombre de la clase del evento de dominio:
+ `"WalletOpened"`, `"FundsDeposited"`, `"FundsWithdrawn"`. El
+ decorador `@event_listener(event_types=["WalletOpened", "FundsDeposited", "FundsWithdrawn"])`
+ sobre `WalletAuditListener.on_wallet_event` nombra esos tres tipos
+ explícitamente; el framework los almacena en el método como
+ `__pyfly_event_patterns__`, que el fixture `audit_listener` lee para suscribirse.
+ La prueba comprueba directamente las cadenas con los nombres de clase.
+
+---
+
+## Prueba de integración con el contexto arrancado
+
+Las pruebas unitarias, las de flujo CQRS y las de repositorio cablean cada una una capa del stack. La prueba de integración con el contexto arrancado las cablea todas a la vez: inicia el `ApplicationContext` real —escaneo de componentes de inyección de dependencias, autoconfiguración de CQRS, autoconfiguración relacional, `RepositoryBeanPostProcessor`, la costura `@transactional`, el bus de eventos de la EDA— y luego resuelve el `DefaultCommandBus` y el `DefaultQueryBus` desde el contexto y recorre el ciclo de vida completo del monedero.
+
+El **ApplicationContext** es el contenedor en tiempo de ejecución de PyFly: el objeto que escanea en busca de
+componentes, construye beans, ejecuta post-procesadores y mantiene unida la aplicación
+cableada. Arrancarlo es la prueba más fiel que puedes escribir sin llegar a iniciar un
+servidor HTTP: cada pieza de cableado que el framework hace al arrancar ocurre de verdad.
+
+La URL de la base de datos se sustituye mediante una variable de entorno para que la prueba nunca toque el `lumen.db` del desarrollador. Este es el plan:
+
+**Paso 1 — aislar la base de datos.** El fixture `booted_context` usa el fixture
+`monkeypatch` de pytest para fijar `PYFLY_DATA_RELATIONAL_URL` a una ruta SQLite de archivo temporal
+bajo `tmp_path`, *antes* de que la aplicación arranque. `monkeypatch` es la forma segura de pytest de fijar una
+variable de entorno durante una sola prueba y restaurarla automáticamente
+después, así que esta prueba nunca puede pisar tu `lumen.db` real.
+
+**Paso 2 — arrancar la aplicación real.** Construye `PyFlyApplication(LumenApplication,
+config_path=...)` y `await app.startup()`. Esa única llamada ejecuta toda la secuencia de arranque:
+escaneo de componentes, todas las autoconfiguraciones, el `RepositoryBeanPostProcessor`
+y el bus de eventos. El fixture entrega `app.context` y, en su bloque `finally`,
+cierra la sesión compartida y llama a `app.shutdown()`.
+
+**Paso 3 — resolver beans y recorrer el ciclo de vida.** La prueba llama a
+`ctx.get_bean(DefaultCommandBus)` y `ctx.get_bean(DefaultQueryBus)` —obteniendo los
+*mismos* buses que usaría la aplicación— y luego ejecuta apertura → depósito → retiro → listado →
+ricos → saldo, comprobando cada resultado.
+
+::: listing tests/test_app_context_integration.py | Listado 16.7 — Integración con el contexto arrancado: composición completa de inyección de dependencias + persistencia
+from __future__ import annotations
+
+import logging
+import sys
+from collections.abc import AsyncIterator
+from pathlib import Path
+
+import pytest
+import pytest_asyncio
+from sqlalchemy.ext.asyncio import AsyncSession
+
+_HERE = Path(__file__).resolve().parent
+_SRC = _HERE.parent / "src"
+sys.path.insert(0, str(_SRC))
+
+
+@pytest_asyncio.fixture
+async def booted_context(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> AsyncIterator[object]:
+ """Boot the full LumenApplication against an isolated SQLite file."""
+ db_path = tmp_path / "lumen-it.db"
+ monkeypatch.setenv(
+ "PYFLY_DATA_RELATIONAL_URL",
+ f"sqlite+aiosqlite:///{db_path}",
+ )
+ # Silence the pool-GC warning that aiosqlite emits at teardown.
+ logging.getLogger(
+ "sqlalchemy.pool.impl.AsyncAdaptedQueuePool"
+ ).setLevel(logging.CRITICAL)
+
+ from lumen.app import LumenApplication
+ from pyfly.core import PyFlyApplication
+
+ app = PyFlyApplication(
+ LumenApplication,
+ config_path=str(_HERE.parent / "pyfly.yaml"),
+ )
+ await app.startup()
+ try:
+ yield app.context
+ finally:
+ await app.context.get_bean(AsyncSession).close()
+ await app.shutdown()
+
+
+@pytest.mark.asyncio
+async def test_full_lifecycle_through_booted_context(
+ booted_context: object,
+) -> None:
+ from lumen.core.services.wallets.deposit_funds_command import DepositFunds
+ from lumen.core.services.wallets.get_balance_query import GetBalance
+ from lumen.core.services.wallets.get_wallet_query import GetWallet
+ from lumen.core.services.wallets.list_rich_wallets_query import (
+ ListRichWallets,
+ )
+ from lumen.core.services.wallets.list_wallets_query import ListWallets
+ from lumen.core.services.wallets.open_wallet_command import OpenWallet
+ from lumen.core.services.wallets.withdraw_funds_command import WithdrawFunds
+ from lumen.interfaces.enums.v1.currency import Currency
+ from pyfly.cqrs import DefaultCommandBus, DefaultQueryBus
+ from pyfly.data import Pageable
+
+ ctx = booted_context
+ commands = ctx.get_bean(DefaultCommandBus)
+ queries = ctx.get_bean(DefaultQueryBus)
+
+ # --- open -> deposit -> withdraw, each a committed unit of work -------
+ w1 = await commands.send(OpenWallet(owner_id="u-1", currency=Currency.EUR))
+ w2 = await commands.send(OpenWallet(owner_id="u-2", currency=Currency.EUR))
+ assert w1.startswith("wlt-") and w2.startswith("wlt-")
+
+ assert await commands.send(DepositFunds(wallet_id=w1, amount=5000)) == 5000
+ assert await commands.send(WithdrawFunds(wallet_id=w1, amount=1500)) == 3500
+ assert await commands.send(DepositFunds(wallet_id=w2, amount=100)) == 100
+
+ # --- persistence survived: reload the aggregate via the query side ---
+ reloaded = await queries.query(GetWallet(wallet_id=w1))
+ assert reloaded is not None
+ assert reloaded.owner_id == "u-1"
+ assert reloaded.balance_minor == 3500
+
+ # --- paged list (find_all(pageable) + Page.map) ----------------------
+ page = await queries.query(ListWallets(pageable=Pageable.of(1, 10)))
+ assert page.total == 2
+ assert {w.id for w in page.items} == {w1, w2}
+
+ # --- Specification: only wallets with balance >= 1000 ----------------
+ rich = await queries.query(
+ ListRichWallets(min_minor=1000, pageable=Pageable.of(1, 10))
+ )
+ assert rich.total == 1
+ assert [w.id for w in rich.items] == [w1]
+
+ everyone = await queries.query(
+ ListRichWallets(min_minor=0, pageable=Pageable.of(1, 10))
+ )
+ assert everyone.total == 2
+
+ # --- projection-backed balance ---------------------------------------
+ balance = await queries.query(GetBalance(wallet_id=w1))
+ assert balance is not None
+ assert balance.balance_minor == 3500
+ assert balance.balance == 35.0
+:::
+
+`booted_context` usa el fixture integrado `monkeypatch` de pytest para fijar `PYFLY_DATA_RELATIONAL_URL` antes de que la aplicación arranque. El framework lee esta variable de entorno durante la autoconfiguración relacional, así que el contexto usa la base de datos SQLite de archivo temporal aislada durante la vida de la prueba, y luego la desecha cuando el fixture se desmonta.
+
+`test_full_lifecycle_through_booted_context` ejercita cada tipo de consulta que la aplicación expone: `GetWallet` (recarga del agregado), `ListWallets` (listado paginado usando `find_all(pageable)`), `ListRichWallets` (predicado de tipo Specification usando `find_all_by_spec_paged`) y `GetBalance` (saldo respaldado por proyección). Demuestra que el `RepositoryBeanPostProcessor`, la frontera `@transactional` alrededor de cada manejador de comandos y el cableado de inyección de dependencias se componen todos correctamente en un solo arranque.
+
+**Ejecútalo.**
+
+```bash
+uv run --extra dev pytest tests/test_app_context_integration.py -q
+```
+
+Salida esperada:
+
+```text
+. [100%]
+1 passed in 0.15s
+```
+
+Una prueba, pero la más pesada de la suite: realmente arrancó el framework. Si
+el escaneo de inyección de dependencias se saltó un bean, una autoconfiguración cableó mal o la frontera
+`@transactional` no consiguió hacer commit, esta es la prueba que lo atrapa, lo cual es exactamente por lo que
+se sitúa en la cima de la pirámide y por lo que solo hay una de ella.
+
+*Qué acaba de pasar.* La sustitución de la variable de entorno es el truco que lo sostiene todo.
+El framework lee `pyfly.data.relational.url` de la configuración durante la autoconfiguración
+relacional, y PyFly mapea cualquier clave de configuración a una variable de entorno `PYFLY_*`
+(los puntos y los guiones se vuelven guiones bajos, en mayúsculas), así que `PYFLY_DATA_RELATIONAL_URL`
+sustituye la `url` de `pyfly.yaml`. Fijarla con `monkeypatch` *antes* de
+`app.startup()` es lo que redirige toda la aplicación arrancada a una base de datos
+desechable, y `monkeypatch` deshace el cambio cuando el fixture se desmonta, así que ninguna
+otra prueba se ve afectada.
+
+!!! tip "Un perfil de prueba dedicado (v26.6.110)"
+ Fijar una variable está bien para una sola sustitución. Cuando un proyecto necesita un bloque
+ entero de ajustes solo de prueba, el mecanismo de **perfiles** de PyFly (equivalencia con Spring) es
+ más limpio: deja un `pyfly-test.yaml` junto a `pyfly.yaml` con tus sustituciones de prueba,
+ luego actívalo fijando `PYFLY_PROFILES_ACTIVE=test` (o
+ `pyfly.profiles.active: test` en la configuración). Al arrancar, PyFly superpone
+ `pyfly-test.yaml` sobre el `pyfly.yaml` base, así que valores como la URL de la base de datos
+ o `ddl-auto` se aplican solo bajo ese perfil. Lumen no necesita un perfil
+ —una sola sustitución de entorno cubre su único ajuste solo de prueba—, pero recurre a uno a medida que
+ la configuración de pruebas crezca.
+
+!!! spring "Equivalencia con Spring"
+ Esta prueba es el equivalente en Python de `@SpringBootTest` con una base de datos H2
+ embebida. `@SpringBootTest` carga el contexto de aplicación completo, incluidas todas las
+ autoconfiguraciones y la capa JPA; fijas `spring.datasource.url` en
+ `application-test.properties` para redirigir a H2. La sustitución de variable de entorno
+ de PyFly (`monkeypatch.setenv`) cumple el mismo papel. Ambos
+ enfoques demuestran que la aplicación compuesta funciona de extremo a extremo sin
+ infraestructura externa alguna.
+
+---
+
+## Ayudantes de pruebas del framework
+
+Las pruebas de arriba cubren la pirámide completa de Lumen con primitivas estándar de pytest y los componentes reales de producción de PyFly. Para aplicaciones más grandes o equipos que prefieren más estructura, `pyfly.testing` incluye ayudantes de más alto nivel que reflejan las anotaciones de pruebas de Spring Boot.
+
+**`PyFlyTestCase` + `mock_bean(T)`** funcionan como `@MockBean` en `@SpringBootTest`. Declara `repo = mock_bean(WalletDomainRepository)` en el cuerpo de la clase; `setup()` instala un `AsyncMock(spec=T)` en el contexto de aplicación y lo cablea en cualquier colaborador que dependa de él.
+
+**`create_test_container(overrides={Interface: Implementation})`** construye un contenedor de inyección de dependencias con dobles (fakes) registrados para interfaces concretas. Resuelve desde él la clase bajo prueba y sus dependencias ya quedan inyectadas.
+
+**`assert_event_published(events, event_type, payload_contains=...)`** rastrea una lista capturada de `EventEnvelope` en busca del primer sobre del tipo dado, opcionalmente comprueba claves del payload y devuelve el sobre para aserciones posteriores. `assert_no_events_published(events)` falla si la lista no está vacía.
+
+**Integración con Testcontainers** (`postgres_container()`, `redis_container()`, `pyfly_config(container, base={...})`) es el equivalente de PyFly a `@Testcontainers` + `@ServiceConnection` de Spring Boot. Arranca un contenedor Postgres real; `pyfly_config` reescribe la URL síncrona `psycopg2://` a `postgresql+asyncpg://` y la fusiona en un `Config` listo para arrancar un `ApplicationContext`. Instala el soporte con:
+
+```bash
+pip install 'pyfly[testcontainers]'
+```
+
+Protege cada prueba de Testcontainers con `@requires_docker` para que se omita limpiamente en máquinas sin Docker y se ejecute automáticamente en los ejecutores de CI que sí lo tengan:
+
+```python
+from pyfly.testing import postgres_container, pyfly_config, requires_docker
+
+@requires_docker
+async def test_wallet_round_trip_against_real_postgres():
+ with postgres_container() as pg:
+ config = pyfly_config(pg, base={"pyfly.data.enabled": True})
+ assert config.get("pyfly.data.relational.url").startswith(
+ "postgresql+asyncpg://"
+ )
+ ...
+```
+
+Lumen no usa estos ayudantes: SQLite cubre la capa de persistencia sin Docker, y el bus en memoria cubre el enrutamiento de eventos. Recurre a ellos cuando tu proyecto tenga infraestructura que no pueda reproducirse sin un demonio real.
+
+**Ejecútalo.** Ya has recorrido cada capa archivo a archivo. Ejecuta toda la suite una vez
+más para confirmar que la pirámide completa está en verde en conjunto:
+
+```bash
+uv run --extra dev pytest -q
+```
+
+Salida esperada: el mismo `41 passed` con el que empezaste, ahora con un modelo mental de
+exactamente lo que demuestra cada punto:
+
+```text
+......................................... [100%]
+41 passed in 0.28s
+```
+
+---
+
+## Lo que construiste {.recap}
+
+Los seis archivos de prueba que construyó este capítulo suman 26 pruebas superadas, ejercitando cada capa de la pirámide. Junto con las pruebas de la saga del Capítulo 12 y las pruebas de event sourcing del Capítulo 9, la suite completa de Lumen son **41 pruebas superadas**: el recuento que viste cuando ejecutaste `uv run --extra dev pytest -q` al principio.
+
+En la base, `test_money.py` y `test_wallet_aggregate.py` demuestran la aritmética, la inmutabilidad y las reglas de invariante del modelo de dominio. Todas las pruebas son funciones síncronas de Python puro, sin fixtures, sin inyección de dependencias, sin `async`. El atributo `BusinessRuleViolation.rule` hace que cada aserción sea específica del invariante exacto incumplido.
+
+En el centro, `conftest.py` cablea los componentes reales —el `WalletRepository` del framework sobre un motor SQLite en memoria, `InMemoryEventBus`, los cinco manejadores de comandos y consultas (incluidos `ListWalletsHandler` y `ListRichWalletsHandler`) y `WalletAuditListener`— en fixtures asíncronos reutilizables que pytest comparte automáticamente entre módulos. El `RepositoryBeanPostProcessor` se aplica al fixture del repositorio exactamente como el `ApplicationContext` lo aplica al arrancar. `test_cqrs_flow.py` despacha comandos y consultas a través del bus real y comprueba cada campo de los DTO de consulta. `test_event_listener.py` demuestra que el listener de auditoría observa exactamente los eventos producidos por comandos exitosos y nada de los rechazados.
+
+`test_sql_wallet_repository.py` ejercita el `WalletRepository` directamente contra un archivo SQLite temporal, cubriendo la superficie CRUD completa, la consulta derivada `find_by_owner_id` (compilada a partir del nombre del método por `RepositoryBeanPostProcessor`), la API `find_all(pageable)` que devuelve una `Page` con recuento total y metadatos de página, y el camino del predicado de tipo `Specification` vía `find_rich` / `find_all_by_spec`. El patrón de reconexión de dos motores demuestra la durabilidad verdadera.
+
+En la cima, `test_app_context_integration.py` arranca la `LumenApplication` real con la URL de la base de datos sustituida por un archivo SQLite aislado, y luego recorre el ciclo de vida completo de apertura → depósito → retiro → listado → ricos → saldo a través de los buses resueltos por el contexto. Esta única prueba demuestra que el escaneo de inyección de dependencias, la autoconfiguración de CQRS, el `RepositoryBeanPostProcessor` y la frontera `@transactional` se componen todos correctamente.
+
+En concreto, aprendiste:
+
+- **`asyncio_mode = "auto"` + `pythonpath = ["src"]`** en `pyproject.toml`:
+ todas las pruebas asíncronas se ejecutan sin decoradores; la disposición `src/` es importable.
+- **`uv run --extra dev pytest -q`**: el `uv sync` a secas omite el grupo de desarrollo;
+ incluye siempre `--extra dev` para obtener pytest.
+- **`@pytest_asyncio.fixture`**: ciclo de vida del fixture asíncrono gestionado por
+ pytest-asyncio; el `@pytest.fixture` simple no maneja generadores asíncronos.
+- **Instancias de fixture compartidas**: cuando dos fixtures solicitan el mismo nombre de
+ fixture (p. ej., `event_bus`, `session_factory`), pytest lo resuelve una vez por
+ prueba y comparte la instancia.
+- **`RepositoryBeanPostProcessor().after_init(repo, name)`**: debe
+ llamarse en las pruebas que ejercitan consultas derivadas; sin él, los esbozos
+ de método lanzan `NotImplementedError`.
+- **Consultas derivadas** (`find_by_owner_id`): declaradas como esbozos; el
+ post-procesador las compila a `WHERE owner_id = :value` al arrancar.
+- **`Pageable.of(page, size, sort)` + `Page`**: la API `find_all(pageable)`
+ devuelve una `Page` con `total`, `total_pages`, `has_next` e
+ `items`; comprueba cada campo para verificar la corrección de la paginación.
+- **Predicados de tipo `Specification`**: `balance_at_least(n)` se pasa a
+ `find_rich` / `find_all_by_spec` para filtrar por un predicado arbitrario
+ sin añadir un nuevo método de consulta derivada.
+- **`pending_events()` frente a `clear_events()`**: `pending_events()` lee
+ sin vaciar; `clear_events()` vacía. Llama siempre a `clear_events()` en
+ los pasos de organización para que las aserciones solo vean eventos del paso de actuación.
+- **`BusinessRuleViolation.rule`**: comprueba la cadena de regla exacta, no solo
+ la clase de excepción, para demostrar que se disparó el invariante correcto.
+- **`monkeypatch.setenv`**: sustituye la configuración antes de arrancar el
+ contexto en las pruebas de integración; el framework lee variables de entorno
+ durante la autoconfiguración.
+- **Sustituciones de configuración `PYFLY_*`**: cada clave de configuración se mapea a una variable de
+ entorno (`pyfly.data.relational.url` → `PYFLY_DATA_RELATIONAL_URL`); fíjala
+ con `monkeypatch.setenv` antes de arrancar para redirigir toda la aplicación.
+- **Perfil de prueba (v26.6.110)**: para un bloque de ajustes solo de prueba, añade un
+ superpuesto `pyfly-test.yaml` y actívalo con `PYFLY_PROFILES_ACTIVE=test`
+ (equivalencia con el `application-test.yaml` de Spring).
+- **Ayudantes del framework** (`PyFlyTestCase`, `mock_bean`, `create_test_container`,
+ Testcontainers): disponibles en `pyfly.testing` para proyectos que los necesiten;
+ Lumen lo mantiene simple con componentes reales.
+
+---
+
+## Pruébalo tú mismo {.exercises}
+
+1. **Añade una prueba para el retiro de importe cero.** En `test_wallet_aggregate.py`,
+ añade `test_withdraw_zero_is_rejected`. Abre un monedero, deposita 500 EUR y luego
+ intenta `wallet.withdraw(Money(0, Currency.EUR))`. Comprueba que se lanza una
+ `BusinessRuleViolation` y verifica su atributo `.rule`. Compara
+ el nombre de la regla con el equivalente del depósito: ¿son simétricas las reglas?
+
+2. **Prueba un monedero desconocido vía el bus de CQRS.** En `test_cqrs_flow.py`, añade
+ `test_withdraw_from_unknown_wallet_is_rejected`. Envía solo un
+ comando `WithdrawFunds(wallet_id="wlt-ghost", amount=50)` sin abrir un
+ monedero antes. Comprueba que se lanza `CommandProcessingException`. Confirma
+ que el repositorio sigue sin contener monederos consultando
+ `GetWallet(wallet_id="wlt-ghost")` y comprobando `None`.
+
+3. **Amplía la prueba del listener con un segundo monedero.** En
+ `test_event_listener.py`, añade una prueba que abra dos monederos (`u-A` y
+ `u-B`), deposite importes distintos en cada uno y luego llame a
+ `audit_listener.entries_for(wallet_id_A)` y
+ `audit_listener.entries_for(wallet_id_B)` por separado. Comprueba que cada uno
+ devuelve exactamente dos entradas (`WalletOpened` + `FundsDeposited`) y que
+ los valores de `amount` del payload difieren. Esto demuestra que `entries_for` filtra
+ por ID de monedero, no por tipo de evento.
+
+4. **Añade una prueba de paginación multipropietario.** En `test_sql_wallet_repository.py`,
+ añade una prueba que inserte diez monederos con dos propietarios distintos, llame a
+ `find_by_owner_id` para cada propietario y luego llame a `find_all` con
+ `Pageable.of(1, 3, Sort.by("balance_minor").descending())`. Comprueba que
+ `page.total == 10`, `page.total_pages == 4` y que el primer elemento de
+ `page.items` tiene el `balance_minor` más alto. Esto demuestra que la paginación
+ es independiente del filtro de consulta derivada.
diff --git a/book/manuscript-es/17-scheduling-notifications.md b/book/manuscript-es/17-scheduling-notifications.md
new file mode 100644
index 00000000..06549e09
--- /dev/null
+++ b/book/manuscript-es/17-scheduling-notifications.md
@@ -0,0 +1,1184 @@
+Capítulo 17
+
+# Programación, notificaciones, webhooks y callbacks {.chtitle}
+
+::: figure art/openers/ch17.svg |
+
+En el Capítulo 16 dotaste a Lumen de un arnés de pruebas completo: pruebas unitarias para el dominio, pruebas de flujo CQRS a través del bus real y una prueba del adaptador de SQLite que demuestra una persistencia real. Lumen está ahora bien probado y es resiliente. Pero sigue viviendo enteramente dentro de su propio proceso: reacciona a las peticiones, pero nunca toma la iniciativa por sí mismo.
+
+Las plataformas financieras reales son distintas. Envían extractos de cuenta nocturnos, disparan un SMS en el momento en que los fondos llegan, reciben webhooks de estado de pago de un proveedor de pagos a medianoche y llaman de vuelta a sistemas de socios para confirmar que un desembolso quedó registrado. Eso son cuatro patrones de integración distintos —programación, notificaciones, webhooks entrantes y callbacks salientes— y este capítulo los cubre todos.
+
+Al final del capítulo Lumen:
+
+- ejecutará un **trabajo programado nocturno** que totaliza los saldos diarios de los monederos usando `@scheduled` con una expresión cron;
+- enviará un **correo electrónico y una notificación push de "fondos recibidos"** a través de los puertos enchufables `EmailService` y `PushService` de PyFly, disparados por el evento de dominio real `FundsDeposited`;
+- aceptará **webhooks entrantes** de un proveedor de pagos ilustrativo, verificando la firma HMAC-SHA256, deduplicando reintentos y despachando a un listener tipado;
+- despachará **callbacks salientes** a sistemas de socios, firmando cada carga útil, reintentando ante fallos transitorios y registrando cada intento de entrega.
+
+Instala los dos extras opcionales antes de empezar:
+
+```
+uv add "pyfly[scheduling,notifications]"
+```
+
+!!! note "Término nuevo: extras opcionales"
+ Un *extra* es una porción opt-in de las dependencias de un paquete. `pyfly`
+ mantiene su núcleo ligero y entrega capacidades más pesadas —programación,
+ notificaciones y el resto— detrás de extras con nombre, de modo que solo
+ instalas lo que usas. `pyfly[scheduling,notifications]` trae ambos. La sintaxis
+ de corchetes es estándar en el empaquetado de Python; `uv add` lo registra en
+ tu `pyproject.toml` para que el siguiente `uv sync` los reinstale. Si más
+ adelante ves un `ModuleNotFoundError` para `croniter` o para un proveedor de
+ notificaciones, te saltaste esta línea: vuelve a ejecutarla.
+
+Este capítulo está dirigido a PyFly **v26.6.110**. Cada listado de código de abajo
+coincide con el código real de Lumen bajo `samples/lumen/src/lumen`, y cada API
+del framework se comprobó contra el propio `pyfly`, así que lo que construyas aquí
+se ejecuta sin cambios.
+
+---
+
+## Tareas programadas
+
+### ¿Por qué programar en lugar de disparar?
+
+Muchas operaciones de una plataforma financiera no pueden esperar a que llegue una petición HTTP. La conciliación nocturna debe ejecutarse a las 02:00 independientemente de si hay algún usuario activo. Una pasada de calentamiento de caché debería dispararse 30 segundos después del arranque —antes de que llegue el tráfico real— y no cuando la primera petición lenta provoque un fallo de caché. Una métrica de latido debería emitirse cada 10 segundos para que el panel de operaciones muestre una señal en vivo, no una lectura obsoleta.
+
+El módulo de programación de PyFly proporciona una forma declarativa, basada en decoradores, de definir los tres patrones sin gestionar manualmente hilos, bucles de eventos ni ruedas de temporizadores.
+
+::: figure art/figures/17-integrations.svg | Figura 17.1 — Las cuatro\
+capas de integración añadidas en este capítulo. Las tareas programadas se disparan\
+internamente; las notificaciones fluyen hacia afuera, hacia los usuarios; los webhooks entrantes\
+llegan desde los socios; los callbacks salientes cierran el bucle de realimentación.
+
+### El decorador @scheduled
+
+**`@scheduled`** marca cualquier método `async` de un bean `@service` para su ejecución periódica. Acepta exactamente un *disparador* (trigger): `fixed_rate`, `fixed_delay` o `cron`. Proporcionar cero o más de un disparador lanza un `ValueError` en el momento de la decoración, de modo que los errores afloran al arrancar y no silenciosamente a las tres de la madrugada.
+
+!!! note "Término nuevo: disparador"
+ Un *disparador* (trigger) es la regla que decide *cuándo* se ejecuta un método
+ programado. Eliges exactamente uno: `cron` (una expresión de calendario como
+ "todos los días a las 02:00"), `fixed_rate` (un intervalo constante como "cada
+ 10 segundos") o `fixed_delay` (un hueco medido después de que cada ejecución
+ termina). Un método, un disparador.
+
+Construyamos el resumen nocturno una decisión a la vez.
+
+**Paso 1 — Crea el archivo de servicio.** En el árbol de Lumen, añade `daily_rollup.py`
+bajo un paquete `ledger`. La clase es un `@service` corriente: una clase Python
+sencilla que PyFly registra en su contenedor de inyección de dependencias y
+construye por ti. Como es un bean gestionado, puedes pedir el `WalletRepository` en
+el constructor y el framework te lo entrega; nunca llamas a `new` tú mismo.
+
+**Paso 2 — Elige el disparador.** Este trabajo debe ejecutarse una vez por noche, a hora fija, así que
+el disparador es `cron`. La expresión `"0 2 * * *"` se lee campo a campo como
+*minuto 0, hora 2, cada día del mes, cada mes, cada día de la semana* —es decir,
+las 02:00 cada día.
+
+**Paso 3 — Escribe el trabajo.** Dentro del método, carga cada monedero, suma los
+enteros `balance_minor` persistidos y (por ahora) registra el total. En producción
+escribirías la instantánea en una tabla de informes o la enviarías aguas abajo; el
+registro mantiene el ejemplo centrado en la *programación*, no en la contabilidad.
+
+::: listing lumen/ledger/daily_rollup.py | Listado 17.1 — Resumen nocturno de saldos de monederos con @scheduled
+from datetime import timedelta
+
+from lumen.models.repositories.wallet_repository import WalletRepository
+from pyfly.container import service
+from pyfly.scheduling import scheduled
+
+
+@service
+class DailyRollupService:
+ """Tallies all wallet balances once per night at 02:00 UTC."""
+
+ def __init__(self, wallet_repo: WalletRepository) -> None:
+ self._wallets = wallet_repo
+
+ @scheduled(cron="0 2 * * *")
+ async def run(self) -> None:
+ wallets = await self._wallets.find_all()
+ # find_all() returns WalletEntity rows; balance_minor is the
+ # persisted integer (cents).
+ total_minor_units = sum(w.balance_minor for w in wallets)
+ # Persist or ship the nightly snapshot; here we log it.
+ print(
+ f"[rollup] {len(wallets)} wallets, "
+ f"total {total_minor_units / 100:.2f} "
+ f"(minor units: {total_minor_units})"
+ )
+:::
+
+**Cómo funciona.** `@scheduled(cron="0 2 * * *")` se dispara todos los días a las 02:00 UTC. El planificador calcula `seconds_until_next()` mediante `CronExpression`, duerme exactamente ese tiempo y luego envía el método al ejecutor.
+
+Eso es todo el cableado que Lumen necesita. Con `pyfly[scheduling]` instalado, `SchedulingAutoConfiguration` automáticamente:
+
+1. registra un bean `TaskScheduler`;
+2. escanea cada bean `@service` en busca de métodos `@scheduled`;
+3. arranca el planificador durante el arranque del `ApplicationContext`;
+4. lo detiene con elegancia al apagarse.
+
+No se requiere ningún `SchedulerManager`.
+
+!!! note "Término nuevo: autoconfiguración"
+ La *autoconfiguración* es PyFly fijándose en lo que hay en tu classpath y
+ cableando por ti la maquinaria correspondiente. `SchedulingAutoConfiguration`
+ solo se activa cuando `croniter` (incluido por el extra `scheduling`) es
+ importable, así que el planificador aparece en el momento en que instalas el
+ extra y permanece ausente en caso contrario. Es la misma idea de "convención
+ sobre configuración" que hizo famosa Spring Boot; siempre puedes reemplazar un
+ bean declarando el tuyo propio.
+
+**Ejecútalo.** Esperar hasta las 02:00 para ver tu primer tic no tiene gracia, así que
+cambia temporalmente el disparador para que se ejecute cada minuto —`@scheduled(cron="* * * * *")`— e
+inicia la aplicación desde el directorio `samples/lumen`:
+
+```bash
+uv run pyfly run --server uvicorn
+```
+
+Al comienzo del siguiente minuto deberías ver tu línea de resumen en los logs (una
+base de datos vacía simplemente informa de cero monederos):
+
+```text
+[rollup] 0 wallets, total 0.00 (minor units: 0)
+```
+
+Abre un monedero y deposita en él (consulta las recetas de curl en el Capítulo 7), espera al
+siguiente minuto y los totales se mueven:
+
+```text
+[rollup] 1 wallets, total 15.00 (minor units: 1500)
+```
+
+Detén la aplicación con Ctrl-C y **vuelve a poner el disparador en `"0 2 * * *"`** antes de
+confirmar el cambio: el cron de cada minuto era solo una sonda.
+
+!!! note "Qué acaba de pasar"
+ No arrancaste un hilo, ni abriste un bucle de eventos, ni registraste un
+ temporizador. Escribiste un `@service` con un método `@scheduled`, y el
+ framework lo descubrió al arrancar, calculó el siguiente momento de disparo a
+ partir de la expresión cron, durmió hasta entonces y ejecutó tu corrutina,
+ repitiendo para siempre. El planificador es *declarativo*: tú indicas *cuándo*,
+ PyFly se encarga del *cómo*.
+
+### fixed_rate frente a fixed_delay
+
+**`fixed_rate`** mide desde el **inicio** de una ejecución hasta el inicio de la siguiente. **`fixed_delay`** mide desde el **final** de una ejecución hasta el inicio de la siguiente. Usa `fixed_rate` para latidos y métricas donde necesitas una cadencia constante con independencia del tiempo de ejecución. Usa `fixed_delay` cuando necesitas un hueco de respiro garantizado; por ejemplo, al sondear una API aguas arriba que limita la tasa por frecuencia de peticiones.
+
+::: listing lumen/health/monitor.py | Listado 17.2 — Latido fixed_rate y sondeo fixed_delay
+from datetime import timedelta
+
+from pyfly.container import service
+from pyfly.scheduling import scheduled
+
+
+@service
+class HealthMonitor:
+
+ @scheduled(
+ fixed_rate=timedelta(seconds=10),
+ initial_delay=timedelta(seconds=5),
+ )
+ async def heartbeat(self) -> None:
+ """Emit a liveness metric every 10 s, starting 5 s after startup."""
+ # metrics.gauge("lumen.up", 1)
+ pass
+
+
+@service
+class ExchangeRatePoller:
+
+ def __init__(self, fx_repo) -> None:
+ self._repo = fx_repo
+
+ @scheduled(fixed_delay=timedelta(minutes=5))
+ async def poll(self) -> None:
+ """Fetch the latest exchange rates, then wait 5 min before repeating."""
+ rates = await self._repo.fetch_latest()
+ await self._repo.store(rates)
+:::
+
+`initial_delay` pospone la primera ejecución; está disponible tanto para `fixed_rate` como para `fixed_delay` (se ignora en los disparadores `cron`, que siempre esperan al siguiente instante de calendario coincidente).
+
+### CronExpression
+
+**`CronExpression`** también es utilizable directamente: resulta conveniente cuando necesitas mostrar próximos horarios de programación en una interfaz o validar una expresión proporcionada por el usuario antes de almacenarla.
+
+::: listing lumen/ledger/schedule_preview.py | Listado 17.3 — Uso de CronExpression de forma independiente
+from pyfly.scheduling import CronExpression
+
+
+def preview_rollup_schedule(expression: str, n: int = 5) -> list[str]:
+ """Return the next N fire times for a given cron expression."""
+ cron = CronExpression(expression)
+ return [str(t) for t in cron.next_n_fire_times(n)]
+:::
+
+**Ejecútalo.** `CronExpression` no necesita una aplicación en marcha, así que la forma más rápida de construir
+intuición es el REPL. Desde `samples/lumen`:
+
+```bash
+uv run python -c "from pyfly.scheduling import CronExpression; \
+print(*CronExpression('0 2 * * *').next_n_fire_times(3), sep='\n')"
+```
+
+Deberías ver los tres próximos instantes de las 02:00, uno por línea (tus fechas
+serán distintas):
+
+```text
+2026-06-16 02:00:00+00:00
+2026-06-17 02:00:00+00:00
+2026-06-18 02:00:00+00:00
+```
+
+Fíjate en el `+00:00`: los momentos de disparo son UTC salvo que pases una `zone` (que se cubre
+a continuación). Esta es también la forma más limpia de comprobar la cordura de una expresión proporcionada
+por el usuario antes de almacenarla: una cadena no válida lanza `ValueError` de inmediato.
+
+`CronExpression` acepta tanto el formato estándar de 5 campos (`min hour dom month dow`) como el formato de 6 campos al estilo Spring con los segundos primero (`sec min hour dom month dow`). El comodín `?` de Spring se normaliza a `*` de forma transparente.
+
+| Expresión | Se dispara |
+|---|---|
+| `* * * * *` | Cada minuto |
+| `0 * * * *` | Cada hora, en punto |
+| `0 2 * * *` | Cada día a las 02:00 |
+| `0 9 * * 1-5` | Días laborables a las 09:00 |
+| `30 2 1 * *` | El día 1 de cada mes a las 02:30 |
+| `*/15 * * * *` | Cada 15 minutos |
+| `0 0 12 * * *` | Mediodía cada día (6 campos, segundos primero) |
+
+### Cron consciente de la zona horaria
+
+Las expresiones cron se evalúan en **UTC** por defecto. Pasa `zone` con un nombre de zona horaria IANA para evaluar los momentos de disparo en una zona específica en su lugar:
+
+```python
+@scheduled(cron="0 2 * * *", zone="America/New_York")
+async def close_books(self) -> None:
+ """02:00 New York time — follows DST automatically."""
+ ...
+```
+
+El mismo parámetro `zone` está disponible en `CronExpression`:
+
+```python
+cron = CronExpression("0 9 * * *", zone="Europe/Madrid")
+next_run = cron.next_fire_time() # zone-aware datetime
+```
+
+Las transiciones de horario de verano (DST) las gestiona la base de datos `zoneinfo`; no se requiere ningún ajuste manual de desfase.
+
+### Bloqueo distribuido
+
+Cuando varias instancias de Lumen se ejecutan detrás de un balanceador de carga, cada instancia programa los mismos métodos `@scheduled`. Sin coordinación, el resumen nocturno se dispara una vez por instancia y escribe registros duplicados. El parámetro `lock` resuelve esto de la misma manera que `@SchedulerLock` (ShedLock) de Spring: antes de cada tic el planificador intenta adquirir un bloqueo con nombre y **omite la ejecución** si el bloqueo ya está retenido en otro lugar.
+
+```python
+@scheduled(cron="0 2 * * *", lock=True, lock_ttl=timedelta(minutes=5))
+async def run(self) -> None:
+ """lock=True auto-names the lock 'DailyRollupService.run'."""
+ ...
+```
+
+- `lock=True` — deriva el nombre del bloqueo de `"ClassName.method_name"`.
+- `lock="shared-name"` — nombre explícito; útil cuando dos métodos deben ser mutuamente excluyentes.
+- `lock_ttl` — TTL de válvula de seguridad; ponlo cómodamente más largo que el peor tiempo de ejecución del trabajo.
+
+Por defecto `TaskScheduler` usa `LocalLock`, que siempre adquiere: el comportamiento de instancia única no cambia. Para la coordinación entre procesos, implementa `DistributedLock` y regístralo como un bean:
+
+::: listing lumen/infra/redis_lock.py | Listado 17.4 — DistributedLock respaldado por Redis
+from pyfly.container import bean, configuration
+from pyfly.scheduling import DistributedLock
+
+
+class RedisLock:
+ """Best-effort named lock backed by Redis SET NX PX."""
+
+ def __init__(self, redis) -> None:
+ self._redis = redis
+
+ async def try_acquire(self, name: str, ttl: float) -> bool:
+ ok = await self._redis.set(
+ f"pyfly:lock:{name}", "1",
+ nx=True, px=int(ttl * 1000),
+ )
+ return ok is True
+
+ async def release(self, name: str) -> None:
+ await self._redis.delete(f"pyfly:lock:{name}")
+
+
+@configuration
+class LockConfig:
+
+ @bean
+ def distributed_lock(self) -> DistributedLock:
+ import redis.asyncio as aioredis
+ client = aioredis.from_url("redis://localhost:6379/1")
+ return RedisLock(client)
+:::
+
+`SchedulingAutoConfiguration` detecta el bean `DistributedLock` en el contenedor automáticamente y se lo pasa al `TaskScheduler`. Cualquier objeto con corrutinas `try_acquire` y `release` conformes satisface el protocolo.
+
+### @async_method
+
+**`@async_method`** marca un método para ejecución fire-and-forget (dispara y olvida) a través del `TaskExecutorPort`. La persona que llama retorna de inmediato; el framework encamina la corrutina a través del ejecutor configurado en segundo plano:
+
+```python
+from pyfly.scheduling import async_method
+
+
+@service
+class AlertService:
+
+ @async_method
+ async def send_alert(self, msg: str) -> None:
+ """Caller does not await — AlertService dispatches asynchronously."""
+ ...
+```
+
+Bajo el capó `@async_method` establece `__pyfly_async__ = True` en la función; el framework detecta esta bandera y envía la corrutina al `TaskExecutorPort`.
+
+!!! spring "Equivalencia con Spring"
+ `@scheduled(fixed_rate=...)` refleja el
+ `@Scheduled(fixedRate=...)` de Spring. `@scheduled(fixed_delay=...)` refleja
+ `@Scheduled(fixedDelay=...)`. `@scheduled(cron=...)` refleja
+ `@Scheduled(cron=...)`. `zone=` refleja el atributo `zone` de Spring.
+ `lock=True` refleja el `@SchedulerLock` de ShedLock. `@async_method`
+ refleja el `@Async` de Spring.
+
+### Referencia de configuración
+
+```yaml
+pyfly:
+ scheduling:
+ enabled: true # set false to disable all loops
+ executor:
+ type: asyncio # 'asyncio' (default, in-loop) or 'thread'
+ max-workers: 4 # worker threads when type is 'thread'
+ lock:
+ provider: none # none | memory | redis | postgres
+```
+
+Cuando `enabled` es `false`, `TaskScheduler` no arranca ningún bucle y todos los métodos `@scheduled` se omiten en silencio.
+
+El `executor.type` elige cómo se ejecuta cada tic. El valor por defecto `asyncio` ejecuta la
+corrutina en el bucle de eventos de la aplicación —ideal para trabajos cortos, ligados a E/S, como
+el resumen—. Cambia a `thread` (un grupo de `executor.max-workers` hilos) cuando un
+trabajo realice trabajo intensivo de CPU o llame a una biblioteca bloqueante, de modo que no pueda atascar el bucle.
+
+!!! tip "Cómo elegir un proveedor de bloqueo"
+ `lock.provider` selecciona el backend detrás de `@scheduled(lock=...)`, descrito
+ a continuación: `none` (el valor por defecto: sin coordinación), `memory` (exclusión mutua
+ dentro de un proceso), `redis` o `postgres` (verdadera coordinación entre instancias
+ sin cambios en el código). En `redis`/`postgres` PyFly construye el
+ bean `DistributedLock` por ti a partir de `pyfly.scheduling.lock.redis.url` o el
+ `AsyncEngine` ya existente de la aplicación; el `@bean` artesanal del Listado 17.4 es la
+ alternativa de hazlo-tú-mismo cuando necesitas semánticas personalizadas.
+
+---
+
+## Notificaciones
+
+Lumen necesita decirles a los clientes que su dinero ha llegado: un correo electrónico para la confirmación del saldo y, opcionalmente, un SMS o un push móvil para la alerta en tiempo real.
+
+El módulo de notificaciones de PyFly define tres **protocolos de puerto** y tres **servicios por defecto**. Tu lógica de negocio depende de los protocolos; los adaptadores concretos de proveedor —SMTP, SendGrid, Twilio, Firebase— viven detrás de la frontera del puerto y pueden intercambiarse sin tocar una sola línea de código de dominio.
+
+!!! note "Término nuevo: puerto y adaptador"
+ Un *puerto* es una interfaz con la que tu código conversa —aquí, "algo capaz de
+ enviar un correo electrónico"—. Un *adaptador* es una implementación concreta de ese puerto:
+ `SmtpEmailProvider`, `SendGridEmailProvider`, etcétera. El patrón (también
+ llamado *arquitectura hexagonal*) significa que tu lógica de depósito depende solo del
+ puerto `EmailService`, nunca de un proveedor específico. Cambiar SMTP por SendGrid
+ es un cambio de una línea en una clase de configuración; el código de dominio nunca se entera.
+
+### La jerarquía de puertos
+
+| Protocolo | Clase de servicio | Método |
+|---|---|---|
+| `EmailProvider` | `DefaultEmailService` | `send(EmailMessage) -> NotificationResult` |
+| `SmsProvider` | `DefaultSmsService` | `send(SmsMessage) -> NotificationResult` |
+| `PushProvider` | `DefaultPushService` | `send(PushMessage) -> NotificationResult` |
+
+`DefaultEmailService`, `DefaultSmsService` y `DefaultPushService` son envoltorios finos: cada uno delega en un proveedor, captura cualquier excepción del proveedor y devuelve un `NotificationResult` estructurado con `status=FAILED` y la cadena del error en lugar de propagar la excepción. Una caída transitoria de SendGrid no tumba el manejador (handler) de depósitos.
+
+### Mensajes y resultados
+
+`FundsDeposited` lleva `amount` y `balance` como **unidades menores enteras** (céntimos). La propiedad `Money.major_units` las convierte para su visualización —`Money(25000, Currency.EUR).major_units` es `250.0`—. Tenlo en cuenta al formatear los cuerpos de las notificaciones.
+
+::: listing lumen/notifications/models_overview.py | Listado 17.5 — Los DTO principales
+from pyfly.notifications import (
+ EmailMessage,
+ NotificationResult,
+ PushMessage,
+ SmsMessage,
+)
+
+# Email — full field set
+email = EmailMessage(
+ to=["alice@example.com"],
+ sender="no-reply@lumenbank.com",
+ subject="Funds received",
+ body_text="EUR 250.00 has been credited to your wallet.",
+ body_html=(
+ "EUR 250.00 has been credited "
+ "to your wallet.
"
+ ),
+)
+
+# SMS — compact
+sms = SmsMessage(
+ to="+34600000001",
+ body="Lumen: EUR 250.00 received. New balance: EUR 750.00.",
+ sender="LUMEN",
+)
+
+# Push — structured payload
+push = PushMessage(
+ device_tokens=["FCM_TOKEN_GOES_HERE"],
+ title="Funds received",
+ body="EUR 250.00 credited",
+ data={"wallet_id": "w-001", "amount_minor": 25000},
+)
+:::
+
+`NotificationResult` lleva `id`, `provider`, `status` (`EmailStatus.SENT | DELIVERED | FAILED | ...`), un `provider_id` opcional (p. ej. el ID de mensaje de SendGrid) y un `error` opcional.
+
+### Cableando el proveedor SMTP
+
+Para desarrollo y despliegues autoalojados, `SmtpEmailProvider` ejecuta `smtplib` desde un grupo de hilos para que el bucle de eventos asíncrono nunca se bloquee.
+
+**Paso 1 — Construye el proveedor como un `@bean`.** Una clase `@configuration` es el lugar
+de PyFly para ensamblar objetos que el contenedor no puede construir por sí solo —aquí, un
+cliente SMTP que necesita un host, credenciales y ajustes de TLS—. Cada método `@bean`
+devuelve un objeto listo para usar; el framework lo cachea y lo inyecta
+allá donde se solicite el tipo de retorno.
+
+**Paso 2 — Envuélvelo en un `DefaultEmailService`.** El segundo `@bean` toma el
+proveedor y lo devuelve como un `EmailService` —el *puerto* del que depende tu código
+de dominio—. El tipo de retorno declarado importa: al devolver `EmailService`, cada
+clase que pide un `EmailService` recibe este envoltorio, y ninguna de ellas
+se entera de que SMTP está detrás.
+
+::: listing lumen/notifications/config.py | Listado 17.6 — Proveedor SMTP cableado como un @bean
+from pyfly.container import bean, configuration
+from pyfly.notifications import DefaultEmailService, EmailService
+from pyfly.notifications.providers.smtp import SmtpEmailProvider
+
+
+@configuration
+class NotificationConfig:
+
+ @bean
+ def email_provider(self) -> SmtpEmailProvider:
+ return SmtpEmailProvider(
+ "smtp.lumenbank.internal",
+ port=587,
+ username="notifications",
+ password="s3cr3t",
+ use_tls=True,
+ )
+
+ @bean
+ def email_service(
+ self, provider: SmtpEmailProvider,
+ ) -> EmailService:
+ return DefaultEmailService(provider=provider)
+:::
+
+`SmtpEmailProvider` acepta `host`, `port` (por defecto `587`), `username`, `password` y `use_tls` (por defecto `True`). Cámbialo por `SendGridEmailProvider` o `ResendEmailProvider` modificando un único método `@bean`: `DefaultEmailService` es indiferente al proveedor que tenga detrás.
+
+!!! tip "Proveedores disponibles"
+ `pyfly.notifications` incluye ocho adaptadores integrados:
+ `DummyEmailProvider` / `DummySmsProvider` / `DummyPushProvider`
+ (solo registran, para desarrollo/pruebas), `SmtpEmailProvider`,
+ `SendGridEmailProvider`, `ResendEmailProvider` (correo electrónico),
+ `TwilioSmsProvider` (SMS) y `FirebasePushProvider` (push). Todos
+ satisfacen su respectivo protocolo `*Provider`.
+
+### Enviando una notificación de "fondos recibidos"
+
+Lumen publica un evento de dominio `FundsDeposited` cada vez que el comando `deposit()` tiene éxito (consulta el Capítulo 8). El lugar adecuado para disparar la notificación es un listener de EDA suscrito a ese evento, no el propio manejador del comando, lo que mantiene la ruta de depósito libre de preocupaciones de notificación.
+
+`FundsDeposited` lleva `wallet_id: str`, `amount: int` (unidades menores), `currency: str` y `balance: int` (nuevo saldo, unidades menores). El listener convierte `amount` en una cadena de visualización mediante `amount / 100`.
+
+**Paso 1 — Suscríbete al evento.** Apila `@event_listener(event_types=["FundsDeposited"])`
+sobre un método `async` de un `@service`. Al arrancar, PyFly descubre el método
+marcado y lo autosuscribe al bus `EventPublisher` —exactamente el mismo
+mecanismo que `WalletAuditListener` usó allá en el Capítulo 8—. Nunca cableas un bus a
+mano.
+
+**Paso 2 — Lee la carga útil.** El manejador recibe un `EventEnvelope`. Su
+`payload` es un dict sencillo de los campos del evento, así que extraes `wallet_id`,
+`amount`, `currency` y `balance` con `.get(...)` y coaccionas los importes
+a enteros. Como los importes están en unidades menores, dividir por 100 da el valor
+de visualización: `25000` se convierte en `250.00`.
+
+**Paso 3 — Envía a través de los puertos.** Inyecta `EmailService` y `PushService` en
+el constructor y llama a `.send(...)` en cada uno. Ambos devuelven un `NotificationResult`
+en lugar de lanzar una excepción: un proveedor inestable se degrada con elegancia en lugar de hacer caer
+el listener.
+
+::: listing lumen/wallet/deposit_notification_listener.py | Listado 17.7 — Notificando ante FundsDeposited
+from pyfly.container import service
+from pyfly.eda import EventEnvelope, event_listener
+from pyfly.notifications import (
+ EmailMessage,
+ EmailService,
+ PushMessage,
+ PushService,
+)
+
+
+@service
+class DepositNotificationListener:
+ """Sends email + push when a FundsDeposited event is observed."""
+
+ def __init__(
+ self,
+ email_service: EmailService,
+ push_service: PushService,
+ ) -> None:
+ self._email = email_service
+ self._push = push_service
+
+ @event_listener(event_types=["FundsDeposited"])
+ async def on_funds_deposited(
+ self, envelope: EventEnvelope,
+ ) -> None:
+ payload = envelope.payload
+ wallet_id = str(payload.get("wallet_id", ""))
+ amount_minor = int(payload.get("amount", 0))
+ currency = str(payload.get("currency", "EUR"))
+ balance_minor = int(payload.get("balance", 0))
+ amount_str = f"{amount_minor / 100:.2f} {currency}"
+ balance_str = f"{balance_minor / 100:.2f} {currency}"
+
+ # Fetch contact details from a wallet profile service in prod;
+ # hardcoded here for illustration.
+ email = "customer@example.com"
+ device_token = "FCM_TOKEN_GOES_HERE"
+
+ await self._email.send(EmailMessage(
+ to=[email],
+ sender="no-reply@lumenbank.com",
+ subject=f"Funds received: {amount_str}",
+ body_text=(
+ f"{amount_str} has been credited to wallet "
+ f"{wallet_id}. New balance: {balance_str}."
+ ),
+ ))
+ await self._push.send(PushMessage(
+ device_tokens=[device_token],
+ title="Funds received",
+ body=f"{amount_str} credited",
+ data={
+ "wallet_id": wallet_id,
+ "amount_minor": amount_minor,
+ "currency": currency,
+ },
+ ))
+:::
+
+Ambas llamadas devuelven un `NotificationResult`; inspecciona el campo `status` para registrar fallos o programar reintentos.
+
+**Ejecútalo.** No quieres un servidor SMTP real mientras desarrollas, así que cambia el
+proveedor por el `DummyEmailProvider`, que solo registra. En tu clase `@configuration`,
+devuelve un `DummyEmailProvider` (y un `DummyPushProvider`) en lugar del de SMTP,
+luego inicia la aplicación y dispara un depósito:
+
+```bash
+uv run pyfly run --server uvicorn
+# in a second terminal, open a wallet and deposit (see Chapter 7), e.g.:
+curl -s -X POST localhost:8080/api/v1/wallets//deposit \
+ -H 'content-type: application/json' -d '{"amount":25000}'
+```
+
+El depósito publica `FundsDeposited`, el listener se dispara y los proveedores
+de prueba registran los mensajes que "enviaron":
+
+```text
+[dummy email] to=['customer@example.com'] subject=Funds received: 250.00 EUR
+[dummy push] tokens=1 title=Funds received
+```
+
+El `DummyEmailProvider` también conserva cada mensaje que recibió en una lista `.sent`,
+que es exactamente contra lo que se afirma la prueba del Ejercicio 2, sin necesidad de servidor SMTP.
+
+!!! note "Qué acaba de pasar"
+ El comando de depósito no sabía nada del correo electrónico. Simplemente hizo su trabajo y
+ lanzó un evento de dominio `FundsDeposited`. La lógica de notificación vive en un
+ listener aparte que *reacciona* a ese evento, así que la ruta de depósito se mantiene
+ limpia y puedes añadir, eliminar o cambiar notificaciones sin tocar el
+ manejador del comando. Esa separación —publicar un hecho, dejar que las partes interesadas
+ reaccionen— es la razón de ser de la arquitectura orientada a eventos.
+
+!!! spring "Equivalencia con Spring"
+ `EmailService` / `SmsService` / `PushService` son los equivalentes en Python
+ del `JavaMailSender` (correo electrónico) de Spring y de las integraciones
+ de terceros de Spring para SMS y push. La división hexagonal puerto/adaptador
+ es idéntica: tu código de dominio depende del protocolo;
+ los adaptadores concretos de proveedor viven en la capa de infraestructura.
+
+---
+
+## Webhooks entrantes
+
+Un proveedor de pagos ilustrativo envía por POST un evento `payment_intent.succeeded` a Lumen cada vez que un cliente recarga su monedero con tarjeta. Lumen debe:
+
+1. **verificar la firma HMAC-SHA256** para rechazar cargas útiles falsificadas;
+2. **deduplicar** los reintentos usando la clave de idempotencia para que un reintento no acredite un monedero dos veces;
+3. **despachar** el evento verificado a un listener tipado.
+
+El módulo `pyfly.webhooks` de PyFly se encarga de los tres pasos.
+
+!!! note "Términos nuevos: webhook, HMAC, idempotencia"
+ Un *webhook* es un POST HTTP que un sistema externo te envía *a ti* cuando
+ ocurre algo: el espejo entrante de los callbacks salientes que veremos más adelante en
+ este capítulo. Como cualquiera puede hacer POST a una URL pública, el proveedor firma
+ cada petición con un secreto compartido usando *HMAC* (un hash con clave); recalcular
+ el hash sobre los bytes exactos recibidos y compararlo demuestra que la carga útil es
+ genuina y no fue manipulada. *Idempotencia* significa "seguro de recibir más de
+ una vez": los proveedores reintentan ante fallos de red, así que almacenas una clave de idempotencia e
+ ignoras una repetición —de lo contrario una sola recarga con tarjeta podría acreditar un monedero dos veces—.
+
+### WebhookEvent y AbstractWebhookEventListener
+
+Cada evento entrante se modela como una dataclass `WebhookEvent`:
+
+```python
+@dataclass
+class WebhookEvent:
+ id: str # auto-generated UUID
+ source: str # e.g. "payment-provider"
+ event_type: str # from body["type"]
+ headers: dict[str, str]
+ body: dict[str, Any]
+ raw_body: bytes
+ received_at: datetime
+ idempotency_key: str | None
+```
+
+Subclasifica `AbstractWebhookEventListener` y establece `source` con el nombre
+que pasarás a `WebhookProcessor.process()`:
+
+::: listing lumen/webhooks/payment_listener.py | Listado 17.8 — Listener de webhook del proveedor de pagos
+from pyfly.container import service
+from pyfly.webhooks import AbstractWebhookEventListener, WebhookEvent
+
+
+@service
+class PaymentWebhookListener(AbstractWebhookEventListener):
+ source = "payment-provider"
+
+ def __init__(self, deposit_handler) -> None:
+ self._handler = deposit_handler
+
+ async def handle(self, event: WebhookEvent) -> None:
+ if event.event_type == "payment_intent.succeeded":
+ pi = event.body.get("data", {}).get("object", {})
+ wallet_id = pi.get("metadata", {}).get("wallet_id")
+ amount_minor = int(pi.get("amount_received", 0))
+ currency_code = pi.get("currency", "EUR").upper()
+ if wallet_id and amount_minor > 0:
+ # Delegate to the CQRS command handler so the aggregate
+ # enforces the balance invariant and raises FundsDeposited.
+ from lumen.core.services.wallets.deposit_funds_command import (
+ DepositFunds,
+ )
+ await self._handler.handle(
+ DepositFunds(
+ wallet_id=wallet_id,
+ amount=amount_minor,
+ )
+ )
+
+ async def on_error(
+ self, event: WebhookEvent, error: BaseException,
+ ) -> None:
+ # Override to DLQ or page on-call.
+ pass
+:::
+
+`on_error` se invoca cuando `handle` lanza una excepción; por defecto es un no-op. Reescríbelo para publicar en una cola de mensajes muertos o emitir una métrica.
+
+### WebhookProcessor: verificar, deduplicar, despachar
+
+**`WebhookProcessor`** ensambla un validador de firmas, un almacén de idempotencia y una lista de listeners. Móntalo en una clase `@configuration` para que sea un
+único bean compartido:
+
+- `listeners` es la lista de subclases de `AbstractWebhookEventListener` a las que abrir en
+ abanico los eventos (de momento solo `PaymentWebhookListener`);
+- `signature_validators` asocia cada nombre de `source` con el validador que demuestra que sus
+ peticiones son genuinas —aquí un `HmacSignatureValidator` con clave del secreto del webhook
+ que te dio tu proveedor—;
+- un `event_store` (omitido aquí, así que se usa el por defecto en memoria) recuerda
+ las claves de idempotencia.
+
+::: listing lumen/webhooks/processor_config.py | Listado 17.9 — Ensamblando WebhookProcessor
+from pyfly.container import bean, configuration
+from pyfly.webhooks import (
+ HmacSignatureValidator,
+ WebhookProcessor,
+)
+from lumen.webhooks.payment_listener import PaymentWebhookListener
+
+
+@configuration
+class WebhookConfig:
+
+ @bean
+ def webhook_processor(
+ self, payment_listener: PaymentWebhookListener,
+ ) -> WebhookProcessor:
+ return WebhookProcessor(
+ listeners=[payment_listener],
+ signature_validators={
+ "payment-provider": HmacSignatureValidator(
+ secret="whsec_REPLACE_ME",
+ ),
+ },
+ )
+:::
+
+`HmacSignatureValidator` espera el formato de cabecera `sha256=` y usa `hmac.compare_digest` para una comparación en tiempo constante. Cambia el parámetro `header_prefix` si tu proveedor usa un esquema diferente.
+
+### Manejando un webhook en un manejador HTTP
+
+Llama a `processor.process()` desde tu manejador HTTP entrante. Pasa el cuerpo de la petición sin procesar (bytes sin modificar): el validador calcula el HMAC sobre los bytes exactos recibidos.
+
+!!! warning "Lee el cuerpo como bytes en crudo, no como JSON parseado"
+ La firma se calcula sobre los *bytes exactos* que envió el proveedor. Si
+ parseas el JSON y lo vuelves a serializar, el orden de las claves o los espacios en blanco pueden cambiar y el
+ HMAC ya no coincidirá —toda petición legítima sería rechazada—.
+ Pasa siempre `await request.body()` (los bytes intactos) a `process()`, como
+ hace el manejador de abajo.
+
+::: listing lumen/webhooks/payment_handler.py | Listado 17.10 — Endpoint de webhook entrante del proveedor de pagos
+from pyfly.container import rest_controller
+from pyfly.web import post_mapping, request_mapping
+from pyfly.webhooks import WebhookProcessor
+from starlette.requests import Request
+from starlette.responses import Response
+
+
+@rest_controller
+@request_mapping("/webhooks")
+class PaymentWebhookHandler:
+
+ def __init__(self, processor: WebhookProcessor) -> None:
+ self._processor = processor
+
+ @post_mapping("/payment")
+ async def receive(self, request: Request) -> Response:
+ # Read the untouched bytes — the HMAC is computed over exactly
+ # what the provider sent (see the warning above).
+ raw_body = await request.body()
+ headers = {
+ "X-Signature": request.headers.get(
+ "X-Webhook-Signature", ""
+ ),
+ "X-Idempotency-Key": request.headers.get(
+ "X-Idempotency-Key", ""
+ ),
+ }
+ try:
+ await self._processor.process(
+ source="payment-provider",
+ raw_body=raw_body,
+ headers=headers,
+ )
+ except ValueError:
+ return Response(content=b"invalid signature", status_code=400)
+ return Response(content=b"ok", status_code=200)
+:::
+
+La firma de `process()` acepta los argumentos por palabra clave `signature_header` e `idempotency_header` para reemplazar los nombres de cabecera por defecto (`X-Signature` y `X-Idempotency-Key`).
+
+**Qué ocurre dentro de `process()`:**
+
+1. El validador se busca por `source`; si no hay ninguno registrado, se usa un `NoOpSignatureValidator` —que siempre pasa, seguro para desarrollo pero no para producción—.
+2. Si la validación de la firma falla, se lanza `ValueError` de inmediato y no se invoca a ningún listener.
+3. El cuerpo en crudo se decodifica como JSON; si falla, los bytes en crudo se almacenan bajo `body["_raw"]`.
+4. Si `idempotency_key` está presente y ya se ha visto, el evento se devuelve pero **no** se invoca a los listeners.
+5. Cada listener para el source se invoca en el orden de registro; si uno lanza una excepción, el error se registra y se invoca `on_error` antes de continuar con el siguiente listener.
+
+**Ejecútalo.** Prueba el endpoint como lo haría un proveedor real: firmando el cuerpo
+exacto. Elige el mismo secreto que pusiste en `HmacSignatureValidator` (`whsec_REPLACE_ME`
+en el Listado 17.9), calcula el HMAC con `openssl` y haz POST. Inicia la aplicación
+(`uv run pyfly run --server uvicorn`), luego en un segundo terminal:
+
+::: listing terminal | Listado 17.10a — Firma y POST de un webhook
+BODY='{"type":"payment_intent.succeeded","data":{"object":{"amount_received":25000,"currency":"eur","metadata":{"wallet_id":""}}}}'
+SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "whsec_REPLACE_ME" | sed 's/^.* //')
+
+curl -s -X POST localhost:8080/webhooks/payment \
+ -H "X-Webhook-Signature: sha256=$SIG" \
+ -H "X-Idempotency-Key: evt-001" \
+ -H 'content-type: application/json' \
+ -d "$BODY"
+:::
+
+Una petición correctamente firmada devuelve `ok` y acredita el monedero (verás también
+dispararse los logs de notificación de `FundsDeposited` de antes):
+
+```text
+ok
+```
+
+Ahora demuestra las dos garantías. Haz POST del **mismo** comando otra vez con la misma
+`X-Idempotency-Key`: sigue devolviendo `ok`, pero el monedero *no* se acredita una
+segunda vez (el duplicado se descarta antes de que se ejecute ningún listener). Luego altera
+un byte de `$BODY` *sin* recalcular `$SIG` y vuelve a hacer POST: la firma
+ya no coincide, así que el manejador devuelve:
+
+```text
+invalid signature
+```
+
+Esa es la tubería verificar-deduplicar-despachar funcionando de extremo a extremo, y refleja
+el Ejercicio 3 casi exactamente.
+
+!!! note "Qué acaba de pasar"
+ Un desconocido en internet hizo POST de JSON a tu servicio, y tres guardianes se ejecutaron
+ antes que una sola línea de tu lógica de negocio: la comprobación de la firma rechazó
+ falsificaciones, el almacén de idempotencia rechazó reintentos, y solo entonces el
+ listener tipado tradujo el evento en un comando CQRS `DepositFunds` —así que
+ la raíz de agregado del monedero siguió haciendo cumplir sus propios invariantes—. Tú escribiste el
+ cuerpo de `handle()`; PyFly proporcionó el desafío que lo rodea.
+
+!!! note "Almacén de idempotencia en memoria"
+ El `InMemoryWebhookEventStore` por defecto guarda las claves vistas en un
+ `set` de Python. Para clústeres de producción, implementa el protocolo
+ `WebhookEventStore` respaldado por Redis o una base de datos:
+ ```python
+ class RedisEventStore:
+ async def already_processed(
+ self, key: str,
+ ) -> bool: ...
+ async def remember(self, key: str) -> None: ...
+ ```
+ Pásalo como `event_store=RedisEventStore(...)` a `WebhookProcessor`.
+
+---
+
+## Callbacks salientes
+
+Cuando Lumen registra un desembolso a un banco socio, ese socio espera un POST `DisbursementSettled` a su URL de webhook —firmado, reintentado ante fallos y auditable—. El módulo `pyfly.callbacks` de PyFly se encarga del lado saliente.
+
+!!! note "Término nuevo: callback saliente"
+ Un *callback* aquí es lo inverso del webhook entrante que acabas de construir:
+ ahora *Lumen* es el remitente, que hace POST de un evento *a* la URL de un socio. El
+ módulo te da la misma maquinaria de confianza y fiabilidad en la salida:
+ firma cada carga útil (para que el socio pueda verificarla), reintenta los fallos
+ transitorios con retroceso (backoff) y registra cada intento para que tengas un rastro de auditoría
+ cuando un socio pregunte "¿nos llegasteis a avisar de la transacción X?".
+
+### Suscripciones y configuración
+
+Cada socio se modela como una **`CallbackConfig`** —un registro con alcance de inquilino (tenant) que contiene el secreto del webhook, las suscripciones a eventos y la política de reintentos—.
+
+!!! note "Término nuevo: inquilino (tenant)"
+ Un *inquilino* (tenant) es un cliente u organización aislada dentro de una
+ aplicación compartida —aquí, `"lumen"`—. Los callbacks tienen alcance de inquilino para que un
+ despliegue multiinquilino pueda mantener las URLs de socios, secretos y política de reintentos
+ de cada inquilino por separado y nunca cruzar los cables. Con un solo inquilino simplemente pasas
+ el mismo `tenant_id` en todas partes.
+
+**Paso 1 — Describe cada suscripción.** Una `CallbackSubscription` empareja un
+`event_type` con la `target_url` a la que hacerle POST. Usa el nombre exacto del evento
+(`"DisbursementSettled"`) para encaminar un evento, o `"*"` como comodín que
+coincide con todos los eventos del inquilino —útil para un endpoint de auditoría que quiere
+el flujo completo—.
+
+**Paso 2 — Envuélvelas en una `CallbackConfig` y guárdala.** La configuración lleva el
+`secret` compartido (usado para firmar cada carga útil), la política de reintentos (`max_attempts`,
+`backoff_ms`) y la lista de suscripciones. Persístela a través de un
+`CallbackConfigRepository` —`InMemoryCallbackConfigRepository` por ahora, uno
+respaldado por base de datos en producción—.
+
+::: listing lumen/callbacks/register_partner.py | Listado 17.11 — Registrando un callback de socio
+from pyfly.callbacks import (
+ CallbackConfig,
+ CallbackSubscription,
+ InMemoryCallbackConfigRepository,
+ InMemoryCallbackExecutionRepository,
+)
+
+
+async def register_clearance_bank(configs) -> None:
+ await configs.save(CallbackConfig(
+ tenant_id="lumen",
+ name="clearance-bank",
+ secret="cb-secret-xyz",
+ max_attempts=5,
+ backoff_ms=2_000,
+ subscriptions=[
+ CallbackSubscription(
+ event_type="DisbursementSettled",
+ target_url=(
+ "https://api.clearancebank.example.com"
+ "/hooks/lumen"
+ ),
+ ),
+ CallbackSubscription(
+ event_type="*",
+ target_url=(
+ "https://audit.clearancebank.example.com"
+ "/all-events"
+ ),
+ ),
+ ],
+ ))
+:::
+
+`event_type="*"` es un comodín: todos los eventos despachados para el inquilino coinciden. Los tipos con nombre solo coinciden con la cadena exacta del tipo de evento.
+
+### Despachando un evento
+
+**`CallbackDispatcher.dispatch()`** abre el evento en abanico hacia cada suscripción coincidente:
+
+::: listing lumen/callbacks/dispatcher_config.py | Listado 17.12 — Cableando e invocando CallbackDispatcher
+from pyfly.callbacks import (
+ CallbackDispatcher,
+ InMemoryCallbackConfigRepository,
+ InMemoryCallbackExecutionRepository,
+)
+from pyfly.container import bean, configuration
+
+
+@configuration
+class CallbackConfig_:
+
+ @bean
+ def callback_configs(self) -> InMemoryCallbackConfigRepository:
+ return InMemoryCallbackConfigRepository()
+
+ @bean
+ def callback_executions(
+ self,
+ ) -> InMemoryCallbackExecutionRepository:
+ return InMemoryCallbackExecutionRepository()
+
+ @bean
+ def callback_dispatcher(
+ self,
+ configs: InMemoryCallbackConfigRepository,
+ executions: InMemoryCallbackExecutionRepository,
+ ) -> CallbackDispatcher:
+ return CallbackDispatcher(
+ configs=configs,
+ executions=executions,
+ )
+:::
+
+Luego, en el servicio de dominio —fíjate en que la carga útil usa `amount` en unidades menores (céntimos), así que `50_000` son EUR 500.00—:
+
+```python
+results = await dispatcher.dispatch(
+ "lumen", # tenant_id
+ "DisbursementSettled",
+ {"id": "txn-009", "amount": 50_000, "currency": "EUR"},
+)
+```
+
+`dispatch()` devuelve un registro `CallbackExecution` por cada suscripción coincidente, cada uno con `status`, `attempts`, `response_status` y `delivered_at`.
+
+**Ejecútalo.** El emisor HTTP por defecto del despachador no llama realmente a la
+red —registra la petición que *haría* y devuelve `200`—, lo cual es
+perfecto para ver el cableado sin levantar un servidor de socio. Suelta esto
+en un script (o en `uv run python`) desde `samples/lumen`:
+
+::: listing lumen/callbacks/try_dispatch.py | Listado 17.12a — Despacho contra el emisor por defecto (solo registra)
+import asyncio
+
+from pyfly.callbacks import (
+ CallbackConfig,
+ CallbackDispatcher,
+ CallbackSubscription,
+ InMemoryCallbackConfigRepository,
+ InMemoryCallbackExecutionRepository,
+)
+
+
+async def main() -> None:
+ configs = InMemoryCallbackConfigRepository()
+ await configs.save(CallbackConfig(
+ tenant_id="lumen",
+ name="clearance-bank",
+ secret="cb-secret-xyz",
+ subscriptions=[CallbackSubscription(
+ event_type="DisbursementSettled",
+ target_url="https://api.clearancebank.example.com/hooks/lumen",
+ )],
+ ))
+ dispatcher = CallbackDispatcher(
+ configs=configs,
+ executions=InMemoryCallbackExecutionRepository(),
+ )
+ results = await dispatcher.dispatch(
+ "lumen",
+ "DisbursementSettled",
+ {"id": "txn-009", "amount": 50_000, "currency": "EUR"},
+ )
+ for r in results:
+ print(r.status, r.attempts, r.response_status, r.target_url)
+
+
+asyncio.run(main())
+:::
+
+Deberías ver una ejecución entregada, con la petición firmada registrada justo
+encima de ella:
+
+```text
+would POST https://api.clearancebank.example.com/hooks/lumen headers={'X-Pyfly-Signature': 'sha256=...', 'Content-Type': 'application/json'} body={'id': 'txn-009', 'amount': 50000, 'currency': 'EUR'}
+DELIVERED 1 200 https://api.clearancebank.example.com/hooks/lumen
+```
+
+`DELIVERED 1 200` se lee como: estado `DELIVERED`, con éxito en el intento `1`, HTTP
+`200`. Para enviar de verdad, pasa tu propio emisor `http=` (un POST de `httpx`/`aiohttp`)
+a `CallbackDispatcher`; la lógica de firma, reintento y auditoría se mantiene idéntica.
+
+!!! note "Qué acaba de pasar"
+ Una sola llamada a `dispatch()` buscó todas las suscripciones que el inquilino tiene para ese
+ tipo de evento, firmó la carga útil, hizo POST y escribió un registro `CallbackExecution`
+ para cada una —todo ello sin que tu servicio de dominio supiera cuántos socios
+ están escuchando ni cómo funcionan los reintentos—. Añadir un socio más adelante es solo otra
+ `CallbackConfig` guardada; el código de desembolso nunca cambia.
+
+### Firma HMAC y lógica de reintentos
+
+Cuando `CallbackConfig.secret` está establecido, `CallbackDispatcher` firma la carga útil JSON canónica antes de cada POST usando HMAC-SHA256:
+
+```python
+# canonical body — compact, keys sorted
+canonical = json.dumps(payload, separators=(",", ":"), sort_keys=True)
+sig = hmac.new(secret, canonical.encode(), hashlib.sha256).hexdigest()
+headers["X-Pyfly-Signature"] = f"sha256={sig}"
+```
+
+El destinatario puede verificar la firma usando el propio `HmacSignatureValidator` de PyFly —la misma clase usada para los webhooks entrantes—.
+
+**Política de reintentos:**
+
+- El despachador reintenta hasta `max_attempts` veces (por defecto `5`).
+- Entre reintentos aplica retroceso exponencial: `delay = min(backoff_ms * 2^(attempt-1), 300_000) ms`.
+- Solo los códigos de estado HTTP *transitorios* disparan un reintento: `408`, `429`, `500`, `502`, `503`, `504`, o cualquiera `>= 500`.
+- Los errores de cliente permanentes (`4xx` salvo `408`/`429`) marcan la ejecución como `FAILED` de inmediato sin reintentar.
+- Ante el éxito (`2xx`) la ejecución se marca como `DELIVERED` y se estampa `delivered_at`.
+
+::: listing lumen/callbacks/models_overview.py | Listado 17.13 — Ciclo de vida del estado de CallbackExecution
+from pyfly.callbacks import CallbackStatus
+
+# After a successful delivery:
+assert execution.status == CallbackStatus.DELIVERED
+assert execution.delivered_at is not None
+assert execution.response_status == 200
+
+# After all retries are exhausted:
+assert execution.status == CallbackStatus.FAILED
+assert execution.attempts == 5
+assert execution.last_error is not None
+:::
+
+### Protección contra SSRF: dominios autorizados
+
+El campo `authorized_domains` de `CallbackConfig` actúa como una lista de permitidos. Cuando está establecido, `CallbackDispatcher` comprueba que el nombre de host de la URL de destino coincide con uno de los dominios permitidos antes de realizar cualquier petición saliente. Una URL que no supera la comprobación se marca de inmediato como `FAILED` con `last_error="Domain not authorized"` —no se realiza ninguna petición HTTP—.
+
+```python
+from pyfly.callbacks import AuthorizedDomain, CallbackConfig
+
+config = CallbackConfig(
+ tenant_id="lumen",
+ name="safe-config",
+ secret="s3cr3t",
+ authorized_domains=[
+ AuthorizedDomain(domain="clearancebank.example.com"),
+ ],
+ subscriptions=[...],
+)
+```
+
+Los subdominios de los dominios permitidos también se aceptan (p. ej. `api.clearancebank.example.com`).
+
+!!! note "Término nuevo: SSRF"
+ La *falsificación de peticiones del lado del servidor* (Server-Side Request Forgery) es un ataque en el que un valor malicioso engaña a
+ tu servidor para que haga una petición HTTP que no debería —por ejemplo, una
+ URL de socio que apunta a `http://169.254.169.254/` (un endpoint de metadatos
+ de la nube) para robar credenciales—. Como las URLs de callback pueden venir de
+ configuración proporcionada por el socio, la lista de permitidos `authorized_domains` cierra esa puerta:
+ un host que no está en la lista se marca como `FAILED` *antes* de que ninguna petición
+ salga del proceso. Para verificarlo, añade un `AuthorizedDomain` para un host, luego
+ despacha una suscripción cuya `target_url` apunte a otro sitio: el
+ `CallbackExecution` devuelto mostrará `status=FAILED`, `attempts=0` y
+ `last_error="Domain not authorized"`, y no se enviará nada.
+
+!!! spring "Equivalencia con Spring"
+ El trío `@scheduled` / `CronExpression` / `TaskScheduler` de PyFly
+ refleja el `@Scheduled` / `CronExpression` /
+ `ThreadPoolTaskScheduler` de Spring. Los puertos de notificación se corresponden con los
+ `MailSender` / `JavaMailSender` de Spring. `WebhookProcessor` se corresponde con
+ un `@RestController` de Spring + el `HmacRequestMatcher` de HMAC de Spring
+ Security. `CallbackDispatcher` con firma HMAC y
+ reintentos refleja el patrón `WebhookPublisher` de Spring
+ Modulith.
+
+---
+
+**Ejecútalo — confirma que la suite sigue en verde.** Añadiste cuatro nuevos patrones
+de integración; asegúrate de que nada más sufrió una regresión. Desde el directorio `samples/lumen`:
+
+```bash
+uv run --extra dev pytest -q
+```
+
+Deberías ver que todas las pruebas existentes siguen pasando:
+
+```text
+......................................... [100%]
+41 passed in 0.28s
+```
+
+Los tres ejercicios de abajo añaden sus propias pruebas de programación, notificación y webhook —
+vuelve a ejecutar este comando después de cada uno para ver subir el recuento—. Recuerda la
+bandera `--extra dev`; el `uv sync` a secas omite pytest.
+
+---
+
+## Lo que construiste {.recap}
+
+Extendiste Lumen hasta convertirlo en un sistema conectado que opera con independencia de las peticiones entrantes:
+
+- **Tareas programadas** — `@scheduled` con los disparadores `cron`, `fixed_rate` y `fixed_delay` ejecuta trabajo según un calendario o un temporizador. `CronExpression` impulsa los cálculos de los momentos de disparo, incluida la programación consciente de la zona horaria con el horario de verano gestionado automáticamente. `lock=True` serializa la ejecución en todo el clúster a través del puerto `DistributedLock`. `@async_method` descarga el trabajo fire-and-forget en el ejecutor.
+
+- **Notificaciones** — Los protocolos de puerto `EmailService`, `SmsService` y `PushService` desacoplan la lógica de negocio de los adaptadores de proveedor (SMTP, SendGrid, Resend, Twilio, Firebase). `DefaultEmailService` y sus hermanos capturan los errores del proveedor y devuelven valores `NotificationResult` estructurados en lugar de propagar excepciones. `DepositNotificationListener` se suscribe al evento de EDA real `FundsDeposited` y convierte los importes en unidades menores en cadenas de visualización antes de enviar.
+
+- **Webhooks entrantes** — `AbstractWebhookEventListener` define consumidores tipados. `WebhookProcessor` filtra cada evento con `HmacSignatureValidator` y `WebhookEventStore` antes de despacharlo a los listeners. Los ganchos `on_error()` permiten la integración con una cola de mensajes muertos sin romper el bucle de despacho.
+
+- **Callbacks salientes** — `CallbackDispatcher` abre los eventos en abanico hacia los destinos de `CallbackSubscription`, firma las cargas útiles con HMAC-SHA256 bajo la cabecera `X-Pyfly-Signature` y reintenta ante fallos transitorios con retroceso exponencial. Los registros `CallbackExecution` proporcionan un rastro de auditoría de entrega completo. `authorized_domains` previene la SSRF.
+
+---
+
+## Pruébalo tú mismo {.exercises}
+
+1. **Bloqueo de clúster.** Añade una segunda instancia de `DailyRollupService` a una
+ prueba que levante dos instancias de `ApplicationContext` compartiendo un
+ `FakeDistributedLock` (uno que solo devuelva `True` para el primer
+ adquirente). Afirma que `run()` se invoca exactamente una vez en ambas
+ instancias para un único tic de cron.
+
+2. **Cambio de proveedor.** Reemplaza `SmtpEmailProvider` por un
+ `DummyEmailProvider` en la suite de pruebas. Escribe una prueba que deposite
+ EUR 100 (10 000 unidades menores) en el monedero `w-001` a través del manejador
+ de depósitos, disparando un evento `FundsDeposited`. El proveedor registra
+ cada mensaje que recibió en su lista `.sent`, así que afirma que
+ `provider.sent[-1].body_text` contiene el ID del monedero y el
+ importe formateado (`100.00 EUR`).
+
+3. **Ataque de reenvío de firma.** Escribe una prueba que invoque
+ `PaymentWebhookHandler.receive()` dos veces con el mismo cuerpo en crudo,
+ cabeceras y clave de idempotencia. Afirma que la primera llamada devuelve 200
+ y acredita el monedero (disparando `FundsDeposited`), y que la segunda
+ llamada también devuelve 200 (el duplicado lo ignora silenciosamente
+ `InMemoryWebhookEventStore`) pero **no** acredita el monedero una
+ segunda vez.
diff --git a/book/manuscript-es/18-production.md b/book/manuscript-es/18-production.md
new file mode 100644
index 00000000..cc44b767
--- /dev/null
+++ b/book/manuscript-es/18-production.md
@@ -0,0 +1,1095 @@
+Capítulo 18
+
+# Extender PyFly y llevarlo a producción {.chtitle}
+
+::: figure art/openers/ch18.svg |
+
+Lumen ya no es un juguete. A lo largo de los diecisiete capítulos anteriores construiste un servicio de monedero (wallet) desde una única clase anotada hasta un microservicio completo orientado a eventos: CQRS, sagas, EDA, clientes HTTP, caché, resiliencia, observabilidad, seguridad y un conjunto de pruebas respaldado por contenedores reales. Sabes cómo ejecutarlo, depurarlo y desplegarlo.
+
+Este capítulo final trata sobre la distancia que separa el "funciona en mi portátil" del "funciona de forma fiable para usuarios reales". Esa distancia tiene tres dimensiones. Primera: la **extensibilidad**, la capacidad de añadir comportamiento sin bifurcar el framework. Segunda: las funcionalidades que tu dominio puede necesitar ahora mismo: un motor de reglas, configuración centralizada, varios idiomas, push en tiempo real, una CLI. Tercera: los hábitos operativos que separan un proyecto de fin de semana de un servicio en producción.
+
+Avanzarás rápido. Cada sección escoge un tema, muestra la API mínima que funciona y la conecta con Lumen. Al final tendrás una imagen completa del ecosistema PyFly y una lista de comprobación de producción que merece la pena tener a mano.
+
+!!! note "Convenciones de este capítulo"
+ Los listados y las claves de configuración de aquí apuntan a PyFly
+ **v26.6.110**. Dos hechos de despliegue de esa versión recorren toda la
+ sección "Llevarlo a producción", así que conviene conocerlos de
+ antemano:
+
+ - La aplicación escucha en `pyfly.server.port` (por defecto `8080`), la
+ clave equivalente a `server.port` de Spring. Las antiguas claves
+ `pyfly.web.port` / `PYFLY_WEB_PORT` se eliminaron en v26.6.102.
+ - El Actuator y el panel de administración se ejecutan en un **puerto de
+ gestión independiente** (`pyfly.management.server.port`, por defecto
+ `9090`), abierto y sin autenticación por defecto. Lo cubrimos en detalle
+ cuando conectemos las sondas de salud.
+
+ Cada funcionalidad de abajo se construye igual: un breve "por qué", el
+ código y, a continuación, un punto de control **Ejecútalo** que muestra el
+ comando exacto y la salida que deberías ver. Escribe los comandos a medida
+ que avanzas: así es como las ideas se asientan.
+
+---
+
+## Plugins y puntos de extensión
+
+### ¿Por qué un sistema de plugins?
+
+El framework central es pequeño de forma intencionada. Las funcionalidades opcionales (formateadores, sumideros de auditoría, canales de notificación) deberían poder conectarse como plugins para que los equipos compongan solo lo que necesitan y publiquen añadidos sin tocar las interioridades del framework.
+
+El módulo `pyfly.plugins` de PyFly refleja el registro de plugins de Spring: declaras un **punto de extensión** (una ranura con nombre), **extensiones** (contribuciones concretas) y las agrupas en un **plugin** con un ciclo de vida.
+
+La nueva jerga, en términos sencillos: un **punto de extensión** es un hueco etiquetado en tu aplicación: "todo lo que quiera ser un sumidero de auditoría se conecta aquí". Una **extensión** es una cosa que llena el hueco. Un **plugin** es el paquete que entrega una o más extensiones juntas y que se puede arrancar y detener como una unidad. Si alguna vez has definido una interfaz de Java y has dejado que quienes la llaman registren implementaciones de ella, ya conoces la forma: los decoradores de abajo simplemente hacen el cableado declarativo.
+
+Construiremos el ejemplo útil más pequeño: un sumidero de auditoría de consola que imprime cada evento que se le entrega.
+
+**Paso 1: declara el punto de extensión.** Este es el contrato. Todo sumidero de auditoría debe prometer un método `record(event)`. La cadena `id="audit-sinks"` es el nombre que usa el resto del código para encontrar más tarde cada sumidero.
+
+**Paso 2: escribe un plugin que aporte un sumidero.** El decorador `@plugin` envuelve una clase con un `id` y una `version` obligatorios; la clase interna `@extension` es la contribución real. Hereda de la interfaz del punto de extensión (`AuditSink`) para que el registro pueda confirmar que respeta el contrato.
+
+**Paso 3: dale al plugin un ciclo de vida.** Los métodos `start` y `stop` son donde abres y cierras recursos (un descriptor de archivo, una conexión de red). El gestor de plugins los llama por ti.
+
+Aquí tienes los tres pasos en un único archivo.
+
+::: listing lumen/plugins/audit.py | Listado 18.1 — Declarar un plugin de sumidero de auditoría
+from pyfly.plugins import (
+ PluginManager,
+ extension,
+ extension_point,
+ plugin,
+)
+
+
+@extension_point(id="audit-sinks")
+class AuditSink:
+ """Interface that all audit sinks must implement."""
+
+ def record(self, event: dict) -> None: ...
+
+
+@plugin(id="console-audit", version="1.0.0")
+class ConsoleAuditPlugin:
+
+ @extension(point="audit-sinks", priority=10)
+ class ConsoleSink(AuditSink):
+ name = "console"
+
+ def record(self, event: dict) -> None:
+ print(f"[AUDIT] {event}")
+
+ async def start(self) -> None:
+ print("ConsoleAuditPlugin started")
+
+ async def stop(self) -> None:
+ print("ConsoleAuditPlugin stopped")
+:::
+
+**Cómo funciona.** `@extension_point(id="audit-sinks")` registra una ranura con nombre y declara la interfaz que toda contribución debe implementar. `@plugin(id="console-audit", version="1.0.0")` declara una clase de plugin con un `id` y una `version` obligatorios. `@extension(point="audit-sinks", priority=10)` marca una clase interna como contribución a esa ranura; la clase interna debe heredar de la interfaz del punto de extensión para que el registro pueda validarla. La prioridad más alta gana la primera posición al iterar los resultados.
+
+Cargar y ejecutar el plugin:
+
+::: listing lumen/plugins/runner.py | Listado 18.2 — Conducir el ciclo de vida del plugin
+import asyncio
+
+from pyfly.plugins import PluginManager
+
+from lumen.plugins.audit import ConsoleAuditPlugin
+
+
+async def main() -> None:
+ manager = PluginManager()
+ await manager.add(ConsoleAuditPlugin)
+ await manager.start_all()
+
+ sinks = await manager.registry.get("audit-sinks")
+ for sink in sinks:
+ sink.record({"action": "deposit", "amount_minor": 100})
+
+ await manager.stop_all()
+
+
+asyncio.run(main())
+:::
+
+`PluginManager.add()` inspecciona la clase en busca de declaraciones `@extension_point` anidadas y luego registra cada contribución `@extension`. `start_all()` invoca los hooks `init` y después `start` de cada plugin en orden de dependencias; `stop_all()` invierte la secuencia, llamando a `stop` y luego a `unload`. Las dependencias circulares lanzan `PluginResolutionError` antes de que se ejecute código alguno.
+
+!!! tip "Ejecútalo"
+ Guarda ambos listados bajo `src/lumen/plugins/` y ejecuta el módulo runner
+ directamente:
+
+ ```bash
+ uv run python -m lumen.plugins.runner
+ ```
+
+ Deberías ver dispararse los hooks del ciclo de vida, registrarse el único
+ evento y producirse el apagado limpio:
+
+ ```
+ ConsoleAuditPlugin started
+ [AUDIT] {'action': 'deposit', 'amount_minor': 100}
+ ConsoleAuditPlugin stopped
+ ```
+
+ El orden lo es todo: `start` se ejecuta antes de usar ningún sumidero, tu
+ código itera los sumideros registrados y `stop` se ejecuta el último. Si
+ añades un segundo plugin más adelante, `start_all()` arranca ambos en orden
+ de dependencias y `stop_all()` los apaga en orden inverso: nunca gestionas
+ ese orden a mano.
+
+**Lo que acaba de ocurrir.** Añadiste una capacidad a la aplicación —el
+registro de auditoría— sin editar una sola línea de código del framework. El
+framework descubrió tu plugin, validó que su extensión respeta el contrato
+`AuditSink`, ejecutó su ciclo de vida y te entregó los sumideros registrados
+para que los llamaras. Esa es la promesa central de un sistema de plugins:
+abierto a la extensión, cerrado a la modificación.
+
+| Método | Descripción |
+|---|---|
+| `await manager.add(cls)` | Escanea y registra una clase de plugin |
+| `await manager.start_all()` | `init` → `start` en orden de dependencias |
+| `await manager.stop_all()` | `stop` → `unload` en orden inverso |
+| `await manager.remove(plugin_id)` | Descarga un plugin; devuelve `False` si es desconocido |
+| `await manager.registry.get(point_id)` | Extensiones de una ranura, ordenadas por prioridad |
+
+!!! spring "Equivalencia con Spring"
+ `@plugin` / `@extension_point` / `@extension` reflejan
+ `@Plugin` / `ExtensionPoint` / `@Extension` de la API de plugins
+ de Spring. `PluginManager.start_all()` desempeña el papel de la
+ gestión del ciclo de vida del contenedor de plugins de Spring. El
+ arranque en orden de dependencias y el apagado en orden inverso son
+ idénticos en semántica.
+
+---
+
+## Reglas de negocio con el motor de reglas
+
+La mayoría de los servicios del mundo real arrastran lógica que pertenece al negocio, no al código: "marca los pedidos de más de 500.000 céntimos", "bloquea los envíos a regiones sancionadas", "aplica un recargo fuera de horario". Codificar esos umbrales en Python a fuego significa recompilar cada vez que el negocio cambia de opinión.
+
+El módulo `pyfly.rule_engine` de PyFly ofrece a los responsables de producto un dial YAML que pueden girar sin tocar el código fuente.
+
+Un **motor de reglas**, en términos sencillos, es un pequeño intérprete de sentencias "si esto, entonces aquello" que viven en datos en lugar de en código. Le proporcionas un saco de hechos (el *contexto*) y un conjunto de reglas; comprueba la condición de cada regla contra los hechos y, para las que coinciden, ejecuta las acciones listadas, normalmente escribiendo una marca de vuelta en el contexto. La ventaja es que las *reglas* las pueden editar quienes no programan, mientras que el *motor* que las ejecuta es fijo y está probado.
+
+### Definir reglas en YAML
+
+Construiremos una comprobación de fraude y límite en dos pasos: primero escribir las reglas como datos, luego conectar un servicio que las ejecuta.
+
+**Paso 1: escribe las reglas como YAML.** Cada regla nombra una condición `when` y una lista de acciones `then`. Como las reglas son datos planos, un responsable de producto puede revisarlas en una pull request y un servidor de configuración puede intercambiarlas en caliente en tiempo de ejecución.
+
+Las reglas viven en un archivo YAML separado que cualquier miembro del equipo puede revisar. El evaluador analiza este archivo una vez al arranque, o en cada obtención si lo recargas en caliente desde un Config Server (consulta la siguiente sección).
+
+::: listing lumen/rules/transaction_rules.yaml | Listado 18.3 — Reglas de fraude y límite diario (importes en unidades menores)
+id: transaction-rules
+name: Lumen transaction rules
+
+rules:
+ - id: daily-limit
+ priority: 20
+ when:
+ op: ge
+ field: transaction.daily_total
+ value: 500000
+ then:
+ - type: set
+ target: flags.limit_exceeded
+ value: true
+ - type: log
+ value: "daily limit exceeded"
+
+ - id: fraud-country
+ priority: 10
+ when:
+ op: in
+ field: transaction.country
+ value: ["XX", "YY", "ZZ"]
+ then:
+ - type: set
+ target: flags.fraud_risk
+ value: true
+ - type: log
+ value: "high-risk country detected"
+
+ - id: high-value
+ priority: 5
+ when:
+ op: ge
+ field: transaction.amount
+ value: 100000
+ then:
+ - type: set
+ target: flags.high_value
+ value: true
+:::
+
+Cada regla tiene una condición `when` y una lista de acciones `then`. Los importes son siempre **unidades menores enteras** (céntimos), así que `100000` son 1.000,00 €. Las condiciones usan estos operadores:
+
+| Comparación | Lógicos |
+|---|---|
+| `eq`, `ne`, `gt`, `ge`, `lt`, `le` | `and`, `or`, `not` |
+| `in`, `not_in`, `regex` | (con `conditions: [...]`) |
+
+Las acciones son `set` (escribir en una ruta del contexto), `increment` o `log`. Crea una subclase de `RuleEvaluator` y sobreescribe `_execute_action` para añadir `call`, `calculate` o cualquier verbo personalizado.
+
+**Paso 2: conecta un servicio que cargue y ejecute las reglas.** El servicio analiza el YAML una vez en la construcción y luego expone un método `assess()` que construye un contexto, ejecuta el evaluador y devuelve las marcas que las reglas establecieron.
+
+::: listing lumen/rules/risk_service.py | Listado 18.4 — Evaluar reglas contra una transacción
+from pathlib import Path
+
+from pyfly.container import service
+from pyfly.rule_engine import RuleSetEvaluator, RuleSetLoader
+
+
+@service
+class RiskService:
+ """Evaluate transaction-level rules and return risk flags."""
+
+ def __init__(self) -> None:
+ yaml_text = (
+ Path(__file__).parent / "transaction_rules.yaml"
+ ).read_text()
+ self._ruleset = RuleSetLoader.from_yaml(yaml_text)
+ self._evaluator = RuleSetEvaluator()
+
+ def assess(
+ self,
+ amount: int,
+ daily_total: int,
+ country: str,
+ ) -> dict:
+ ctx = {
+ "transaction": {
+ "amount": amount,
+ "daily_total": daily_total,
+ "country": country,
+ },
+ "flags": {},
+ }
+ self._evaluator.evaluate(self._ruleset, ctx)
+ return ctx["flags"]
+:::
+
+**Cómo funciona.** `RuleSetLoader.from_yaml(text)` analiza el YAML en un AST. `RuleSetEvaluator.evaluate(ruleset, ctx)` recorre cada regla en orden de prioridad, evalúa la cláusula `when` y aplica las acciones `then` que coinciden, mutando `ctx` en el sitio y devolviendo una `list[EvaluationResult]`. El diccionario `flags` es la salida autoritativa: un manejador (handler) posterior rechaza, encola o marca la transacción en función de las claves que se hayan establecido. `amount` y `daily_total` están en unidades menores (céntimos) para coincidir con el dominio de Lumen.
+
+!!! tip "Ejecútalo"
+ Ejercita el servicio desde un REPL de Python para ver dispararse las
+ reglas. Una transferencia de 6.000,00 € (`600000` unidades menores)
+ dispara a la vez los umbrales de alto valor y de límite diario:
+
+ ```bash
+ uv run python -c "
+ from lumen.rules.risk_service import RiskService
+ print(RiskService().assess(amount=600000, daily_total=600000, country='US'))
+ "
+ ```
+
+ Salida esperada: las marcas que establecen las reglas coincidentes, y nada
+ más:
+
+ ```python
+ {'high_value': True, 'limit_exceeded': True}
+ ```
+
+ Ahora baja el importe a `50000` (500,00 €) con un país limpio y recibes de
+ vuelta un `{}` vacío: ninguna regla coincidió, así que no se marcó nada.
+ Cambiaste el *resultado* sin tocar Python: ese es el dial que el YAML da a
+ tus responsables de producto.
+
+::: figure art/figures/18-production.svg | Figura 18.1 — Evaluación de reglas en la frontera del servicio. Las reglas YAML se analizan una vez al arranque; cada transacción pasa por el evaluador como un diccionario de contexto mutable.
+
+!!! tip "Recargar reglas en caliente sin redesplegar"
+ Almacena `transaction_rules.yaml` en el Config Server (consulta la
+ siguiente sección) y vuelve a analizarlo en cada obtención. Tu motor de
+ reglas se convierte en un dial en vivo que controla el negocio.
+
+---
+
+## Configuración centralizada (Config Server)
+
+A medida que Lumen crece a múltiples servicios, cada uno arrastra su propia copia de URLs de base de datos, tiempos de espera y feature flags. El módulo Config Server elimina esa duplicación: un servicio posee la verdad; todos los demás la obtienen al arrancar.
+
+Un **config server**, en términos sencillos, es un pequeño servicio HTTP cuyo único trabajo es repartir configuración. En lugar de incrustar tiempos de espera y URLs en el `pyfly.yaml` de cada servicio, los almacenas en un único lugar y cada servicio pide su paquete al arrancar. Cambia el valor una vez, reinicia (o refresca) a los consumidores y toda la flota se mueve junta.
+
+### Ejecutar el servidor
+
+Habilita el servidor en `pyfly.yaml`:
+
+```yaml
+pyfly:
+ config-server:
+ enabled: true
+ backend:
+ root: /etc/lumen/config
+```
+
+Eso es todo. PyFly autoconfigura un `ConfigServer` respaldado por un `FilesystemConfigBackend` y monta las rutas HTTP automáticamente:
+
+| Método | Ruta | Propósito |
+|---|---|---|
+| `GET` | `/{app}/{profile}` | Obtener el paquete de configuración combinado |
+| `GET` | `/{app}/{profile}/{label}` | Obtener para una etiqueta concreta |
+| `POST` | `/{app}/{profile}` | Guardar un paquete de configuración |
+| `GET` | `/_list` | Listar todos los paquetes almacenados |
+
+La forma de la respuesta es compatible con Spring Cloud Config, así que un servicio Spring existente puede consumir el mismo endpoint sin cambios.
+
+### Guardar y obtener configuración de forma programática
+
+::: listing lumen/config/seed.py | Listado 18.5 — Sembrar y leer un paquete de configuración
+import asyncio
+
+from pyfly.config_server import (
+ ConfigClient,
+ ConfigServer,
+ FilesystemConfigBackend,
+)
+
+
+async def seed() -> None:
+ server = ConfigServer(FilesystemConfigBackend("/etc/lumen/config"))
+ await server.save(
+ "wallet",
+ "prod",
+ {
+ "db.url": "postgres://db:5432/lumen",
+ "cache.ttl": 30,
+ },
+ )
+ bundle = await server.fetch("wallet", "prod")
+ print(bundle)
+
+
+asyncio.run(seed())
+:::
+
+!!! tip "Ejecútalo"
+ Con `pyfly.config-server.enabled: true` en `pyfly.yaml`, arranca la app y
+ haz un curl al paquete que sembraste. Recuerda: las rutas del config-server
+ se sirven en el puerto de **aplicación** (`8080`), no en el puerto de
+ gestión.
+
+ ```bash
+ uv run pyfly run
+ # en otra terminal:
+ curl http://localhost:8080/wallet/prod
+ ```
+
+ La respuesta tiene la forma de Spring Cloud Config: tus claves sembradas
+ llegan dentro de un array `propertySources`:
+
+ ```json
+ {
+ "name": "wallet",
+ "profiles": ["prod"],
+ "propertySources": [
+ {"name": "wallet-prod", "source": {"db.url": "postgres://db:5432/lumen", "cache.ttl": 30}}
+ ]
+ }
+ ```
+
+ Como la forma coincide con Spring Cloud Config, un servicio Spring Boot
+ existente puede apuntar su `spring.config.import=configserver:` a esta misma
+ URL y consumirla sin cambios.
+
+Los servicios cliente la obtienen al arrancar con:
+
+::: listing lumen/config/bootstrap.py | Listado 18.6 — Obtener configuración remota al arranque
+from pyfly.config_server import ConfigClient
+
+
+async def load_remote() -> dict:
+ client = ConfigClient(
+ url="http://config:8888",
+ application="wallet",
+ profile="prod",
+ label="main",
+ )
+ return await client.fetch()
+:::
+
+`ConfigClient.fetch()` hace un GET a `{url}/{application}/{profile}/{label}`, combina el array `propertySources` (la prioridad más alta primero) y devuelve un diccionario plano `{dotted_key: value}`. En el funcionamiento normal nunca llamas a `ConfigClient` directamente: establece `pyfly.cloud.config.uri` en `pyfly.yaml` y `PyFlyApplication` lo llama automáticamente durante el bootstrap, combinando el resultado en el `Config` de la aplicación como una fuente de alta precedencia.
+
+!!! note "Prioridad de respaldo"
+ El servidor ensambla hasta cuatro capas de superposición:
+ `{app}/{profile}`, `{app}/default`, `application/{profile}`,
+ `application/default`. Un cliente las combina con la primera fuente
+ ganando, así que las anulaciones específicas de entorno siempre baten a
+ los valores por defecto compartidos.
+
+---
+
+## Internacionalización (i18n)
+
+Los mensajes de error y las notificaciones de Lumen viven actualmente como literales de cadena en Python. Cuando los usuarios hablan idiomas diferentes, ese enfoque no escala.
+
+**i18n** es la abreviatura de *internacionalización* (las 18 letras entre la "i" y la "n"). En la práctica significa sacar cada cadena visible para el usuario de tu código hacia **paquetes de recursos** por idioma, y luego elegir el paquete correcto en tiempo de ejecución según el idioma preferido de quien llama. Tu código se refiere a una cadena mediante una clave estable como `wallet.deposit_ok`; el framework busca la traducción.
+
+Habilita el subsistema i18n con un único flag:
+
+```yaml
+pyfly:
+ i18n:
+ enabled: true
+ base-path: i18n/
+ default-locale: en
+```
+
+### Escribir paquetes de recursos
+
+**Paso 1: escribe un paquete por idioma.** Los archivos se nombran `messages_.yaml`. Las claves se comparten entre idiomas; solo cambian los valores. Los marcadores `{0}`, `{1}` son marcadores de posición posicionales que el framework rellena en tiempo de renderizado.
+
+```yaml
+# i18n/messages_en.yaml
+wallet:
+ deposit_ok: "Deposited {0} minor units to wallet {1}."
+ limit_exceeded: "Daily limit exceeded. Maximum is {0} minor units."
+
+# i18n/messages_es.yaml
+wallet:
+ deposit_ok: "Se depositaron {0} unidades menores en la billetera {1}."
+ limit_exceeded: "Se superó el límite diario. El máximo es {0} unidades menores."
+```
+
+**`ResourceBundleMessageSource`** resuelve claves con notación de puntos y sustituye los marcadores de posición `{n}` (base cero) siguiendo la semántica de `MessageFormat`. Los códigos ausentes recurren al `default-locale`; si tampoco están allí, `get_message` lanza `KeyError`.
+
+### Usar MessageSource en un servicio
+
+**Paso 2: inyecta `MessageSource` y resuelve el locale a partir de la petición.** El servicio de abajo lee la cabecera `Accept-Language` de quien llama, escoge el paquete que coincide y renderiza el mensaje con los argumentos en tiempo de ejecución.
+
+::: listing lumen/i18n/notification_service.py | Listado 18.7 — Servicio de notificación consciente del locale
+from pyfly.container import service
+from pyfly.i18n import AcceptHeaderLocaleResolver, MessageSource
+
+
+@service
+class NotificationService:
+ """Renders user-facing messages in the caller's preferred locale."""
+
+ def __init__(
+ self,
+ messages: MessageSource,
+ locale_resolver: AcceptHeaderLocaleResolver,
+ ) -> None:
+ self._messages = messages
+ self._resolver = locale_resolver
+
+ def deposit_confirmation(
+ self,
+ request,
+ amount_minor: int,
+ wallet_id: str,
+ ) -> str:
+ locale = self._resolver.resolve_locale(request)
+ return self._messages.get_message_or_default(
+ "wallet.deposit_ok",
+ default="Deposit successful.",
+ args=(amount_minor, wallet_id),
+ locale=locale,
+ )
+:::
+
+`AcceptHeaderLocaleResolver` analiza la cabecera `Accept-Language` y devuelve el subtag primario con la `q` más alta. Usa `FixedLocaleResolver` para despliegues de un solo idioma o para pruebas. La autoconfiguración registra ambos cuando `pyfly.i18n.enabled: true`; inyecta o bien `MessageSource` (el protocolo del puerto) o bien el `ResourceBundleMessageSource` concreto: ambos funcionan.
+
+!!! tip "Ejecútalo"
+ La forma más rápida de demostrar que la búsqueda funciona es una prueba que
+ resuelve el paquete directamente, sin necesidad de un servidor HTTP. Guarda
+ el Listado 18.7a bajo `tests/` y luego ejecuta solo esta prueba:
+
+ ```bash
+ uv run --extra dev pytest tests/test_messages.py -q
+ ```
+
+ Esperado:
+
+ ```
+ 1 passed in 0.05s
+ ```
+
+ Cambia `locale="es"` por `locale="en"` y la aserción necesitaría la cadena
+ en inglés en su lugar: misma clave, paquete distinto. Ese es justo el
+ objetivo de i18n: tu código nunca cambia, solo cambia el locale resuelto.
+
+::: listing tests/test_messages.py | Listado 18.7a — Afirmar un mensaje traducido
+from pyfly.i18n.adapters.resource_bundle import ResourceBundleMessageSource
+
+
+def test_deposit_message_in_spanish() -> None:
+ messages = ResourceBundleMessageSource(base_path="i18n/", default_locale="en")
+ text = messages.get_message(
+ "wallet.deposit_ok", args=(100, "w-001"), locale="es"
+ )
+ assert text == "Se depositaron 100 unidades menores en la billetera w-001."
+:::
+
+!!! spring "Equivalencia con Spring"
+ `MessageSource`, `ResourceBundleMessageSource`,
+ `AcceptHeaderLocaleResolver` y `FixedLocaleResolver` son
+ equivalentes directos de nombre del stack i18n de Spring MVC. La API
+ difiere solo en el uso de marcadores de posición posicionales `{n}` en
+ lugar de SpEL dentro de las cadenas de mensaje.
+
+---
+
+## Actualizaciones en tiempo real con WebSocket
+
+El panel de administración de Lumen actualmente sondea en busca de cambios de saldo. Un endpoint WebSocket elimina el sondeo: el servidor empuja una actualización en el instante en que un depósito se confirma.
+
+Un **WebSocket** es una conexión bidireccional que permanece abierta. Una petición HTTP normal es de un solo disparo: el cliente pregunta, el servidor responde, la línea se cierra. Con un WebSocket la línea se mantiene activa, así que el *servidor* puede enviar datos cuando le apetezca: perfecto para actualizaciones en vivo. El esquema de URL es `ws://` (o `wss://` sobre TLS) en lugar de `http://`.
+
+::: listing lumen/web/balance_ws_controller.py | Listado 18.8 — Flujo de saldo en vivo vía WebSocket
+import asyncio
+
+from pyfly.container import rest_controller
+from pyfly.web import request_mapping
+from pyfly.websocket import WebSocketSession, websocket_mapping
+
+
+@rest_controller
+@request_mapping("/ws")
+class BalanceFeedController:
+ """Streams balance updates to connected clients."""
+
+ def __init__(self, wallet_service) -> None:
+ self._wallet = wallet_service
+ self._clients: set[WebSocketSession] = set()
+
+ @websocket_mapping("/balance/{wallet_id}")
+ async def balance_feed(self, session: WebSocketSession) -> None:
+ wallet_id = session.path_params["wallet_id"]
+ await session.accept()
+ self._clients.add(session)
+ try:
+ while True:
+ balance = await self._wallet.get_balance(wallet_id)
+ await session.send_json(
+ {"wallet_id": wallet_id, "balance_minor": balance}
+ )
+ await asyncio.sleep(1)
+ finally:
+ self._clients.discard(session)
+
+ async def on_disconnect(self, session: WebSocketSession) -> None:
+ self._clients.discard(session)
+:::
+
+**Cómo funciona.** `@websocket_mapping("/balance/{wallet_id}")` monta el endpoint en `ws:///ws/balance/{wallet_id}`. La ruta completa es la base `@request_mapping` del controlador (`/ws`) concatenada con la ruta del decorador.
+
+!!! tip "Ejecútalo"
+ Arranca la app y luego abre el flujo en vivo con cualquier cliente
+ WebSocket. Usando `websocat` (`brew install websocat`):
+
+ ```bash
+ uv run pyfly run
+ # en otra terminal:
+ websocat ws://localhost:8080/ws/balance/w-001
+ ```
+
+ Deberías ver llegar un frame JSON aproximadamente una vez por segundo,
+ empujado por el servidor sin que vuelvas a pedirlo:
+
+ ```json
+ {"wallet_id": "w-001", "balance_minor": 5000}
+ {"wallet_id": "w-001", "balance_minor": 5000}
+ ```
+
+ Deposita en `w-001` desde otra terminal y observa cómo el valor de
+ `balance_minor` salta en el siguiente frame: sin sondeo, sin refresco. Pulsa
+ `Ctrl+C` para cerrar; se ejecuta el `on_disconnect` del controlador y la
+ sesión se elimina del conjunto de difusión.
+
+`WebSocketSession` expone el ciclo de vida de la conexión:
+
+| Método | Descripción |
+|---|---|
+| `await accept(subprotocol=None)` | Completar el handshake |
+| `await send_json(data)` | Serializar y enviar un mensaje JSON |
+| `await send_text(data)` | Enviar una cadena plana |
+| `await receive_text()` | Bloquear hasta que llegue un mensaje de texto |
+| `await receive_json()` | Bloquear hasta que llegue un mensaje JSON |
+| `await close(code=1000, reason=None)` | Cerrar la conexión limpiamente |
+
+`session.path_params`, `session.query_params` y `session.headers` exponen los metadatos de la conexión. Las rutas WebSocket se descubren automáticamente junto con las rutas HTTP: no se requiere configuración adicional.
+
+El método opcional `on_disconnect` lo invoca automáticamente el registrador después de que el manejador `@websocket_mapping` retorne o el cliente cierre la conexión (solo si la conexión se aceptó antes), dando a los controladores un lugar seguro donde liberar recursos.
+
+!!! tip "Difusión (broadcasting)"
+ Mantén un `set[WebSocketSession]` en el controlador y difunde con
+ `for client in list(self._clients): await client.send_json(payload)`.
+ Como los beans de los controladores son singletons, el conjunto vive
+ durante toda la vida de la aplicación.
+
+---
+
+## Comandos de shell y runners de arranque
+
+No toda funcionalidad vive detrás de un endpoint HTTP. Los scripts de siembra de bases de datos, las migraciones de datos puntuales y los trabajos por lotes programados se expresan mejor como comandos CLI que se ejecutan dentro del mismo contenedor de DI, compartiendo servicios, configuración y repositorios con la aplicación principal.
+
+La idea clave aquí: un **comando de shell** es solo un método que se ejecuta desde la terminal pero que aún tiene acceso completo a los servicios cableados de tu aplicación. No escribes un script aparte que recree la conexión a la base de datos a mano: el comando recibe el mismo `WalletService` que usan tus controladores HTTP, porque vive dentro del mismo contenedor de DI.
+
+### @shell_component y @shell_method
+
+::: listing lumen/cli/wallet_commands.py | Listado 18.9 — Comandos de shell con DI
+from pyfly.shell import (
+ shell_argument,
+ shell_component,
+ shell_method,
+ shell_option,
+)
+
+
+@shell_component
+class WalletCommands:
+ """Operational commands for the Lumen wallet service."""
+
+ def __init__(self, wallet_service) -> None:
+ self._wallet = wallet_service
+
+ @shell_method(group="wallet", help="Deposit funds into a wallet")
+ @shell_argument("wallet_id", help="Target wallet identifier")
+ @shell_option("--amount", help="Amount in minor units (integer cents)")
+ async def deposit(
+ self, wallet_id: str, amount: int = 100
+ ) -> str:
+ result = await self._wallet.deposit(wallet_id, amount)
+ return f"New balance: {result['balance_minor']} minor units"
+
+ @shell_method(group="wallet", help="Show current balance")
+ @shell_argument("wallet_id", help="Wallet to inspect")
+ async def balance(self, wallet_id: str) -> str:
+ data = await self._wallet.get_balance(wallet_id)
+ return f"{wallet_id}: {data['balance_minor']} minor units"
+:::
+
+Habilita el shell en `pyfly.yaml`:
+
+```yaml
+pyfly:
+ shell:
+ enabled: true
+```
+
+PyFly autoconfigura un `ClickShellAdapter` y cablea cada `@shell_method` al arranque. El nombre del grupo se convierte en un subcomando:
+
+```bash
+python -m lumen wallet deposit w-001 --amount 500
+python -m lumen wallet balance w-001
+python -m lumen # sin argumentos → entra en modo REPL
+```
+
+!!! tip "Ejecútalo"
+ Deposita 500 unidades menores en un monedero directamente desde la línea de
+ comandos: el comando ejecuta tu `WalletService` real contra la base de datos
+ real:
+
+ ```bash
+ uv run python -m lumen wallet deposit w-001 --amount 500
+ ```
+
+ Salida esperada (el valor de retorno de tu método `deposit`, impreso por
+ el adaptador de shell):
+
+ ```
+ New balance: 500 minor units
+ ```
+
+ Ejecuta `uv run python -m lumen wallet balance w-001` y verás reflejado de
+ vuelta el mismo `500`: prueba de que el comando y la API HTTP hablan con el
+ mismo estado persistente, no con una copia desechable en memoria.
+
+### CommandLineRunner: tareas puntuales tras el arranque
+
+Para tareas que se ejecutan una vez al arranque —siembra, calentamiento, comprobaciones de conexión— implementa **`CommandLineRunner`**:
+
+::: listing lumen/runners/seed_runner.py | Listado 18.10 — Sembrador de base de datos tras el arranque
+from pyfly.container import service
+from pyfly.shell import CommandLineRunner
+
+
+@service
+class SeedRunner(CommandLineRunner):
+ """Seed the database with a default admin wallet on first boot."""
+
+ def __init__(self, wallet_service) -> None:
+ self._wallet = wallet_service
+
+ async def run(self, args: list[str]) -> None:
+ if "--seed" in args:
+ await self._wallet.ensure_default_wallet()
+ print("Default wallet ensured.")
+:::
+
+Cualquier bean cuya clase implemente `async def run(self, args: list[str]) -> None` satisface estructuralmente el protocolo `CommandLineRunner`. El framework lo detecta vía `isinstance()` (el protocolo es `@runtime_checkable`) después de que se dispare `ApplicationReadyEvent`, y luego lo invoca con los argumentos CLI en crudo. Usa `@order(n)` para controlar el orden de ejecución cuando coexisten varios runners.
+
+!!! tip "Ejecútalo"
+ El runner se dispara durante el arranque de la aplicación y recibe el
+ `sys.argv[1:]` del proceso, así que lanza la app a través de su punto de
+ entrada CLI con el flag añadido:
+
+ ```bash
+ uv run python -m lumen --seed
+ ```
+
+ Tras el banner y la tabla de rutas, verás la línea de confirmación del
+ runner:
+
+ ```
+ Default wallet ensured.
+ ```
+
+ Arranca sin `--seed` y la línea no aparece: la guarda `if "--seed" in args`
+ se salta el trabajo. Esa es la diferencia entre un *runner* (se ejecuta en
+ cada arranque, lo controlas tú) y un comando de shell puntual (se ejecuta
+ solo cuando invocas su nombre).
+
+!!! spring "Equivalencia con Spring"
+ `@shell_component`, `@shell_method`, `@shell_option`,
+ `@shell_argument` y `CommandLineRunner` son equivalentes
+ directos de `@ShellComponent`, `@ShellMethod`, `@ShellOption`,
+ `@ShellArgument` de Spring Shell y de la interfaz `CommandLineRunner`
+ de Spring Boot. Click reemplaza a JLine como librería de terminal,
+ pero el modelo de programación es idéntico.
+
+---
+
+## Generar un SDK a partir de la especificación OpenAPI
+
+Cuando Lumen expone una API HTTP, los servicios posteriores deberían llamarla mediante un cliente generado, no mediante llamadas `httpx` escritas a mano que se desincronizan. PyFly construye y sirve una especificación OpenAPI 3.1 automáticamente en `/openapi.json`.
+
+Una **especificación OpenAPI** es una descripción legible por máquina de tu API HTTP: cada ruta, cada parámetro, cada forma de petición y respuesta. Un **SDK** (software development kit) es la librería cliente que una herramienta genera *a partir de* esa especificación: métodos tipados que envuelven las llamadas HTTP por ti. La cadena es: tus controladores → la especificación → un cliente generado. Como cada eslabón es mecánico, el cliente nunca puede desincronizarse silenciosamente del servidor.
+
+`OpenAPIGenerator` ensambla la especificación a partir de los metadatos de ruta recopilados por `ControllerRegistrar`:
+
+- **Info**: poblada a partir de `title`, `version` y `description` pasados a `create_app()`.
+- **Paths**: una operación por cada `@get_mapping` / `@post_mapping`, etc., con parámetros inferidos a partir de las anotaciones de tipo `PathVar[T]`, `QueryParam[T]`, `Header[T]` y `Body[BaseModel]`.
+- **Schemas**: modelos de Pydantic registrados en `components.schemas` vía `model_json_schema()` y referenciados con `$ref`.
+
+Con la especificación disponible, genera un cliente Python en dos pasos: descarga la especificación y luego ejecuta el generador.
+
+**Paso 1: descarga la especificación de una instancia en ejecución.** La especificación vive en el puerto de aplicación (`8080`), junto a tus rutas de negocio.
+
+**Paso 2: ejecuta el generador de OpenAPI** para convertir ese JSON en un paquete Python instalable.
+
+```bash
+# Download the spec from a running instance
+curl http://localhost:8080/openapi.json -o lumen-spec.json
+
+# Generate a Python client package
+openapi-generator-cli generate \
+ -i lumen-spec.json \
+ -g python \
+ -o lumen-client \
+ --package-name lumen_client
+```
+
+El paquete `lumen_client` generado contiene modelos tipados y un `DefaultApi` con un método por operación. Los servicios consumidores lo añaden como dependencia y lo llaman sin saber nada de HTTP:
+
+::: listing payment/services/wallet_client.py | Listado 18.11 — Consumir el SDK de Lumen generado
+from lumen_client import ApiClient, Configuration, DefaultApi
+
+
+class WalletGateway:
+ """Typed façade over the generated Lumen client SDK."""
+
+ def __init__(self, base_url: str) -> None:
+ cfg = Configuration(host=base_url)
+ self._api = DefaultApi(ApiClient(cfg))
+
+ def get_balance(self, wallet_id: str) -> int:
+ result = self._api.get_wallet_balance(wallet_id)
+ return result.balance_minor
+:::
+
+!!! tip "Mantén la especificación versionada"
+ Incluye `lumen-spec.json` en el repositorio de Lumen y regenera los
+ paquetes cliente en CI cada vez que cambie la especificación. Los
+ equipos posteriores se fijan a una versión concreta de la
+ especificación a través de su gestor de dependencias: la misma
+ disciplina que usan los equipos Java con las versiones de artefactos
+ de Maven.
+
+---
+
+## Llevarlo a producción
+
+### Empaquetar con Docker
+
+**Contenerizar**, en términos sencillos, significa congelar tu app y todo lo que necesita para ejecutarse —Python, dependencias, tu código, tu configuración— en una única imagen que se ejecuta de forma idéntica en tu portátil, en CI y en producción. Un `Dockerfile` es la receta para construir esa imagen.
+
+`pyfly new` genera un `Dockerfile` para cada arquetipo. Para un servicio web tiene este aspecto tras el endurecimiento de producción. Léelo de arriba abajo: cada línea es un paso del build:
+
+```dockerfile
+FROM python:3.12-slim
+
+WORKDIR /app
+COPY pyproject.toml uv.lock ./
+RUN pip install uv && \
+ uv sync --no-dev --extra web --extra data-relational \
+ --extra security --extra observability
+
+COPY src/ src/
+COPY pyfly.yaml .
+
+# 8080 = application traffic; 9090 = the management port (actuator + admin).
+EXPOSE 8080 9090
+CMD ["pyfly", "run", "--host", "0.0.0.0", \
+ "--port", "8080", "--server", "granian", "--workers", "2"]
+```
+
+Recorriendo la receta: `FROM` escoge una imagen base de Python pequeña; `COPY` + `uv sync` instalan exactamente los extras de dependencias que nombras (y nada más); el segundo `COPY` añade tu fuente y tu configuración; `EXPOSE` documenta los dos puertos en los que escucha el contenedor; `CMD` es el comando que se ejecuta cuando arranca el contenedor. El flag `--port 8080` de aquí establece `pyfly.server.port` para este proceso: el puerto de gestión se queda en su valor por defecto `9090` salvo que anules `pyfly.management.server.port`.
+
+Instala solo los extras que tu servicio realmente usa: el meta-extra `full` arrastra los drivers de Kafka, RabbitMQ y MongoDB incluso cuando no necesitas ninguno de ellos.
+
+!!! tip "Ejecútalo"
+ Construye la imagen y ejecútala, mapeando ambos puertos fuera del
+ contenedor:
+
+ ```bash
+ docker build -t lumen:local .
+ docker run --rm -p 8080:8080 -p 9090:9090 lumen:local
+ ```
+
+ Luego confirma que ambos listeners responden: el puerto de negocio en
+ `8080` y el puerto de gestión en `9090`:
+
+ ```bash
+ curl http://localhost:8080/openapi.json # app: returns the spec
+ curl http://localhost:9090/actuator/health # management: {"status":"UP"}
+ ```
+
+ Dos puertos, un proceso. Esa separación es sobre la que se construye el
+ resto de esta sección.
+
+### Variables de entorno y secretos
+
+Nunca incrustes secretos en `pyfly.yaml`. PyFly resuelve marcadores de posición `${ENV_VAR}` en cualquier parte de la configuración:
+
+```yaml
+pyfly:
+ data:
+ relational:
+ url: ${DATABASE_URL}
+
+ security:
+ jwt:
+ secret: ${JWT_SECRET}
+```
+
+PyFly lee los valores reales del entorno del contenedor al arranque. En Kubernetes, respalda esas variables con un `Secret`; en Docker Compose, usa un archivo `.env` que nunca se commitea. El comando `pyfly doctor` comprueba que las herramientas requeridas están presentes, pero no valida secretos: esa responsabilidad sigue siendo tuya.
+
+### Apagado ordenado
+
+PyFly respeta el apagado ordenado por defecto. Establece `pyfly.server.graceful-timeout` (en segundos) para controlar cuánto espera el servidor a que se completen las peticiones en vuelo antes de forzar la salida:
+
+```yaml
+pyfly:
+ server:
+ graceful-timeout: 30
+```
+
+SIGTERM dispara la secuencia de apagado: el servidor deja de aceptar nuevas conexiones, `ApplicationContext.stop()` ejecuta los hooks `@pre_destroy` y `stop_all()` para los plugins, y el proceso sale limpiamente. En Kubernetes, establece `terminationGracePeriodSeconds` al menos cinco segundos por encima de `graceful-timeout`.
+
+### Selección de servidor
+
+El servidor ASGI se selecciona por prioridad en tiempo de ejecución:
+
+| Prioridad | Servidor | Extra de instalación |
+|---|---|---|
+| 1 | Granian (Rust/tokio) | `granian` |
+| 2 | Uvicorn | `web` (por defecto) |
+| 3 | Hypercorn | `hypercorn` |
+
+Para producción, prefiere Granian: ofrece aproximadamente 3× el rendimiento de Uvicorn con HTTP/2 nativo. Combínalo con uvloop en Linux para un aceleramiento adicional de 2 a 4× del bucle de eventos:
+
+```bash
+uv add "pyfly[web-fast]" # granian + uvloop in one shot
+```
+
+Fija la elección en YAML para evitar sorpresas en máquinas donde resulta que hay varios servidores instalados:
+
+```yaml
+pyfly:
+ server:
+ type: granian
+ event-loop: uvloop
+ workers: 4
+ graceful-timeout: 30
+```
+
+### El despliegue de dos puertos
+
+Este es el hecho de despliegue que más necesitas interiorizar para v26.6.110. PyFly se ejecuta en **dos puertos**, ambos dentro de un único proceso:
+
+- el **puerto de aplicación** —`pyfly.server.port`, por defecto `8080`— sirve tu API de negocio, tus flujos WebSocket, la especificación OpenAPI y las rutas del config-server;
+- el **puerto de gestión** —`pyfly.management.server.port`, por defecto `9090`— sirve el Actuator (`/actuator/*`) y el panel de administración (`/admin`).
+
+El puerto de gestión es un segundo listener en proceso, no procesos worker adicionales, así que casi no cuesta nada. Dos opciones de ajuste importan en el momento del despliegue: establece `pyfly.management.server.port` **igual** a `pyfly.server.port` para colapsar todo en un único puerto, o ponlo a **`-1`** para deshabilitar por completo los endpoints web de gestión. La anulación por entorno es `PYFLY_MANAGEMENT_SERVER_PORT`.
+
+¿Por qué separarlos? Porque te permite exponer solo `8080` a internet manteniendo las comprobaciones de salud, los scrapes de Prometheus y la consola de administración en `9090`, accesibles únicamente desde dentro de tu clúster.
+
+!!! warning "El puerto de gestión está ABIERTO por defecto"
+ A partir de v26.6.110, el puerto de gestión está **sin autenticación por
+ defecto** (el modelo `management.server.port` de Spring Boot): cualquier
+ cosa que pueda alcanzar `9090` puede leer `/actuator/*` y `/admin`. Eso es
+ intencionado: el puerto está pensado para situarse tras aislamiento de red,
+ nunca en el internet público. Si no puedes garantizar ese aislamiento,
+ aplica también los filtros de seguridad de la app al puerto de gestión:
+
+ ```yaml
+ pyfly:
+ management:
+ security:
+ enabled: true
+ ```
+
+ Con ese flag activado, la misma autenticación, las guardas de roles y las
+ reglas CSRF que protegen tu API de negocio también protegen `9090`.
+
+### Endpoints de salud
+
+PyFly expone endpoints de actuator al estilo de Spring Boot de fábrica. Viven en el **puerto de gestión** (`9090`):
+
+| Endpoint | Propósito |
+|---|---|
+| `GET /actuator/health` | Salud agregada (UP / DOWN) |
+| `GET /actuator/health/liveness` | Sonda de liveness de Kubernetes |
+| `GET /actuator/health/readiness` | Sonda de readiness de Kubernetes |
+| `GET /actuator/metrics` | Desglose por métrica (p. ej. `/actuator/metrics/http.server.requests`) |
+| `GET /actuator/prometheus` | Endpoint de scrape de Prometheus |
+
+Solo `health` e `info` se exponen sobre HTTP por defecto (el valor por defecto seguro de Spring Boot). Para publicar las métricas y el endpoint de scrape de Prometheus, añádelos a la lista de exposición en `pyfly.yaml`:
+
+```yaml
+pyfly:
+ management:
+ endpoints:
+ web:
+ exposure:
+ include: health,info,metrics,prometheus
+ endpoint:
+ health:
+ show-details: when-authorized
+```
+
+!!! tip "Ejecútalo"
+ Golpea las sondas en el puerto de gestión: responden de inmediato porque
+ ese puerto está abierto por defecto:
+
+ ```bash
+ curl http://localhost:9090/actuator/health
+ curl http://localhost:9090/actuator/health/readiness
+ ```
+
+ Esperado: un objeto de estado JSON que el orquestador puede analizar:
+
+ ```json
+ {"status": "UP"}
+ ```
+
+ Una comprobación de readiness que falla (una base de datos aún
+ calentándose, por ejemplo) devuelve `{"status": "DOWN"}` con HTTP `503`,
+ que es exactamente lo que Kubernetes necesita para retener el tráfico hasta
+ que el pod esté listo.
+
+Luego conecta tu deployment de Kubernetes: fíjate en que cada sonda y cada scrape apuntan al **puerto de gestión** `9090`, no a `8080`:
+
+```yaml
+livenessProbe:
+ httpGet:
+ path: /actuator/health/liveness
+ port: 9090
+ initialDelaySeconds: 10
+ periodSeconds: 15
+readinessProbe:
+ httpGet:
+ path: /actuator/health/readiness
+ port: 9090
+ initialDelaySeconds: 5
+ periodSeconds: 10
+```
+
+!!! spring "Equivalencia con Spring"
+ La división de dos puertos es un port directo del `management.server.port`
+ de Spring Boot: tráfico de la app en `server.port`, actuator y la UI de
+ gestión en un `management.server.port` dedicado. La postura de abierto por
+ defecto, la convención de `-1` para deshabilitar y `management.security.enabled`
+ para bloquearlo reflejan todos el comportamiento de Spring Boot.
+
+!!! note "Sondas personalizadas desde el HealthAggregator en vivo"
+ Nuevo en v26.6.110, el `HealthAggregator` en vivo es accesible en
+ `app.state.pyfly_health_aggregator` (solo adaptador Starlette). Registra un
+ indicador de readiness adicional después de `create_app()` —por ejemplo una
+ comprobación que haga ping a un servicio posterior— y aparece en
+ `/actuator/health` independientemente de si el actuator se ejecuta en el
+ puerto de gestión compartido o en el separado.
+
+**Lo que acaba de ocurrir.** Ahora tienes la forma completa de un despliegue de
+PyFly: un contenedor, dos puertos (`8080` para usuarios, `9090` para
+operaciones), secretos inyectados como variables de entorno, un servidor Granian
+ajustado con workers explícitos, una ventana de apagado ordenado que drena las
+peticiones en vuelo y sondas de Kubernetes conectadas al puerto de gestión. La
+lista de comprobación de abajo es la misma imagen en forma de lista que puedes
+pegar en una plantilla de pull request.
+
+### La lista de comprobación de producción
+
+- [ ] Todos los secretos son variables de entorno: ninguno está en
+ `pyfly.yaml` ni en el control de versiones.
+- [ ] La imagen Docker instala solo los extras que el servicio usa.
+- [ ] El servidor está fijado a Granian + uvloop; `workers` está
+ establecido explícitamente (no dejado en `1` para máquinas
+ multinúcleo).
+- [ ] `graceful-timeout` es de al menos 15 s; el
+ `terminationGracePeriodSeconds` de Kubernetes es al menos 5 s más.
+- [ ] Las sondas de liveness y readiness apuntan al **puerto de gestión**
+ (`9090`), no al puerto de aplicación, y están probadas.
+- [ ] `/actuator/health` (en `9090`) devuelve UP antes de que se envíe tráfico.
+- [ ] El puerto de gestión está aislado a nivel de red, o
+ `pyfly.management.security.enabled: true` está establecido: está abierto
+ por defecto.
+- [ ] El endpoint de scrape de Prometheus (`/actuator/prometheus` en `9090`)
+ está añadido a la lista de exposición y lo scrapea el stack de
+ monitorización.
+- [ ] El logging estructurado está habilitado (`pyfly[observability]`) y el
+ nivel de log es `INFO` en producción, no `DEBUG`.
+- [ ] El exportador de OpenTelemetry apunta al colector de producción.
+- [ ] Las migraciones de base de datos (`pyfly db upgrade`) se ejecutan en un
+ paso previo al despliegue, no al arranque de la aplicación.
+- [ ] La especificación OpenAPI generada está versionada en CI y los paquetes
+ SDK posteriores se fijan a una revisión concreta de la especificación.
+- [ ] `pyfly doctor` pasa en cada máquina de desarrollo y en cada runner de CI.
+
+---
+
+## Lo que construiste {.recap}
+
+Hace diecisiete capítulos escribiste `@pyfly_application` y viste cómo el contenedor de DI cableaba tu primer `@service`. Hoy ese mismo contenedor impulsa una plataforma de monedero en producción. Esto es lo que construiste por el camino.
+
+**Capítulos 1–3** te dieron los cimientos: un contenedor de DI de primera clase, configuración flexible (YAML, env, perfiles, expresiones SpEL) y una capa HTTP completa con request mapping, filtros, negociación de contenido y una capa de serialización JSON que puedes reemplazar sin tocar un solo controlador.
+
+**Capítulos 4–6** introdujeron la persistencia. Mapeaste entidades con SQLAlchemy, gestionaste la evolución del esquema con Alembic y estructuraste el dominio con patrones tácticos de DDD: agregados, objetos de valor y repositorios que mantienen la lógica de negocio fuera de la infraestructura.
+
+**Capítulos 7–9** dieron vida a la arquitectura. CQRS separó las lecturas de las escrituras a nivel del manejador. EDA dejó que los servicios reaccionaran a eventos sin sondear. El event sourcing convirtió cada cambio de estado en un hecho de primera clase: reproducible, auditable y el cimiento de las proyecciones.
+
+**Capítulos 10–12** enseñaron a Lumen a salir de su propio proceso. Clientes HTTP resilientes llamaban a servicios posteriores sin fallos en cascada. Las sagas orquestaban transacciones de múltiples pasos a través de las fronteras de los servicios con compensación automática cuando algún paso salía mal.
+
+**Capítulos 13–15** endurecieron la plataforma. La caché redujo la presión sobre la base de datos. Limitadores de tasa, bulkheads, tiempos de espera y cortacircuitos (circuit breakers) convirtieron cada dependencia en un radio de impacto controlado. Las trazas distribuidas, el logging estructurado y un panel de administración en vivo te dieron ojos dentro del sistema en cada capa.
+
+**Capítulos 16–17** cerraron el bucle de retroalimentación. Un conjunto de pruebas estructurado —pruebas unitarias, de integración y de persistencia respaldadas por Testcontainers— hizo seguro cambiar la plataforma. Tareas programadas, notificaciones push, webhooks y callbacks dejaron que Lumen llegara al mundo según su propio calendario.
+
+**Capítulo 18** te mostró lo que hay más allá del núcleo: un sistema de plugins para la extensión abierta, un motor de reglas YAML para la lógica propiedad del negocio, un Config Server para la configuración de toda la flota, i18n para audiencias globales, WebSocket para UX en tiempo real, un módulo Shell para herramientas operativas, una especificación OpenAPI que genera SDKs cliente tipados automáticamente y los hábitos de producción que mantienen todo eso en marcha, empaquetado como un único contenedor que escucha en dos puertos, `8080` para usuarios y `9090` para operaciones.
+
+PyFly no es magia. Toda abstracción de este libro tiene un coste, y ahora entiendes cuál es ese coste: un contenedor de DI que arranca en milisegundos pero te obliga a pensar en los ámbitos de los beans; un servidor HTTP asíncrono que maneja miles de conexiones concurrentes pero te obliga a evitar llamadas bloqueantes; un motor de sagas que sobrevive a fallos parciales pero te obliga a escribir transacciones de compensación.
+
+Entender el coste es lo que separa a un practicante de un lector que se limita a copiar patrones. Ahora eres un practicante.
+
+---
+
+## Pruébalo tú mismo {.exercises}
+
+1. **Añade un plugin personalizado.** Implementa un `AuditPlugin` que aporte una extensión a un punto de extensión `"audit-sinks"`. La clase de extensión debe implementar una interfaz `AuditSink` y escribir cada evento en un archivo. En una prueba, llama a `PluginManager.registry.get("audit-sinks")` y afirma que tu extensión se devuelve con el `name` esperado.
+
+2. **Despliega un cambio de reglas sin redesplegar.** Almacena `transaction_rules.yaml` en el Config Server (`pyfly.config-server.enabled: true`). Escribe un `RiskService` que obtenga el YAML vía `ConfigClient` en cada llamada a `assess()` (o que lo cachee con un TTL corto). Actualiza el umbral `value` a través de la ruta `POST /{app}/{profile}` y verifica que `assess()` recoge el nuevo valor sin reiniciar el servicio.
+
+3. **Localiza un mensaje de rechazo.** Añade `wallet.limit_exceeded` a `i18n/messages_en.yaml` e `i18n/messages_es.yaml`. Conecta un `NotificationService` que lea el locale de la cabecera `Accept-Language` y devuelva la cadena correcta. Escribe dos pruebas —una con `Accept-Language: en`, otra con `Accept-Language: es`— y afirma que cada una devuelve el mensaje adecuado.
+
+---
+
+Lumen está lista para producción. Para lo que viene a continuación —nuevos módulos, plugins de la comunidad y notas de versión— visita la documentación del framework en [github.com/fireflyframework/fireflyframework-pyfly](https://github.com/fireflyframework/fireflyframework-pyfly). Cada concepto de este libro vive en ese repositorio; el código fuente es la referencia definitiva.
diff --git a/book/manuscript-es/90-appendix-a-spring.md b/book/manuscript-es/90-appendix-a-spring.md
new file mode 100644
index 00000000..bb294854
--- /dev/null
+++ b/book/manuscript-es/90-appendix-a-spring.md
@@ -0,0 +1,375 @@
+Apéndice A
+
+# Chuleta Spring Boot → PyFly {.chtitle}
+
+Si has puesto en producción servicios con Spring Boot, los conceptos de PyFly te resultarán inmediatamente familiares: estereotipos, inyección por constructor, factorías `@configuration` + `@bean`, vinculación tipada de configuración, consultas derivadas, orquestación de sagas — están todos aquí. Lo que cambia es la sintaxis (decoradores de Python en lugar de anotaciones de Java), el modelo de ejecución (`async/await` nativo en lugar de Project Reactor o hilos de servlet) y un puñado de decisiones de diseño deliberadas para encajar con el Python idiomático. Esta chuleta asocia cada concepto de Spring Boot que ya conoces con su equivalente en PyFly, de modo que puedas empezar a leer y escribir código PyFly sin reaprender la arquitectura desde cero.
+
+---
+
+## Arranque de la aplicación y estereotipos
+
+| Spring Boot | PyFly | Notas |
+|---|---|---|
+| `@SpringBootApplication` | `@pyfly_application` | Combina `@EnableAutoConfiguration` + `@ComponentScan`. `scan_packages` sustituye al escaneo del classpath — enumera los paquetes explícitamente. |
+| `SpringApplication.run(...)` | `PyFlyApplication(App); await app.startup()` | El punto de entrada es asíncrono. |
+| `@Component` | `@component` | Bean singleton genérico gestionado. |
+| `@Service` | `@service` | Capa de lógica de negocio. |
+| `@Repository` | `@repository` | Capa de acceso a datos. |
+| `@RestController` | `@rest_controller` | Clase de endpoint de API. No hay `@Controller` (no se renderizan vistas). |
+| `@Configuration` | `@configuration` | Clase factoría de beans. |
+| `@Bean` | `@bean` | Método factoría dentro de una clase `@configuration`. La anotación del tipo de retorno es el tipo registrado del bean. |
+| `@Primary` | `@primary` o `@bean(primary=True)` | Opción por defecto cuando existen varios candidatos. |
+| `@Order(N)` | `@order(N)` | Ordenación del ciclo de vida y de la inyección. |
+| `@Lazy` | `@lazy` | El bean no se crea hasta su primera resolución. |
+
+---
+
+## Inyección de dependencias
+
+| Spring Boot | PyFly | Notas |
+|---|---|---|
+| Constructor `@Autowired` (implícito en el Spring moderno) | Constructor normal con parámetros tipados | El contenedor lee las anotaciones de tipo de `__init__` automáticamente. |
+| Campo `@Autowired` | `field: T = Autowired()` | `Autowired(required=False)` para campos opcionales. |
+| `@Qualifier("name")` | `Annotated[T, Qualifier("name")]` | El `Annotated` de Python transporta el cualificador sin perder el tipo base. |
+| Inyección de `Optional` | Parámetro `Optional[T]` | Se resuelve a `None` cuando no hay ningún bean registrado. |
+| Inyección de `List` | Parámetro `list[T]` | Recopila todas las implementaciones registradas de `T`. |
+| Inyección de `Map` | Parámetro `dict[str, T]` | `{nombre-bean: bean}` para cada bean con nombre de tipo `T`. |
+| Inyección genérica `Repository` | Parámetro `Repository[User, int]` | El contenedor casa por los argumentos de tipo genérico y respeta `@primary` para resolver empates. |
+| `ObjectFactory` / `Provider` | `Provider[T]` | Resolución diferida; cada `.get()` vuelve a resolver — seguro para beans `TRANSIENT`. |
+
+!!! tip "Prefiere la inyección por constructor"
+ La inyección por constructor mantiene las dependencias visibles en la firma de la clase, evita errores por dependencias ausentes en el arranque en lugar de en tiempo de ejecución, y te permite escribir pruebas unitarias en Python puro sin contenedor: `svc = WalletService(repo=MockRepo(), events=MockEvents())`.
+
+---
+
+## Condiciones y autoconfiguración
+
+| Spring Boot | PyFly | Notas |
+|---|---|---|
+| `@ConditionalOnProperty` | `@conditional_on_property` | Registra cuando una clave de configuración es igual a un valor concreto. |
+| `@ConditionalOnClass` | `@conditional_on_class("module")` | Registra cuando un módulo de Python es importable. |
+| `@ConditionalOnMissingBean` | `@conditional_on_missing_bean(T)` | Registra cuando aún no existe ningún bean de tipo `T`. |
+| `@ConditionalOnBean` | `@conditional_on_bean(T)` | Registra solo si hay presente un bean de tipo `T`. |
+| `@ConditionalOnSingleCandidate` | `@conditional_on_single_candidate(T)` | Exactamente un candidato, o uno marcado como `@primary`. |
+| `@ConditionalOnWebApplication` | `@conditional_on_web_application()` | Pila web (Starlette/FastAPI) presente. |
+| `@ConditionalOnResource` | `@conditional_on_resource(path)` | Existe una ruta del sistema de archivos. |
+| `@ConditionalOnExpression` | `@conditional_on_expression("#{...}")` | Expresión tipo SpEL ligera — admite `${key:default}` + aritmética, comparación y booleanos. Analizada como AST, sin `eval`. |
+
+---
+
+## Hooks del ciclo de vida y ámbitos
+
+| Spring Boot | PyFly | Notas |
+|---|---|---|
+| `@PostConstruct` | `@post_construct` | Se invoca después de la inyección de dependencias; puede ser `async def`. |
+| `@PreDestroy` | `@pre_destroy` | Se invoca en el apagado ordenado; puede ser `async def`. |
+| Ámbito por defecto (singleton) | Por defecto (singleton) | Una instancia por aplicación. |
+| `@SessionScope` | `@component(scope=Scope.SESSION)` | Una instancia por `HttpSession`. |
+| SPI de `Scope` personalizado | `Container.register_scope(name, handler)` | Implementa el protocolo `ScopeHandler`. |
+| `@RefreshScope` (Spring Cloud) | `@refresh_scope` | Se descarta y se reconstruye al recibir `POST /actuator/refresh`. |
+| `ContextRefresher.refresh()` | `ContextRefresher.refresh()` (inyectable) | Descarta los beans de ámbito refresh, reinicia `@config_properties` y devuelve las claves modificadas. |
+| `ApplicationEventPublisher` | `ApplicationEventPublisher` (inyectable) | `await publisher.publish(event)`. |
+| `@EventListener` | `@app_event_listener` | Despacho por `isinstance`; se permiten listeners síncronos. |
+
+---
+
+## Configuración y perfiles
+
+| Spring Boot | PyFly | Notas |
+|---|---|---|
+| `application.yml` | `pyfly.yaml` | Misma estructura jerárquica. |
+| `application-{profile}.yml` | `pyfly-{profile}.yaml` | Superposiciones por perfil. |
+| `spring.profiles.active=dev` | `PYFLY_PROFILES_ACTIVE=dev` (variable de entorno) o `pyfly.profiles.active: dev` en `pyfly.yaml` | La activación es idéntica en el orden de prioridad. |
+| `@ConfigurationProperties(prefix=…)` | `@config_properties(prefix=…)` sobre un `@dataclass` (`from pyfly.core import config_properties`) | Respaldado por Pydantic: validado y congelado en el arranque. |
+| `@Value("${key}")` | `field: str = Value("${key}")` (`from pyfly.core import Value`) | Lanza una excepción si falta la clave. |
+| `@Value("${key:default}")` | `field: str = Value("${key:default}")` | Valor por defecto tras los dos puntos. |
+| `@Value("#{expr}")` SpEL | `Value("#{...}")` SpEL ligero | Aritmética, comparación, booleanos, sustitución `${...}` y mapeo `env`. Inyección por constructor: `Annotated[bool, Value("#{...}")]`. |
+| `@Bean @Profile("dev")` | `@bean(profile="dev")` | Expresión de perfil (`& \| ! ()`) sobre cualquier `@bean`. |
+| `@Profile("prod & cloud")` booleano | `profile="prod & cloud"` | Operadores de Spring Boot 2.4+; la antigua forma de OR con comas sigue funcionando. |
+| `spring.application.name` | `pyfly.app.name` | Clave del nombre de la aplicación en `pyfly.yaml`. |
+
+Prioridad de las fuentes de propiedades (de menor → mayor):
+
+1. `pyfly-defaults.yaml` (valores integrados del framework)
+2. `pyfly.yaml` (valores por defecto de la aplicación)
+3. `pyfly-{profile}.yaml` (superposiciones por perfil)
+4. Variables de entorno (en tiempo de ejecución, máxima prioridad)
+
+Esto es idéntico al orden de las fuentes de propiedades de Spring Boot.
+
+---
+
+## Capa web
+
+Imports: `from pyfly.web import (Body, PathVar, QueryParam, Valid,`
+` get_mapping, post_mapping, put_mapping, delete_mapping, patch_mapping,`
+` request_mapping)`. Estereotipos: `from pyfly.container import rest_controller,`
+` service, repository, component, configuration`. 404: `from pyfly.kernel`
+` import ResourceNotFoundException`.
+
+| Spring Boot | PyFly | Notas |
+|---|---|---|
+| `@RestController` | `@rest_controller` | |
+| `@RequestMapping("/path")` | `@request_mapping("/path")` | Prefijo a nivel de clase. |
+| `@GetMapping` | `@get_mapping` | Todos los métodos manejadores son `async def`. |
+| `@PostMapping` | `@post_mapping` | |
+| `@PutMapping` | `@put_mapping` | |
+| `@DeleteMapping` | `@delete_mapping` | |
+| `@PatchMapping` | `@patch_mapping` | |
+| `@PathVariable Long id` | Parámetro `id: PathVar[int]` | Anotación de tipo obligatoria; casa por nombre. |
+| `@RequestParam(defaultValue="0") int page` | `page: QueryParam[int] = 0` | El valor por defecto de Python sustituye a `defaultValue`. |
+| `@RequestBody @Valid T body` | `body: Valid[Body[T]]` | Deserialización Pydantic + validación combinadas. |
+| `@RequestHeader("X-Token") String t` | `t: Header[str]` | |
+| `@ResponseStatus(HttpStatus.CREATED)` | `@post_mapping("/", status_code=201)` | Código de estado en el decorador del mapeo. |
+| `@ControllerAdvice` + `@ExceptionHandler` | `@exception_handler` o jerarquía de excepciones integrada | `ResourceNotFoundException` → 404, `ValidationException` → 422, etc. |
+| `spring.mvc.problemdetails.enabled` | `pyfly.web.problem-details.enabled: true` | Respuestas RFC 7807 `application/problem+json`. |
+
+### JSON y negociación de contenido
+
+| Spring Boot | PyFly | Notas |
+|---|---|---|
+| `spring.jackson.property-naming-strategy` | `pyfly.web.json.property-naming-strategy` | `as-is` (por defecto) o `camelCase`. |
+| `spring.jackson.default-property-inclusion: non_null` | `pyfly.web.json.exclude-none: true` | |
+| `ObjectMapper` de Jackson | `PyFlyJsonSerializer` | Frontera central de serialización. |
+| `Module` de Jackson / serializador personalizado | `JsonSerializers.register(Type, encode=fn)` | Codificadores para tipos no Pydantic. |
+| `@JsonNaming(CamelCase…)` | Clase base `CamelModel` | Modelo camelCase opcional — `order_id` se serializa como `orderId`. |
+| `HttpMessageConverter` | `MessageConverter` / `MessageConverterRegistry` | Integrados: JSON (primero) y luego XML; añade conversores personalizados con `registry.add(...)`. |
+
+---
+
+## Acceso a datos
+
+Imports: `from pyfly.data.relational.sqlalchemy import (Repository, BaseEntity, Base,`
+` Specification, transactional, Propagation, Isolation)`
+`from pyfly.data import Page, Pageable, Sort`
+`from pyfly.data.query import query`
+`from pyfly.container import repository`
+
+### Repositorios
+
+| Spring Boot | PyFly | Notas |
+|---|---|---|
+| `JpaRepository` / `CrudRepository` | `Repository[E, ID]` | `from pyfly.data.relational.sqlalchemy import Repository`; decora con `@repository`. Crea una subclase con parámetros de tipo concretos; el `AsyncSession` se inyecta automáticamente en el arranque. |
+| `@Repository interface WalletRepo extends JpaRepository<…>` | `@repository class WalletRepository(Repository[WalletEntity, str])` | Clase, no interfaz; el cuerpo solo contiene esbozos de consultas derivadas y métodos personalizados. |
+| `findByOwnerId(String id)` | `async def find_by_owner_id(self, owner_id: str) -> list[WalletEntity]: ...` | El cuerpo esbozado `...` desencadena la compilación por parte de `RepositoryBeanPostProcessor` en el arranque. Prefijos: `find_by_`, `count_by_`, `exists_by_`, `delete_by_`. |
+| `@Query("SELECT u FROM User u WHERE …")` | `@query("SELECT u FROM User u WHERE …")` (tipo JPQL) o `@query("SELECT …", native=True)` (SQL en bruto) | `from pyfly.data.query import query`. Los parámetros usan la sintaxis `:name`. |
+| `Specification` | `Specification(lambda root, q: q.where(root.status == "ACTIVE"))` | Compón con `&` / `\|` / `~`; ejecuta con `repo.find_all_by_spec(spec)` o `repo.find_all_by_spec_paged(spec, pageable)`. |
+
+### Entidades
+
+| Spring Boot | PyFly | Notas |
+|---|---|---|
+| `@Entity class Order` | `class Order(Base)` | `from pyfly.data.relational.sqlalchemy import Base`. Registra la tabla en `Base.metadata`. |
+| `@Entity` + PK UUID subrogada + columnas de auditoría | `class Order(BaseEntity)` | `from pyfly.data.relational.sqlalchemy import BaseEntity`. Hereda `id: UUID`, `created_at`, `updated_at`, `created_by`, `updated_by` — todas mapeadas como `Mapped`/`mapped_column` de SQLAlchemy 2.0. |
+| `@Column` / `@Id` | `id: Mapped[str] = mapped_column(String(64), primary_key=True)` | Columnas tipadas de SQLAlchemy 2.0. `Base` (sin auditoría) deja que la entidad sea dueña de su propio tipo de PK, como hace `WalletEntity` de Lumen con un id de tipo `str`. |
+| `@SoftDelete` (Hibernate 6) | `SoftDeleteMixin` + `SoftDeleteRepository` | `from pyfly.data.relational.sqlalchemy import SoftDeleteMixin`. Añade `deleted_at`; el repositorio lo filtra automáticamente. |
+| Bloqueo optimista `@Version` | `VersionedMixin` | Añade una columna `version: int`; SQLAlchemy lanza `StaleDataError` en caso de conflicto. |
+
+### Paginación y ordenación
+
+| Spring Boot | PyFly | Notas |
+|---|---|---|
+| `Pageable` / `PageRequest.of(page, size, Sort.by(…).descending())` | `Pageable.of(page, size, Sort.by("created_at").descending())` | `from pyfly.data import Pageable, Sort`. `Sort.by(*fields)` devuelve orden ascendente; `.descending()` lo invierte todo. |
+| `Page` | `Page[T]` | `from pyfly.data import Page`. Atributos: `.items`, `.total`, `.page`, `.size`, `.total_pages`, `.has_next`, `.has_previous`. `.map(fn)` transforma los elementos preservando los metadatos. |
+| `page.getContent()` / `page.getTotalElements()` | `page.items` / `page.total` | Nomenclatura de Python; `.total_pages` se deriva como `ceil(total / size)`. |
+| `repo.findAll(pageable)` | `await repo.find_all(pageable)` | Devuelve `Page[T]`. |
+| `repo.findAll(spec, pageable)` | `await repo.find_all_by_spec_paged(spec, pageable)` | Aplica WHERE, ORDER BY y LIMIT/OFFSET en una sola llamada. |
+
+### Transacciones y `save`
+
+| Spring Boot | PyFly | Notas |
+|---|---|---|
+| `@Transactional` | `@transactional()` | `from pyfly.data.relational.sqlalchemy import transactional`. Resuelve `_session_factory` a partir de `self`, parchea las instancias de `Repository` inyectadas, confirma en caso de éxito y revierte ante una excepción. |
+| `@Transactional(propagation = REQUIRES_NEW)` | `@transactional(propagation=Propagation.REQUIRES_NEW)` | Enum `Propagation` completo: `REQUIRED`, `REQUIRES_NEW`, `SUPPORTS`, `NOT_SUPPORTED`, `NEVER`, `MANDATORY`. |
+| `@Transactional(isolation = READ_COMMITTED)` | `@transactional(isolation=Isolation.READ_COMMITTED)` | El enum `Isolation` completo refleja los niveles de JDBC. |
+| `@Transactional(readOnly = true)` | `@transactional(read_only=True)` | Enruta a la réplica de lectura a través de `RoutingSessionFactory` y marca la sesión como `read_only`. |
+| `repo.save(entity)` | `await repo.save(entity)` | Invoca `session.add` + `flush` + `refresh` — vuelca pero **no** confirma; el `@transactional` que lo rodea confirma. |
+| `session.merge(entity)` (upsert) | `await repo.upsert(entity)` *(extiéndelo)* o `session.merge(entity)` + flush | No hay `upsert` integrado — añádelo como método en tu repositorio (como hace `WalletRepository` de Lumen). `session.merge` gestiona tanto INSERT como UPDATE en función de la PK. |
+| `AbstractRoutingDataSource` | `RoutingSessionFactory` | `factory.primary()` / `factory.replica()` para forzar un lado. |
+| Varios beans `DataSource` | `NamedDataSources` | Configuración: `pyfly.data.relational.datasources.`; inyecta `NamedDataSources` y llama a `.get("")`. |
+
+### Proyecciones y mapeador
+
+| Spring Boot | PyFly | Notas |
+|---|---|---|
+| Proyección por interfaz `interface OrderSummary { … }` | `@projection class OrderSummary: id: str; status: str` | `from pyfly.data.projection import projection`. Un dataclass concreto (no un `Protocol`), no un proxy de la JDK; se registra con `mapper.register_projection(src, proj)`. |
+| `repo.findAll(cls, Projection.class)` | `mapper.project(entity, OrderSummary)` | `from pyfly.data.mapper import Mapper`. |
+| `@Mapper` de MapStruct | `Mapper` + decorador `@mapping` | Reflexión en tiempo de ejecución; sin generación de código. `mapper.map(obj, TargetDTO)`, `mapper.map_list(...)`. |
+
+### Migraciones
+
+| Spring Boot | PyFly | Notas |
+|---|---|---|
+| Migraciones de Flyway | `pyfly.data.migrations.*` | Mismo concepto: scripts SQL versionados que se ejecutan en el arranque. |
+
+---
+
+## Caché
+
+| Spring Boot | PyFly | Notas |
+|---|---|---|
+| `@Cacheable(value="cache", key="#id")` | `@cacheable(backend=cache, key="item:{id}")` | Sintaxis de plantilla `{param}` en la clave. |
+| `@Cacheable(condition=…, unless=…)` | `@cacheable(condition=…, unless=…)` | `condition` omite según los argumentos; `unless` evita almacenar según el resultado. |
+| `@CacheEvict` | `@cache_evict(backend=cache, key="item:{id}")` | |
+| `@CachePut` | `@cache_put(backend=cache, key="item:{id}")` | Actualiza la caché tras la mutación. |
+| `CacheManager` (autoconfigurado) | `InMemoryCache` / `RedisCacheAdapter` (autoconfigurados) | Se selecciona Redis cuando el extra `redis` está instalado; recae en memoria en caso contrario. |
+
+---
+
+## Mensajería y eventos
+
+| Spring Boot | PyFly | Notas |
+|---|---|---|
+| `@KafkaListener(topics=…, groupId=…)` | `@message_listener(topic=…, group_id=…)` | El manejador es `async def`. |
+| `KafkaTemplate.send(topic, event)` | `await publisher.publish(dest, event_type, payload)` | Puerto `EventPublisher` (`from pyfly.eda import EventPublisher`); cambia de adaptador mediante configuración. |
+| `@RetryableTopic` / DLT | `@message_listener(retries=3, retry_delay=1.0, dead_letter_topic="…")` | Reintento con retroceso lineal; los mensajes agotados se enrutan a la DLQ con cabeceras `x-original-topic` / `x-exception`. |
+| `ApplicationEvent` | `EventEnvelope` | Contenedor de eventos de dominio. |
+| `@EventListener` | `@event_listener(event_types=["TypeName"])` | Manejador EDA en proceso; `event_type` es la cadena con el nombre de la clase. No existe `@domain_event_listener`. |
+| `ApplicationEventPublisher` | `ApplicationEventPublisher` (inyectable) | `await publisher.publish(event)` para eventos de aplicación al estilo Spring. |
+
+!!! tip "Mensajería frente a EDA"
+ PyFly separa la **mensajería por broker** (`pyfly.messaging` — transporte Kafka/RabbitMQ) de los **eventos de dominio** (`pyfly.eda` — `EventEnvelope` + `EventBus`). Empieza con `InMemoryEventBus` dentro de un monolito; cambia a un adaptador de Kafka más adelante modificando una sola clave de configuración, no tus manejadores.
+
+---
+
+## Seguridad
+
+| Spring Boot | PyFly | Notas |
+|---|---|---|
+| `SecurityAutoConfiguration` | `JwtAutoConfiguration` + `PasswordEncoderAutoConfiguration` | Dividido por dependencia opcional. |
+| Cadena de filtros JWT | `JwtAutoConfiguration` autocableado | Actívalo con `pyfly.security.jwt.enabled: true`. |
+| `@PreAuthorize("hasRole('ADMIN')")` | `@pre_authorize("hasRole('ADMIN')")` | Mismo subconjunto de SpEL: `hasRole`, `hasAnyRole`, `hasAuthority`, `isAuthenticated`, `permitAll`, `denyAll`, `#param`, `and`/`or`/`not`. Recorrido por AST, sin `eval`. |
+| `@PostAuthorize("returnObject.owner == principal")` | `@post_authorize("returnObject.owner == principal")` | `returnObject` se vincula al valor de retorno del método. |
+| Bean `RoleHierarchy` | `RoleHierarchy.from_string("ADMIN > USER")` + `set_role_hierarchy(...)` | `expand(roles)` es consultado por `hasRole`/`hasAnyRole`. |
+| `ClientRegistration` (OAuth2 con código de autorización) | `ClientRegistration(...)` | PKCE: añade `use_pkce=True` — genera `code_verifier`/`code_challenge` (S256) automáticamente. |
+| `maximumSessions` / `SessionRegistry` | `SessionConcurrencyController` + `SessionRegistry` | Limita las sesiones concurrentes por principal (`evict-oldest` o `reject-new`). Actívalo: `pyfly.session.concurrency.enabled: true`. |
+
+---
+
+## Programación
+
+| Spring Boot | PyFly | Notas |
+|---|---|---|
+| `@Scheduled(fixedRate = 5000)` | `@scheduled(fixed_rate=5.0)` | Spring usa milisegundos; PyFly usa **segundos**. |
+| `@Scheduled(fixedDelay = 1000)` | `@scheduled(fixed_delay=1.0)` | |
+| `@Scheduled(cron = "0 0 2 * * ?")` | `@scheduled(cron="0 2 * * *")` | Spring: 6 campos (segundos primero). PyFly: 5 campos estándar; también acepta la forma de 6 campos de Spring y `?`. |
+| `@Scheduled(cron=…, zone=…)` | `@scheduled(cron=…, zone="America/New_York")` | Zona horaria IANA; se ignora para `fixed_rate`/`fixed_delay`. |
+| ShedLock / `@SchedulerLock` | `@scheduled(lock=True, lock_ttl=30)` + bean `DistributedLock` | Omite un tick cuando el bloqueo está retenido en otro lugar. Por defecto usa el `LocalLock` en proceso; registra un `DistributedLock` de Redis para un disparo único entre procesos. |
+| `@EnableScheduling` | `SchedulingAutoConfiguration` | Se activa automáticamente cuando `croniter` está instalado. No hace falta `@Enable…` explícito. |
+
+---
+
+## Resiliencia
+
+`from pyfly.resilience import retry, CircuitBreaker, circuit_breaker,`
+` RateLimiter, rate_limiter, Bulkhead, bulkhead, time_limiter, fallback`
+
+| Spring (Resilience4j) | PyFly | Notas |
+|---|---|---|
+| `@Retry` | `@retry(max_attempts=3, *, delay=0.1, backoff=2.0, jitter=0.1, exceptions=(IOError,))` | `delay`/`backoff`/`jitter` son solo por palabra clave. `jitter` es una fracción float en `[0,1]`. |
+| `@CircuitBreaker` | `breaker = CircuitBreaker(...); @circuit_breaker(breaker)` | Pasa una *instancia* de `CircuitBreaker`. Basado en conteo (`failure_threshold`) o en tasa (`failure_rate_threshold` + `window_size`). |
+| `@RateLimiter` | `limiter = RateLimiter(max_tokens=100, refill_rate=100/60); @rate_limiter(limiter)` | Cubo de tokens; pasa una *instancia*. |
+| `@Bulkhead` | `bh = Bulkhead(max_concurrent=10); @bulkhead(bh)` | Límite de concurrencia; pasa una *instancia*. |
+| `@TimeLimiter` | `@time_limiter(timeout=timedelta(seconds=2))` | Lanza `asyncio.TimeoutError` al superarse. |
+| `fallbackMethod` | `@fallback(fallback_method=fn)` o `@fallback(fallback_value=v)` | Valor de reserva estático o invocable. |
+
+---
+
+## AOP
+
+| Spring Boot | PyFly | Notas |
+|---|---|---|
+| `@Aspect` + `@Component` | `@aspect` + `@component` | |
+| `@Before("execution(…)")` | `@before("execution(…)")` | |
+| `@After` | `@after` | Se ejecuta siempre (como `finally`). |
+| `@Around` | `@around` | Llama a `await join_point.proceed()` para continuar. |
+| `@AfterReturning` | `@after_returning` | |
+| `@AfterThrowing` | `@after_throwing` | |
+| `@EnableAspectJAutoProxy` | `AopAutoConfiguration` | Siempre activo; no hace falta optar por él. |
+
+DSL de pointcuts: `execution(* pkg.services.*.*(..))` para patrones de métodos; `annotation(timed)` para casar por decorador.
+
+---
+
+## Observabilidad y Actuator
+
+| Spring Boot | PyFly | Notas |
+|---|---|---|
+| `management.endpoints.web.exposure.include` | `pyfly.management.endpoints.web.exposure.include` | |
+| `/actuator/health` | `/actuator/health` | |
+| `/actuator/info` | `/actuator/info` | |
+| `/actuator/beans` | `/actuator/beans` | |
+| `/actuator/env` | `/actuator/env` | |
+| `POST /actuator/refresh` (Spring Cloud) | `POST /actuator/refresh` | Descarta los beans de ámbito refresh; reinicia `@config_properties`; devuelve las claves modificadas. |
+| `@Timed` de Micrometer | `@timed("metric_name")` | Histograma de tiempos del método. |
+| `@Counted` de Micrometer | `@counted("metric_name")` | Contador de invocaciones. |
+| `MetricsRegistry` de Prometheus | `MetricsRegistry` (backend de Prometheus) | Autoconfigurado cuando `prometheus_client` está instalado. |
+| Sleuth / Micrometer Tracing (W3C) | `TracingFilter` (entrante) + `HttpxClientAdapter` (saliente) | El `traceparent` W3C se extrae en un span SERVER; se inyecta en las llamadas httpx salientes. `trace_id`/`span_id` quedan estampados en los logs vía `StructlogAdapter`. No-op seguro sin OpenTelemetry. |
+
+---
+
+## CQRS y sagas
+
+`from pyfly.cqrs import (Command, CommandHandler, DefaultCommandBus,`
+` Query, QueryHandler, DefaultQueryBus, command_handler, query_handler)`
+`from pyfly.transactional.saga.annotations import (saga, saga_step, Input, FromStep)`
+
+| Spring Boot / Axon | PyFly | Notas |
+|---|---|---|
+| `@CommandHandler` | `@command_handler` + `@service` apilados | Ambos decoradores son obligatorios; `@service` registra el bean. Sobrescribe `do_handle(self, cmd)`. |
+| `@QueryHandler` | `@query_handler` + `@service` apilados | Misma regla. Sobrescribe `do_handle(self, qry)`. Método del bus: `.query(...)`. |
+| Inyección del bus en el controlador | `commands: DefaultCommandBus, queries: DefaultQueryBus` | Inyecta las clases concretas, no el protocolo. `commands.send(cmd)`, `queries.query(qry)`. |
+| `@Repository` + puerto | `@repository` sobre una clase que hereda del puerto `Protocol` con `@runtime_checkable` | El puerto es un `Protocol`; la clase adaptadora lo hereda. |
+| `@EventHandler` (event sourcing) | `@event_handler` | Procede del `EventStore`. |
+| `@Saga` | `@saga(name="…", layer_concurrency=N)` + `@service` | Ambos decoradores son obligatorios para la inyección de dependencias + el registro en el motor. |
+| `@SagaStep(id=…, compensate=…)` | `@saga_step(id="…", compensate="method_name")` | |
+| `@Input` | `Annotated[T, Input()]` | El marcador es una **instancia**: `Input()`. Inyecta la carga inicial de la saga. |
+| `@FromStep("id")` | `Annotated[T, FromStep("id")]` | El marcador es una **instancia**: `FromStep("step-id")`. Inyecta el resultado de un paso anterior. |
+| `@Tcc` | `@tcc(name="…")` | Clase de transacción TCC (Try-Confirm-Cancel). |
+| `@TccParticipant` | `@tcc_participant(id="…", order=N)` | |
+| `@TryMethod` / `@ConfirmMethod` / `@CancelMethod` | `@try_method` / `@confirm_method` / `@cancel_method` | Métodos de las tres fases de TCC. |
+| `@FromTry` | `Annotated[T, FromTry]` | Inyecta el resultado de la fase try en confirm/cancel. |
+
+Event sourcing (gestión de estado mediante secuencias de eventos): `from pyfly.eventsourcing import AggregateRoot, EventSourcedRepository`.
+La raíz de agregado usa `self.when(EventType, handler_fn)` para registrar manejadores de aplicación.
+Datos: `from pyfly.data.relational.sqlalchemy import Base` (requiere `pyfly[data-relational]`).
+
+---
+
+## Pruebas de integración
+
+| Spring Boot | PyFly | Notas |
+|---|---|---|
+| `@SpringBootTest` | `service_slice(*beans)` / `slice_context(...)` | Contexto mínimo ya iniciado; `overrides` acepta una clase o una instancia ya construida. |
+| `@WebMvcTest` | `web_slice(*controllers, overrides=…)` → `(context, client)` | Inicia un contexto mínimo + `PyFlyTestClient`. |
+| `@DataJpaTest` | `data_slice(*beans)` → `context` | Slice de la capa de datos. |
+| `@Testcontainers` + `@Container` | `with postgres_container() as pg:` | El context manager de Python gestiona el ciclo de vida. |
+| `@ServiceConnection` | `pyfly_config(pg)` / `pyfly_config_for(pg)` | Asocia los detalles de conexión del contenedor a las claves de configuración de PyFly. |
+| `@DynamicPropertySource` | `pyfly_config(*containers, base=…)` | Un `Config` en una sola llamada para varios contenedores. |
+| `PostgreSQLContainer` | `postgres_container()` | La URL se reescribe automáticamente a `asyncpg`. |
+| `MySQLContainer` | `mysql_container()` | La URL se reescribe a `aiomysql`. |
+| `GenericContainer` (Redis) | `redis_container()` | URLs de caché + sesión cableadas. |
+| `KafkaContainer` | `kafka_container()` | |
+| `@requires_docker` | `@requires_docker` | Omite la prueba limpiamente cuando el demonio de Docker no está presente. |
+
+Instálalo con: `pip install 'pyfly[testcontainers]'`
+
+---
+
+## Servidor embebido
+
+| Spring Boot | PyFly | Notas |
+|---|---|---|
+| `server.port` | `pyfly.server.port` | Puerto HTTP de escucha de la aplicación (por defecto 8080). |
+| `server.address` | `pyfly.server.host` | Dirección de enlace de la aplicación. |
+| `management.server.port` | `pyfly.management.server.port` | Puerto de gestión independiente (actuator + panel de administración); por defecto 9090. |
+| Tomcat (por defecto) | Granian (por defecto) | Runtime HTTP en Rust/tokio; máxima prioridad. |
+| Jetty (alternativa de reserva) | Uvicorn (alternativa de reserva) | Reserva ASGI estándar del ecosistema. |
+| Undertow (alternativa) | Hypercorn (alternativa) | Soporte de protocolos avanzados (HTTP/3). |
+| `server.tomcat.*` | `pyfly.server.granian.*` | Ajuste específico del servidor. |
+| Interfaz `WebServer` | Protocolo `ApplicationServerPort` | Contrato del servidor ASGI embebido. |
+| `EventLoopGroup` (Netty) | Protocolo `EventLoopPort` | Contrato del runtime de E/S. |
+| `server.type: auto` | `pyfly.server.type: auto` (por defecto) | Cascada Granian → Uvicorn → Hypercorn. |
+
+!!! tip "Cascada de autoconfiguración"
+ La autoconfiguración de PyFly usa el mismo patrón de beans condicionales que Spring Boot: si Granian está instalado, gana `GranianServerAdapter`; si no, se prueba Uvicorn a continuación; luego Hypercorn. Anúlalo en cualquier punto aportando tu propio bean `ApplicationServerPort`.
diff --git a/book/manuscript-es/91-appendix-b-mongodb.md b/book/manuscript-es/91-appendix-b-mongodb.md
new file mode 100644
index 00000000..218188b2
--- /dev/null
+++ b/book/manuscript-es/91-appendix-b-mongodb.md
@@ -0,0 +1,447 @@
+Apéndice B
+
+# MongoDB y datos documentales {.chtitle}
+
+La capa de datos documentales de PyFly envuelve MongoDB mediante **Beanie ODM** y **Motor** (el
+driver asíncrono de MongoDB). La API replica deliberadamente la del adaptador relacional: la misma
+clase base `MongoRepository[T, ID]`, la misma convención de nombres para consultas derivadas, el mismo
+vocabulario `Page`/`Pageable`/`Sort`, de modo que cambiar entre almacenamiento relacional y documental
+solo afecta a la definición de la clase de documento y a la clase base del repositorio, no
+a la capa de servicio.
+
+Todos los tipos concretos viven en `pyfly.data.document.mongodb`. Los tipos compartidos (`Page`,
+`Pageable`, `Sort`) provienen de `pyfly.data`.
+
+---
+
+## Instalación y configuración
+
+Instala el extra:
+
+::: listing terminal | Listado B.1 — Instalar el extra data-document
+uv add "pyfly[data-document]"
+:::
+
+Habilita el adaptador en `pyfly.yaml`:
+
+::: listing pyfly.yaml | Listado B.2 — Configuración mínima de MongoDB
+pyfly:
+ data:
+ document:
+ enabled: true
+ uri: "mongodb://localhost:27017"
+ database: "myapp"
+ min_pool_size: 5
+ max_pool_size: 50
+:::
+
+### Referencia de configuración
+
+| Clave de `pyfly.yaml` | Tipo | Valor por defecto | Descripción |
+|---|---|---|---|
+| `pyfly.data.document.enabled` | bool | `false` | Habilita el adaptador de MongoDB |
+| `pyfly.data.document.uri` | str | `mongodb://localhost:27017` | URI de conexión |
+| `pyfly.data.document.database` | str | `pyfly` | Nombre de la base de datos |
+| `pyfly.data.document.min_pool_size` | int | `0` | Mínimo del pool de Motor |
+| `pyfly.data.document.max_pool_size` | int | `100` | Máximo del pool de Motor |
+
+Cada clave tiene una variable de entorno equivalente: sustituye los puntos por guiones bajos y
+pásala a mayúsculas; por ejemplo, `PYFLY_DATA_DOCUMENT_URI`. Para MongoDB Atlas o un conjunto de réplicas (replica set):
+
+::: listing pyfly.yaml | Listado B.3 — URIs de Atlas y de conjunto de réplicas
+# Atlas
+pyfly:
+ data:
+ document:
+ enabled: true
+ uri: >-
+ mongodb+srv://user:secret@cluster.mongodb.net/
+ ?retryWrites=true&w=majority
+ database: production_db
+
+# Replica set (required for transactions)
+# pyfly:
+# data:
+# document:
+# uri: "mongodb://m1:27017,m2:27017,m3:27017/?replicaSet=rs0"
+:::
+
+---
+
+## BaseDocument
+
+`BaseDocument` extiende `beanie.Document` con un rastro de auditoría. Toda clase de documento en
+una aplicación PyFly debería heredar de ella.
+
+| Campo | Tipo | Valor por defecto | Descripción |
+|---|---|---|---|
+| `id` | `PydanticObjectId` | Autogenerado | Clave primaria del documento (ObjectId) |
+| `created_at` | `datetime` | `datetime.now(UTC)` | Marca de tiempo de inserción |
+| `updated_at` | `datetime` | `datetime.now(UTC)` | Marca de tiempo de la última actualización |
+| `created_by` | `str \| None` | `None` | Identificador del creador |
+| `updated_by` | `str \| None` | `None` | Identificador de quien actualizó por última vez |
+
+`use_state_management = True` se establece en la clase base `Settings`, lo que habilita el
+seguimiento de cambios de Beanie para que `save_changes()` produzca actualizaciones parciales eficientes.
+
+Una clase de documento típica:
+
+::: listing catalog/product_document.py | Listado B.4 — ProductDocument con índice y modelo anidado
+from pydantic import BaseModel, Field
+from beanie import Indexed, PydanticObjectId
+from pyfly.data.document.mongodb import BaseDocument
+
+
+class Dimensions(BaseModel):
+ width_cm: float
+ height_cm: float
+ depth_cm: float
+
+
+class ProductDocument(BaseDocument):
+ name: str
+ sku: Indexed(str, unique=True)
+ description: str = ""
+ price: float = Field(gt=0)
+ category: Indexed(str)
+ tags: list[str] = Field(default_factory=list)
+ dimensions: Dimensions | None = None
+ active: bool = True
+
+ class Settings:
+ name = "products"
+:::
+
+El atributo `Settings.name` establece el nombre de la colección de MongoDB. Si lo omites,
+Beanie deriva el nombre a partir del nombre de la clase, lo cual rara vez es lo que deseas.
+
+Para índices compuestos o descendentes usa `Settings.indexes`:
+
+::: listing catalog/product_document.py | Listado B.5 — Índice compuesto mediante Settings.indexes
+from pymongo import IndexModel, ASCENDING, DESCENDING
+from pyfly.data.document.mongodb import BaseDocument
+
+
+class OrderDocument(BaseDocument):
+ customer_id: str
+ status: str
+ total: float
+ region: str
+
+ class Settings:
+ name = "orders"
+ indexes = [
+ IndexModel(
+ [("customer_id", ASCENDING), ("status", ASCENDING)],
+ name="idx_customer_status",
+ ),
+ IndexModel(
+ [("region", ASCENDING), ("total", DESCENDING)],
+ name="idx_region_total",
+ ),
+ ]
+:::
+
+---
+
+## Correspondencia entre Spring Data y MongoRepository
+
+La siguiente tabla muestra cómo los conceptos de Spring Data MongoDB se corresponden con la capa documental de PyFly.
+La superficie es intencionadamente idéntica a la de `Repository[T, ID]` del adaptador relacional,
+de modo que los mismos patrones de la capa de servicio se aplican a ambos.
+
+| Spring Data MongoDB | PyFly | Notas |
+|---|---|---|
+| `MongoRepository` | `MongoRepository[E, ID]` | `from pyfly.data.document.mongodb import MongoRepository`; decora con `@repository`. |
+| `@Document class Product` + `@Id` | `class ProductDocument(BaseDocument)` | `from pyfly.data.document.mongodb import BaseDocument`. Hereda `id` (`PydanticObjectId` de Beanie), `created_at`, `updated_at`, `created_by`, `updated_by`. El nombre de la colección se fija en `class Settings: name = "products"`. |
+| `findByCategory(String c)` | `async def find_by_category(self, category: str) -> list[ProductDocument]: ...` | El cuerpo vacío `...` lo compila `MongoRepositoryBeanPostProcessor` al arrancar. Mismos prefijos que en el relacional: `find_by_`, `count_by_`, `exists_by_`, `delete_by_`. |
+| `@Query("{ 'status': ?0 }")` | `@query('{"status": ":status"}')` | `from pyfly.data.query import query`. Filtro JSON o pipeline de agregación; sustitución de `:param`. |
+| `MongoSpecification` | `MongoSpecification(lambda root, q: {"active": True})` | `from pyfly.data.document.mongodb import MongoSpecification`. Compón con `&` / `\|` / `~`; ejecuta mediante `find_all_by_spec(spec)` o `find_all_by_spec_paged(spec, pageable)`. |
+| `PageRequest.of(page, size, Sort.by(…))` | `Pageable.of(page, size, Sort.by("name").descending())` | `from pyfly.data import Pageable, Sort`, idéntico al adaptador relacional. |
+| `Page` | `Page[T]` | `.items`, `.total`, `.page`, `.size`, `.total_pages`, `.map(fn)`, igual que en el relacional. |
+
+---
+
+## MongoRepository[T, ID]
+
+Crea una subclase de `MongoRepository[T, ID]` y anótala con `@repository`. El framework
+extrae el tipo de documento y el tipo de ID a partir de los parámetros genéricos en el momento
+de definir la clase, mediante `__init_subclass__`. No se requiere ningún `__init__`.
+
+::: listing catalog/product_repository.py | Listado B.6 — ProductRepository: CRUD + consultas derivadas
+from beanie import PydanticObjectId
+from pyfly.container import repository
+from pyfly.data.document.mongodb import MongoRepository
+
+from catalog.product_document import ProductDocument
+
+
+@repository
+class ProductRepository(MongoRepository[ProductDocument, PydanticObjectId]):
+
+ # --- derived query method stubs (compiled at startup) ---
+
+ async def find_by_category(
+ self, category: str
+ ) -> list[ProductDocument]: ...
+
+ async def find_by_active_and_category(
+ self, active: bool, category: str
+ ) -> list[ProductDocument]: ...
+
+ async def find_by_price_greater_than_order_by_price_desc(
+ self, min_price: float
+ ) -> list[ProductDocument]: ...
+
+ async def find_by_name_containing(
+ self, fragment: str
+ ) -> list[ProductDocument]: ...
+
+ async def count_by_category(self, category: str) -> int: ...
+
+ async def exists_by_sku(self, sku: str) -> bool: ...
+
+ async def delete_by_active(self, active: bool) -> int: ...
+:::
+
+### Métodos CRUD integrados
+
+| Método | Tipo de retorno | Descripción |
+|---|---|---|
+| `save(entity)` | `T` | Inserta o actualiza mediante `entity.save()` de Beanie |
+| `find_by_id(id)` | `T \| None` | Busca por clave primaria |
+| `find_all(**filters)` | `list[T]` | Busca todos; los argumentos por palabra clave se convierten en filtros de igualdad |
+| `find_all(sort)` | `list[T]` | Recupera todos los documentos, ordenados por un `Sort` |
+| `find_all(pageable)` | `Page[T]` | Consulta paginada: cuenta el total, aplica el orden del Pageable, recorta con skip/limit y devuelve `Page[T]` |
+| `stream_all(sort)` | `AsyncIterator[T]` | Transmite todos los documentos (el análogo de Flux); admite un `Sort` y filtros de igualdad opcionales |
+| `delete(entity)` | `None` | Elimina una instancia de documento ya cargada |
+| `delete_by_id(id)` | `None` | Elimina por clave primaria; no hace nada si no se encuentra |
+| `count()` | `int` | Cuenta todos los documentos de la colección |
+| `exists_by_id(id)` | `bool` | True si existe un documento con este ID |
+| `save_all(entities)` | `list[T]` | Inserción masiva mediante `insert_many` |
+| `find_all_by_id(ids)` | `list[T]` | Busca todos cuyos ID estén en una lista |
+| `delete_all_by_id(ids)` | `None` | Elimina todos cuyos ID estén en una lista |
+| `delete_all(entities=None)` | `None` | Elimina los documentos indicados; sin argumentos, vacía la colección entera |
+| `find_all_by_spec(spec)` | `list[T]` | Busca los que coincidan con una `MongoSpecification` |
+| `find_all_by_spec_paged(spec, pageable)` | `Page[T]` | Busca los que coincidan con una `MongoSpecification`, con paginación y orden |
+
+`find_all(**filters)` traduce los argumentos por palabra clave en filtros de igualdad de MongoDB:
+
+```python
+# {"status": "PENDING", "customer_id": "abc"}
+orders = await repo.find_all(status="PENDING", customer_id="abc")
+```
+
+---
+
+## Métodos de consulta derivados
+
+PyFly compila los métodos vacíos (stubs) de las subclases de `MongoRepository` en consultas reales de MongoDB
+al arrancar. La convención de nombres es idéntica a la del adaptador relacional y a la de Spring
+Data: `{prefix}_by_{predicates}[_order_by_{fields}]`.
+
+**Prefijos:** `find_by`, `count_by`, `exists_by`, `delete_by`
+
+**Conectores:** `_and_`, `_or_`
+
+### Correspondencia de operadores
+
+| Sufijo del método | Filtro de MongoDB | Argumentos consumidos |
+|---|---|---|
+| *(ninguno, por defecto)* | `{field: value}` | 1 |
+| `_not` | `{field: {"$ne": value}}` | 1 |
+| `_greater_than` | `{field: {"$gt": value}}` | 1 |
+| `_greater_than_equal` | `{field: {"$gte": value}}` | 1 |
+| `_less_than` | `{field: {"$lt": value}}` | 1 |
+| `_less_than_equal` | `{field: {"$lte": value}}` | 1 |
+| `_between` | `{field: {"$gte": low, "$lte": high}}` | 2 |
+| `_like` | `{field: {"$regex": pattern}}` (SQL % → .*) | 1 |
+| `_containing` | `{field: {"$regex": ".*val.*", "$options": "i"}}` | 1 |
+| `_in` | `{field: {"$in": values}}` | 1 (lista) |
+| `_is_null` | `{field: None}` | 0 |
+| `_is_not_null` | `{field: {"$ne": None}}` | 0 |
+
+Ordenación: añade `_order_by_{field}_{asc|desc}`. Varios campos de ordenación se encadenan:
+
+```python
+# sort=[("name", ASC), ("created_at", DESC)]
+async def find_by_active_order_by_name_asc_created_at_desc(
+ self, active: bool
+) -> list[ProductDocument]: ...
+```
+
+El `MongoRepositoryBeanPostProcessor` detecta los stubs (cuerpos que solo contienen `...`
+o `pass`) y los reemplaza por invocables compilados. Fuente:
+`src/pyfly/data/document/mongodb/post_processor.py` y
+`src/pyfly/data/document/mongodb/query_compiler.py`.
+
+---
+
+## Consultas personalizadas con @query
+
+Para las consultas que no pueden expresarse mediante convenciones de nombres, `@query` acepta un
+documento de filtro de MongoDB (`{…}`) o un pipeline de agregación (`[…]`) como cadena JSON.
+Los parámetros con nombre usan la sintaxis `:param_name`.
+
+::: listing catalog/order_repository.py | Listado B.7 — Ejemplos de filtro y agregación con @query
+from pyfly.container import repository
+from pyfly.data.document.mongodb import MongoRepository
+from pyfly.data.query import query
+
+from catalog.order_document import OrderDocument
+
+
+@repository
+class OrderRepository(MongoRepository[OrderDocument, str]):
+
+ @query('{"status": ":status", "total": {"$gte": ":min_total"}}')
+ async def find_by_status_min_total(
+ self, status: str, min_total: float
+ ) -> list[OrderDocument]: ...
+
+ @query(
+ '[{"$match": {"customer_id": ":cid"}},'
+ ' {"$group": {"_id": "$category",'
+ ' "total": {"$sum": "$amount"}}}]'
+ )
+ async def totals_by_category(
+ self, cid: str
+ ) -> list[dict]: ...
+:::
+
+**Reglas de sustitución:**
+
+- Un valor de cadena JSON que sea *exactamente* `:param_name` se reemplaza por el valor de Python,
+ conservando su tipo (`int`, `bool`, `list`, etc.).
+- Un `:param_name` incrustado dentro de una cadena mayor se reemplaza mediante `str(value)`.
+- Los diccionarios y las listas se recorren recursivamente. Los valores JSON no textuales pasan sin cambios.
+
+`MongoQueryExecutor` analiza la plantilla de la consulta una sola vez al arrancar, detecta si
+se trata de un filtro o de un pipeline, y sustituye los parámetros en el momento de la llamada.
+
+---
+
+## Paginación
+
+::: listing catalog/product_service.py | Listado B.8 — Listado de productos paginado
+from pyfly.data import Page, Pageable, Sort
+from pyfly.data.document.mongodb import MongoRepository
+
+from catalog.product_document import ProductDocument
+
+
+async def list_products(
+ repo: MongoRepository[ProductDocument, str],
+ page: int = 1,
+ size: int = 20,
+) -> Page[ProductDocument]:
+ pageable = Pageable.of(
+ page=page,
+ size=size,
+ sort=Sort.by("name"),
+ )
+ return await repo.find_all(pageable)
+:::
+
+`find_all(pageable)` cuenta el total, aplica el orden del Pageable, recorta con
+`.skip((page-1)*size)` y `.limit(size)` sobre la consulta de Beanie, y devuelve `Page[T]`.
+Pageable parte de 1, así que la página `1` es la primera página.
+
+---
+
+## Gestión de transacciones
+
+Las transacciones multidocumento requieren un despliegue con **conjunto de réplicas** (replica set). Una instancia
+de MongoDB independiente (standalone) no las admite.
+
+::: listing pyfly.yaml | Listado B.9 — Conjunto de réplicas de un solo nodo para desarrollo local
+# Start MongoDB: mongod --replSet rs0 --bind_ip localhost
+# Init (once, in mongosh): rs.initiate()
+pyfly:
+ data:
+ document:
+ enabled: true
+ uri: "mongodb://localhost:27017/?replicaSet=rs0"
+ database: myapp
+:::
+
+El decorador `@mongo_transactional` envuelve una función asíncrona en una sesión y una
+transacción de Motor. Las operaciones de Beanie de la función participan automáticamente:
+
+::: listing billing/transfer.py | Listado B.10 — Transferencia de fondos atómica con @mongo_transactional
+from motor.motor_asyncio import AsyncIOMotorClient
+from pyfly.data.document.mongodb import mongo_transactional
+
+from billing.account_document import AccountDocument
+
+
+def make_transfer_fn(client: AsyncIOMotorClient):
+ @mongo_transactional(client)
+ async def transfer(
+ from_id: str, to_id: str, amount: float
+ ) -> None:
+ src = await AccountDocument.get(from_id)
+ dst = await AccountDocument.get(to_id)
+ if src is None or dst is None or src.balance < amount:
+ raise ValueError("Invalid transfer")
+ src.balance -= amount
+ dst.balance += amount
+ await src.save()
+ await dst.save()
+ return transfer
+:::
+
+Si todo va bien, la transacción se confirma (commit); ante cualquier excepción se aborta y se vuelve a lanzar. A diferencia
+de `@reactive_transactional` del relacional, la sesión de Motor no se inyecta como
+argumento: Beanie la recoge a través del contexto de Motor.
+
+El bean `motor_client` lo registra automáticamente `DocumentAutoConfiguration`
+cuando el adaptador está habilitado. Inyéctalo en tu servicio mediante el contenedor de inyección de dependencias.
+
+!!! warning "Se requiere un conjunto de réplicas"
+ `@mongo_transactional` lanzará un error contra una instancia de MongoDB independiente.
+ Usa el fragmento de URI `?replicaSet=rs0` (consulta el Listado B.9) incluso en desarrollo local.
+
+---
+
+## Autoconfiguración
+
+`DocumentAutoConfiguration` se activa cuando:
+
+1. `beanie` es importable (`@conditional_on_class("beanie")`), y
+2. `pyfly.data.document.enabled` vale `"true"` en la configuración.
+
+Registra tres beans automáticamente:
+
+| Bean | Tipo | Función |
+|---|---|---|
+| `motor_client` | `AsyncIOMotorClient` | Pool de conexiones asíncrono de MongoDB |
+| `mongo_post_processor` | `MongoRepositoryBeanPostProcessor` | Compila los stubs de consultas derivadas |
+| `odm_initializer` | `BeanieInitializer` | Llama a `init_beanie()` al arrancar |
+
+`BeanieInitializer.start()` descubre las subclases de `BaseDocument` en dos pasadas: primero
+desde cada `MongoRepository._entity_type` registrado (establecido por `__init_subclass__`),
+y luego las subclases de `BaseDocument` registradas directamente. Esto significa que definir un repositorio
+es suficiente: no necesitas registrar los modelos de documento por separado.
+
+Archivos fuente: `src/pyfly/data/document/auto_configuration.py`,
+`src/pyfly/data/document/mongodb/initializer.py`.
+
+---
+
+## Pruebas
+
+Para las pruebas unitarias, usa [mongomock-motor](https://github.com/michaelkryukov/mongomock-motor)
+o apunta a una base de datos de pruebas dedicada:
+
+::: listing pyfly-test.yaml | Listado B.11 — Configuración de la base de datos de pruebas
+pyfly:
+ data:
+ document:
+ enabled: true
+ database: "myapp_test"
+:::
+
+Para las pruebas de integración, el soporte de Testcontainers de PyFly levanta automáticamente un contenedor
+real de MongoDB; consulta el capítulo de pruebas y
+`@ServiceConnection(MongoDBContainer)`.
diff --git a/book/manuscript-es/92-appendix-c-ecm.md b/book/manuscript-es/92-appendix-c-ecm.md
new file mode 100644
index 00000000..fbbc9090
--- /dev/null
+++ b/book/manuscript-es/92-appendix-c-ecm.md
@@ -0,0 +1,358 @@
+Apéndice C
+
+# ECM: contenido y firma electrónica {.chtitle}
+
+`pyfly.ecm` proporciona abstracciones hexagonales para la gestión documental
+empresarial: almacenamiento de blobs, metadatos de documentos, jerarquías de
+carpetas y flujos de firma electrónica. El módulo incluye adaptadores
+completamente cableados para almacenamiento local, AWS S3 y Azure Blob Storage,
+además de adaptadores de firma electrónica para DocuSign, Adobe Sign y Logalty
+— todos seleccionables sin cambiar una sola línea del código de la aplicación,
+puramente mediante YAML.
+
+!!! note "El módulo en sí no requiere dependencias adicionales"
+ El módulo ECM central (`pyfly.ecm`) no tiene dependencias de terceros más
+ allá de la biblioteca estándar. Los adaptadores de almacenamiento en la nube
+ (`boto3`, `azure-storage-blob`) y las llamadas a los SDK de firma electrónica
+ se realizan a través de envoltorios asíncronos ligeros en cada clase de
+ adaptador; instala solo lo que necesites.
+
+---
+
+## Modelo de dominio
+
+Todos los tipos de ECM son dataclasses sencillas de Python definidas en
+`src/pyfly/ecm/models.py`.
+
+| Clase | Campos clave | Descripción |
+|---|---|---|
+| `Document` | `id`, `name`, `folder_id`, `content_type`, `size_bytes`, `metadata`, `versions` | Registro lógico de documento |
+| `DocumentVersion` | `version`, `content_hash`, `size_bytes`, `storage_uri` | Instantánea inmutable de versión |
+| `Folder` | `id`, `name`, `parent_id`, `path` | Nodo de carpeta en la jerarquía |
+| `Recipient` | `name`, `email`, `role` | Destinatario de firma electrónica |
+| `SignatureRequest` | `document_id`, `recipients`, `subject`, `message` | Carga útil de la solicitud de firma |
+| `ESignatureEnvelope` | `id`, `provider`, `status`, `provider_envelope_id` | Registro de seguimiento del sobre |
+
+`ESignatureStatus` es un `StrEnum` con los valores `DRAFT`, `SENT`, `SIGNED`,
+`DECLINED` y `EXPIRED`.
+
+---
+
+## Puertos (contratos)
+
+Cuatro clases `Protocol` definidas en `src/pyfly/ecm/ports.py` forman el límite
+hexagonal. Los servicios de tu aplicación dependen de estos contratos; los
+adaptadores los implementan.
+
+### DocumentStoragePort
+
+```python
+class DocumentStoragePort(Protocol):
+ name: str
+ async def upload(
+ self, document: Document, content: bytes
+ ) -> DocumentVersion: ...
+ async def download(
+ self, document: Document, version: int | None = None
+ ) -> bytes: ...
+ async def delete(
+ self, document: Document, version: int | None = None
+ ) -> bool: ...
+```
+
+### MetadataStoragePort
+
+```python
+class MetadataStoragePort(Protocol):
+ async def save(self, document: Document) -> Document: ...
+ async def get(self, document_id: str) -> Document | None: ...
+ async def list(
+ self, folder_id: str | None = None, *, limit: int = 100
+ ) -> list[Document]: ...
+ async def delete(self, document_id: str) -> bool: ...
+```
+
+### FolderRepositoryPort
+
+```python
+class FolderRepositoryPort(Protocol):
+ async def save(self, folder: Folder) -> Folder: ...
+ async def get(self, folder_id: str) -> Folder | None: ...
+ async def list(self, parent_id: str | None = None) -> list[Folder]: ...
+ async def delete(self, folder_id: str) -> bool: ...
+```
+
+### ESignatureAdapter
+
+```python
+class ESignatureAdapter(Protocol):
+ name: str
+ async def send(
+ self, request: SignatureRequest
+ ) -> ESignatureEnvelope: ...
+ async def get(self, envelope_id: str) -> ESignatureEnvelope | None: ...
+ async def cancel(self, envelope_id: str) -> bool: ...
+```
+
+---
+
+## DocumentService
+
+`DocumentService` orquesta los puertos de almacenamiento y de metadatos. Es el
+punto de entrada principal para la subida, descarga, listado y eliminación de
+documentos.
+
+::: listing contracts/ecm_usage.py | Listado C.1 — DocumentService: subir, descargar, eliminar
+from pyfly.ecm import (
+ DocumentService,
+ LocalFilesystemStorageAdapter,
+)
+from pyfly.ecm.in_memory import (
+ InMemoryFolderRepository,
+ InMemoryMetadataStorage,
+)
+
+
+service = DocumentService(
+ storage=LocalFilesystemStorageAdapter("/var/ecm/docs"),
+ metadata=InMemoryMetadataStorage(),
+ folders=InMemoryFolderRepository(),
+)
+
+
+async def demo() -> None:
+ # Upload
+ doc = await service.upload(
+ name="contract.pdf",
+ content=b"%PDF-1.4 ...",
+ content_type="application/pdf",
+ metadata={"department": "legal", "year": "2026"},
+ )
+
+ # Download (latest version)
+ content = await service.download(doc.id)
+
+ # Download a specific version
+ v1_content = await service.download(doc.id, version=1)
+
+ # List documents in a folder
+ docs = await service.list(folder_id=doc.folder_id)
+
+ # Delete (returns False if blob delete partially fails)
+ ok = await service.delete(doc.id)
+:::
+
+### Semántica de `delete`
+
+`DocumentService.delete(document_id)` elimina tanto el blob almacenado como el
+registro de metadatos y devuelve el **AND lógico** de los dos resultados de
+eliminación. Si el ID del documento es desconocido, devuelve `False` de
+inmediato. Si la eliminación del blob falla, el registro de metadatos se elimina
+igualmente (de modo que el documento lógico desaparece), pero el método devuelve
+`False` para señalar una eliminación parcial. Este contrato se verifica en el
+código fuente en `src/pyfly/ecm/services.py`.
+
+### Gestión de carpetas
+
+::: listing contracts/ecm_folders.py | Listado C.2 — Creación de jerarquías de carpetas
+from pyfly.ecm import DocumentService, Folder
+
+
+async def setup_folders(service: DocumentService) -> None:
+ root = await service.create_folder(
+ Folder(name="contracts", path="/contracts")
+ )
+ legal = await service.create_folder(
+ Folder(name="legal", parent_id=root.id, path="/contracts/legal")
+ )
+ doc = await service.upload(
+ name="nda.pdf",
+ content=b"...",
+ folder_id=legal.id,
+ content_type="application/pdf",
+ )
+:::
+
+!!! note "El puerto de carpetas es opcional"
+ Pasa `folders=None` a `DocumentService` si no necesitas soporte de carpetas.
+ Llamar a `create_folder` en una instancia así lanza `RuntimeError`.
+
+---
+
+## ESignatureService
+
+`ESignatureService` envuelve un `ESignatureAdapter` y expone tres operaciones:
+`request`, `get` y `cancel`.
+
+::: listing contracts/esignature_usage.py | Listado C.3 — Solicitar una firma electrónica
+from pyfly.ecm import (
+ ESignatureService,
+ NoOpESignatureAdapter,
+ Recipient,
+ SignatureRequest,
+)
+
+
+esig = ESignatureService(adapter=NoOpESignatureAdapter())
+
+
+async def send_for_signature(document_id: str) -> str:
+ envelope = await esig.request(
+ SignatureRequest(
+ document_id=document_id,
+ recipients=[
+ Recipient(
+ name="Alice Johnson",
+ email="alice@example.com",
+ role="signer",
+ ),
+ ],
+ subject="Please sign your employment contract",
+ message="Review and sign at your earliest convenience.",
+ )
+ )
+ return envelope.id
+:::
+
+---
+
+## Adaptadores de almacenamiento
+
+| Clase de adaptador | Valor de `pyfly.ecm.storage.provider` | Notas |
+|---|---|---|
+| `LocalFilesystemStorageAdapter` | `local` (por defecto) | Almacena los blobs como `//v` |
+| `AwsS3StorageAdapter` | `s3` o `aws` | Requiere `boto3`; asíncrono mediante `run_in_executor` |
+| `AzureBlobStorageAdapter` | `azure` | Requiere `azure-storage-blob` |
+
+Los tres implementan `DocumentStoragePort`. `LocalFilesystemStorageAdapter` crea
+el directorio base en el momento de la construcción y almacena cada versión como
+un archivo independiente, lo que lo hace adecuado para desarrollo y pruebas sin
+servicios externos.
+
+## Adaptadores de firma electrónica
+
+| Clase de adaptador | Valor de `pyfly.ecm.esignature.provider` | Notas |
+|---|---|---|
+| `NoOpESignatureAdapter` | `noop` (por defecto) | Devuelve sobres ficticios; seguro para dev/test |
+| `DocuSignESignatureAdapter` | `docusign` | Llamadas a la API REST mediante `httpx` |
+| `AdobeSignESignatureAdapter` | `adobe` | Llamadas a la API REST mediante `httpx` |
+| `LogaltyESignatureAdapter` | `logalty` | Llamadas a la API REST mediante `httpx` |
+
+Implementa `ESignatureAdapter` para añadir un proveedor personalizado (por
+ejemplo, un servicio de firma interno). Registra tu implementación como un bean e
+inyéctala en `ESignatureService`.
+
+---
+
+## Autoconfiguración
+
+`EcmAutoConfiguration` se activa cuando se establece `pyfly.ecm.enabled=true` en
+la configuración. Registra cinco beans:
+
+| Bean | Implementación por defecto |
+|---|---|
+| `metadata_storage` | `InMemoryMetadataStorage` |
+| `folder_repository` | `InMemoryFolderRepository` |
+| `document_storage` | `LocalFilesystemStorageAdapter` (directorio temporal) |
+| `document_service` | `DocumentService` cableando los tres anteriores |
+| `esignature_adapter` | `NoOpESignatureAdapter` |
+| `esignature_service` | `ESignatureService` envolviendo el adaptador |
+
+Los adaptadores de almacenamiento y de firma electrónica se seleccionan desde la
+configuración, de modo que cambias de proveedor puramente mediante YAML — sin
+necesidad de cambiar código:
+
+::: listing pyfly.yaml | Listado C.4 — YAML de ECM completo con almacenamiento S3 y DocuSign
+pyfly:
+ ecm:
+ enabled: true
+ storage:
+ provider: s3
+ local:
+ base-dir: /var/ecm
+ s3:
+ bucket: my-docs-bucket
+ region: eu-west-1
+ key-prefix: documents/
+ azure:
+ container: my-container
+ connection-string: "DefaultEndpointsProtocol=https;..."
+ account-url: "https://acct.blob.core.windows.net"
+ key-prefix: documents/
+ esignature:
+ provider: docusign
+ docusign:
+ base-url: "https://demo.docusign.net/restapi"
+ account-id: "your-account-id"
+ access-token: "your-access-token"
+ adobe:
+ api-base: "https://api.na4.adobesign.com"
+ access-token: "your-token"
+ logalty:
+ api-base: "https://api.logalty.com"
+ api-key: "your-api-key"
+:::
+
+!!! tip "Empieza con local + noop"
+ En desarrollo, omite las claves `provider` y deja que actúen los valores por
+ defecto: el almacenamiento `local` usa un directorio temporal nuevo y la
+ firma electrónica `noop` devuelve datos ficticios deterministas. No se
+ necesitan servicios externos.
+
+---
+
+## Implementar un adaptador de almacenamiento personalizado
+
+Implementa `DocumentStoragePort` y regístralo como un `@bean`:
+
+::: listing infra/gcs_storage.py | Listado C.5 — Esqueleto de un adaptador de almacenamiento personalizado
+from pyfly.ecm.models import Document, DocumentVersion
+from pyfly.ecm.ports import DocumentStoragePort
+
+
+class GcsStorageAdapter:
+ """Google Cloud Storage adapter (skeleton)."""
+
+ name = "gcs"
+
+ def __init__(self, bucket: str, key_prefix: str = "") -> None:
+ self._bucket = bucket
+ self._prefix = key_prefix
+
+ async def upload(
+ self, document: Document, content: bytes
+ ) -> DocumentVersion:
+ version_no = (
+ (document.versions[-1].version + 1) if document.versions else 1
+ )
+ key = f"{self._prefix}{document.id}/v{version_no}"
+ # ... upload content to GCS ...
+ return DocumentVersion(
+ version=version_no,
+ content_hash="sha256-placeholder",
+ size_bytes=len(content),
+ storage_uri=f"gs://{self._bucket}/{key}",
+ )
+
+ async def download(
+ self, document: Document, version: int | None = None
+ ) -> bytes:
+ target = version or document.versions[-1].version
+ key = f"{self._prefix}{document.id}/v{target}"
+ # ... download from GCS ...
+ return b""
+
+ async def delete(
+ self, document: Document, version: int | None = None
+ ) -> bool:
+ # ... delete object(s) from GCS ...
+ return True
+:::
+
+Archivos fuente:
+- `src/pyfly/ecm/models.py` — dataclasses de dominio
+- `src/pyfly/ecm/ports.py` — contratos Protocol
+- `src/pyfly/ecm/services.py` — `DocumentService`, `ESignatureService`
+- `src/pyfly/ecm/adapters/` — adaptadores de almacenamiento y firma electrónica incluidos
+- `src/pyfly/ecm/in_memory.py` — `InMemoryMetadataStorage`, `InMemoryFolderRepository`
+- `src/pyfly/ecm/auto_configuration.py` — `EcmAutoConfiguration`
diff --git a/book/manuscript-es/93-appendix-d-cli.md b/book/manuscript-es/93-appendix-d-cli.md
new file mode 100644
index 00000000..06e9e2b4
--- /dev/null
+++ b/book/manuscript-es/93-appendix-d-cli.md
@@ -0,0 +1,350 @@
+Apéndice D
+
+# CLI y resolución de problemas {.chtitle}
+
+La CLI `pyfly` proporciona andamiaje de proyectos, arranque de la aplicación,
+migraciones de base de datos y diagnóstico del entorno. Está construida con
+**Click** para el análisis de comandos y con **Rich** para la salida coloreada en
+la terminal.
+
+**Instalación:** `uv add "pyfly[cli]"` (o `uv sync --extra cli`). Requiere Click,
+Rich, Jinja2 y questionary.
+
+**Punto de entrada:** `pyfly` — registrado como script de consola en `pyproject.toml`.
+
+---
+
+## Referencia de comandos
+
+| Comando | Descripción |
+|---|---|
+| `pyfly new [NAME]` | Genera el andamiaje de un nuevo proyecto (interactivo o directo) |
+| `pyfly run` | Arranca el servidor de aplicación ASGI |
+| `pyfly info` | Muestra la versión de Python y los extras instalados |
+| `pyfly doctor` | Diagnostica el entorno (Python, herramientas, PyFly) |
+| `pyfly db init` | Inicializa un entorno de migraciones de Alembic |
+| `pyfly db migrate [-m MSG]` | Genera automáticamente una revisión de migración |
+| `pyfly db upgrade [REVISION]` | Aplica las migraciones pendientes (por defecto: `head`) |
+| `pyfly db downgrade REVISION` | Revierte a una revisión anterior |
+| `pyfly license` | Muestra el texto de la licencia Apache 2.0 |
+| `pyfly sbom [--json]` | Tabla del Software Bill of Materials (inventario de software) |
+| `pyfly --version` | Imprime la versión instalada de PyFly |
+| `pyfly --help` | Imprime el banner y todos los comandos |
+
+---
+
+## pyfly new
+
+Crea un directorio de proyecto completo a partir de uno de siete arquetipos.
+
+```
+pyfly new [--archetype ARCHETYPE] [--features FEAT,...] [--directory DIR]
+pyfly new # interactive mode (questionary TUI)
+```
+
+### Arquetipos
+
+| Arquetipo | Características por defecto | Qué se genera |
+|---|---|---|
+| `core` | *(ninguna)* | Contenedor de DI, configuración, Dockerfile |
+| `web-api` | `web` | Controladores REST, servicios, repositorios (CRUD de Todo) |
+| `fastapi-api` | `fastapi` | Stack FastAPI, OpenAPI nativo |
+| `web` | `web` | HTML renderizado en servidor con plantillas Jinja2 |
+| `hexagonal` | `web` | Puertos y adaptadores, capas dominio/aplicación/infra/api |
+| `library` | *(ninguna)* | Paquete PEP 561 `py.typed`, sin runtime de PyFly |
+| `cli` | `shell` | Comandos de shell con DI, sin punto de entrada ASGI |
+
+### Valores disponibles para `--features`
+
+| Característica | Qué añade |
+|---|---|
+| `web` | Servidor HTTP Starlette, controladores REST, documentación OpenAPI |
+| `fastapi` | Servidor HTTP FastAPI, OpenAPI nativo |
+| `granian` | Servidor ASGI Granian (Rust/tokio) |
+| `hypercorn` | Servidor ASGI Hypercorn (HTTP/2, HTTP/3) |
+| `data-relational` | SQLAlchemy ORM (asíncrono), migraciones Alembic |
+| `data-document` | Beanie ODM, Motor (MongoDB) |
+| `eda` | Bus de eventos en memoria, soporte de Kafka + RabbitMQ |
+| `cache` | Capa de caché (en memoria por defecto; Redis si está instalado) |
+| `client` | Cliente HTTP resiliente (httpx + reintentos/cortacircuitos) |
+| `security` | Autenticación JWT, hashing de contraseñas con bcrypt |
+| `scheduling` | Programación de tareas basada en cron |
+| `observability` | Métricas de Prometheus, trazas de OpenTelemetry |
+| `cqrs` | Segregación de Responsabilidad entre Comandos y Consultas (CQRS) |
+| `shell` | Comandos de shell interactivos potenciados con DI |
+
+### Ejemplos
+
+::: listing terminal | Listado D.1 — Ejemplos de pyfly new
+# Minimal core service
+pyfly new wallet-service
+
+# REST API with SQL data layer
+pyfly new lumen --archetype web-api --features web,data-relational
+
+# Hexagonal service with cache and security
+pyfly new payment-svc --archetype hexagonal \
+ --features web,data-relational,cache,security
+
+# MongoDB-backed microservice
+pyfly new catalog-svc --archetype web-api \
+ --features web,data-document
+
+# CLI application with interactive shell
+pyfly new admin-tool --archetype cli
+
+# Interactive mode (arrow keys + checkboxes)
+pyfly new
+:::
+
+En el modo interactivo, el asistente solicita el nombre, el nombre del paquete
+(precargado a partir del nombre del proyecto), el arquetipo (selección única con
+las flechas) y las características (selección múltiple con la barra espaciadora).
+Antes de la creación se muestra un resumen de confirmación. Pulsa Ctrl+C en
+cualquier prompt para salir de forma limpia.
+
+Los nombres de proyecto que contienen guiones se convierten automáticamente a
+nombres de paquete de Python válidos (`my-service` → `my_service`). Usa el prompt
+**Package name** en el modo interactivo para sobrescribir este valor derivado.
+
+---
+
+## pyfly run
+
+Arranca la aplicación ASGI usando el servidor seleccionado automáticamente.
+
+```
+pyfly run [--host HOST] [--port PORT] [--server SERVER]
+ [--workers N] [--reload] [--app MODULE:VAR]
+```
+
+| Opción | Por defecto | Descripción |
+|---|---|---|
+| `--host` | `0.0.0.0` | Dirección de enlace |
+| `--port` | Config o `8080` | Puerto de la app (CLI → `pyfly.server.port` → 8080) |
+| `--server` | Autodetección | `granian`, `uvicorn` o `hypercorn` |
+| `--workers` | Config o `0` | Procesos worker (`0` = número de CPUs) |
+| `--reload` | desactivado | Recarga automática al cambiar el código |
+| `--app` | Autodescubrimiento | Ruta de importación, p. ej. `myapp.main:app` |
+
+**Prioridad de servidores** (cuando se omite `--server`): Granian › Uvicorn › Hypercorn.
+Gana el primer servidor que se pueda importar.
+
+**Descubrimiento de la aplicación** (cuando se omite `--app`):
+
+1. `pyfly.app.module` en `pyfly.yaml`
+2. `app.module` en `pyfly.yaml` (disposición plana)
+3. Autoescaneo de `src//main.py`
+
+`pyfly run` añade `src/` a `sys.path` automáticamente en los proyectos con
+disposición src.
+
+::: listing terminal | Listado D.2 — Ejemplos de pyfly run
+# Development with auto-reload
+pyfly run --reload
+
+# Production: Granian, bind all interfaces, all CPU cores
+pyfly run --host 0.0.0.0 --port 80 --server granian --workers 0
+
+# Explicit application path
+pyfly run --app my_service.main:app
+:::
+
+---
+
+## pyfly info
+
+Muestra dos tablas de Rich: versión de Python, plataforma y arquitectura; además
+del estado de instalación de cada módulo opcional de PyFly. Resulta útil tras una
+instalación selectiva para confirmar qué adaptadores están disponibles.
+
+```
+pyfly info
+```
+
+---
+
+## pyfly doctor
+
+Ejecuta una comprobación integral de salud del entorno.
+
+```
+pyfly doctor
+```
+
+| Comprobación | Condición de aprobado | Impacto del fallo |
+|---|---|---|
+| Versión de Python | >= 3.12 | Fatal — doctor informa de fallo |
+| Entorno virtual | `sys.prefix != sys.base_prefix` | Solo advertencia |
+| `git` en el PATH | `shutil.which("git")` devuelve una ruta | Fatal |
+| `uv` en el PATH | `shutil.which("uv")` devuelve una ruta | Fatal |
+| `uvicorn` en el PATH | presente | Informativo (`-`) |
+| `alembic` en el PATH | presente | Informativo (`-`) |
+| `ruff` en el PATH | presente | Informativo (`-`) |
+| `mypy` en el PATH | presente | Informativo (`-`) |
+| PyFly importable | `import pyfly` tiene éxito | Fatal |
+
+Finaliza con **"All checks passed!"** o **"Some issues found."**.
+
+---
+
+## pyfly db
+
+Comandos de migración de base de datos respaldados por [Alembic](https://alembic.sqlalchemy.org/).
+
+!!! note "Requiere el extra data-relational"
+ Todos los subcomandos `pyfly db` requieren Alembic (`pyfly[data-relational]`).
+
+### pyfly db init
+
+```
+pyfly db init
+```
+
+Crea `alembic/` y `alembic.ini` en el directorio actual. Sobrescribe
+`alembic/env.py` con una plantilla de PyFly que conecta `async_engine_from_config`
+y `Base.metadata` de `pyfly.data.relational.sqlalchemy`. Finaliza con un error si
+`alembic/` ya existe.
+
+### pyfly db migrate
+
+```
+pyfly db migrate [-m "description"]
+```
+
+Ejecuta `alembic revision --autogenerate`. Compara el `Base.metadata` actual con
+la base de datos en vivo y escribe un nuevo archivo de versión en
+`alembic/versions/`. Requiere `alembic.ini` (ejecuta primero `pyfly db init`).
+
+### pyfly db upgrade / downgrade
+
+```
+pyfly db upgrade [REVISION] # default: head
+pyfly db downgrade REVISION # e.g. -1, base, abc123
+```
+
+### Flujo de trabajo típico de migración
+
+::: listing terminal | Listado D.3 — Ciclo de vida de las migraciones de base de datos
+# 1. Initialise Alembic (once per project)
+pyfly db init
+
+# 2. Generate initial migration from your entity models
+pyfly db migrate -m "initial schema"
+
+# 3. Apply migrations
+pyfly db upgrade
+
+# 4. After modifying entities, generate a new revision
+pyfly db migrate -m "add order status column"
+pyfly db upgrade
+
+# 5. Roll back one step
+pyfly db downgrade -1
+
+# 6. Revert all migrations
+pyfly db downgrade base
+:::
+
+---
+
+## pyfly sbom
+
+Imprime una tabla de Rich con cada dependencia de PyFly junto con las versiones
+requeridas e instaladas. La opción `--json` produce JSON legible por máquina para
+pipelines de cumplimiento normativo.
+
+```
+pyfly sbom
+pyfly sbom --json
+```
+
+---
+
+## Flujo de trabajo de desarrollo típico
+
+::: listing terminal | Listado D.4 — Flujo de trabajo de extremo a extremo, de la configuración al desarrollo
+# Verify environment
+pyfly doctor
+
+# Scaffold the project
+pyfly new lumen --archetype web-api \
+ --features web,data-relational,security
+
+cd lumen
+
+# Check what was installed
+pyfly info
+
+# Initialise migrations
+pyfly db init
+pyfly db migrate -m "initial schema"
+pyfly db upgrade
+
+# Develop with auto-reload
+pyfly run --reload
+
+# Add a new column, migrate, upgrade
+pyfly db migrate -m "add shipment_id to orders"
+pyfly db upgrade
+:::
+
+---
+
+## Resolución de problemas
+
+### Problemas comunes y soluciones
+
+| Síntoma | Causa probable | Solución |
+|---|---|---|
+| `command not found: pyfly` | El PATH no se actualizó tras la instalación | `source ~/.zshrc` (o `~/.bashrc`); o `export PATH="$HOME/.pyfly/bin:$PATH"` |
+| `Python 3.11 found (3.12 required)` | Python antiguo en el PATH | `brew install python@3.12` (macOS) o `sudo apt install python3.12` (Ubuntu) |
+| `ModuleNotFoundError: No module named 'starlette'` | El extra `web` no está instalado | `uv add "pyfly[web]"` o `uv sync --extra web` |
+| `ModuleNotFoundError: No module named 'beanie'` | Falta el extra `data-document` | `uv add "pyfly[data-document]"` |
+| `ModuleNotFoundError: No module named 'sqlalchemy'` | Falta el extra `data-relational` | `uv add "pyfly[data-relational]"` |
+| `alembic is not installed` | Falta Alembic | `uv add "pyfly[data-relational]"` |
+| `No application found` | No hay `pyfly.yaml` ni opción `--app` | Añade `pyfly.app.module: myapp.main:app` a `pyfly.yaml`, o pasa `--app myapp.main:app` |
+| `No ASGI server found` | No hay ningún extra de servidor instalado | `uv add "pyfly[web]"` (añade Uvicorn) |
+| `venv module not found` | Python en paquetes separados (Debian/Ubuntu) | `sudo apt install python3.12-venv` |
+| `Directory 'alembic' already exists` | `db init` ejecutado dos veces | `rm -rf alembic alembic.ini` y vuelve a ejecutar `pyfly db init` |
+| `uv cache clean` arregla instalaciones lentas | Caché de uv corrupta | Ejecuta `uv cache clean` y reintenta |
+| Ctrl+C en `pyfly new` no deja archivos | Modo interactivo cancelado limpiamente | Vuelve a ejecutar `pyfly new`; no hace falta limpiar nada |
+
+### Desinstalación
+
+Para una instalación basada en el instalador (`bash install.sh`):
+
+::: listing terminal | Listado D.5 — Desinstalar PyFly
+# Remove the installation directory
+rm -rf ~/.pyfly
+
+# Remove the PATH line from your shell profile
+# Delete the line: export PATH="$HOME/.pyfly/bin:$PATH" # PyFly Framework
+:::
+
+Para una instalación manual con `uv`/`pip`: `uv remove pyfly` o `pip uninstall pyfly`.
+
+---
+
+## Extender la CLI
+
+La CLI está construida sobre Click. Añade comandos personalizados importando el
+grupo `cli` y llamando a `cli.add_command`:
+
+::: listing myapp/generate.py | Listado D.6 — Añadir un comando de CLI personalizado
+import click
+from pyfly.cli.main import cli
+
+
+@click.command()
+@click.argument("entity_name")
+def generate(entity_name: str) -> None:
+ """Generate boilerplate for a new entity."""
+ click.echo(f"Generating {entity_name} entity ...")
+
+
+cli.add_command(generate, name="generate")
+:::
+
+Registra el módulo del comando en los entry points de tu `pyproject.toml` o
+impórtalo en el `__init__.py` de tu aplicación antes de que se invoque la CLI.
diff --git a/book/manuscript-es/94-glossary.md b/book/manuscript-es/94-glossary.md
new file mode 100644
index 00000000..5a3e1ac7
--- /dev/null
+++ b/book/manuscript-es/94-glossary.md
@@ -0,0 +1,105 @@
+Apéndice
+
+# Glosario {.chtitle}
+
+**Adaptador (adapter)** — Una clase concreta que implementa un puerto delegando en una biblioteca o tecnología de infraestructura específica (PostgreSQL, Redis, Kafka, etc.). Los adaptadores viven en el borde de la arquitectura hexagonal y pueden intercambiarse sin tocar las capas de dominio o de aplicación. En PyFly, la factoría de sesiones asíncronas de SQLAlchemy, `RedisCacheAdapter` y `KafkaMessageBroker` son todos adaptadores (Capítulos 5, 10, 13).
+
+**Raíz de agregado (aggregate root)** — El único punto de entrada a un grupo de objetos de dominio que deben permanecer consistentes entre sí; todos los cambios de estado se canalizan a través de sus métodos, que imponen las invariantes y emiten eventos de dominio. El código externo carga y guarda solo la raíz, nunca sus objetos internos. En PyFly, `AggregateRoot[ID]` es la clase base con estado almacenado; `Wallet` es la raíz de agregado con estado almacenado de Lumen y `LedgerAccount` es su contrapartida con event sourcing (Capítulos 6, 9).
+
+**AOP (Programación Orientada a Aspectos)** — Una técnica para añadir preocupaciones transversales —registro de logs, métricas, comprobaciones de seguridad— de forma declarativa a los métodos sin modificar su código fuente. Los decoradores de aviso `@aspect` y `@before`/`@after`/`@around` de PyFly implementan AOP; el Capítulo 15 lo usa para asociar observabilidad a cada método de servicio.
+
+**ApplicationContext** — El contenedor de inyección de dependencias central que descubre los beans, resuelve las dependencias y gestiona su ciclo de vida desde el arranque hasta el apagado. Dispara `ContextRefreshedEvent` una vez que todos los beans están cableados y `ContextClosedEvent` en un apagado ordenado. `ApplicationContext` es el equivalente en PyFly del `ApplicationContext` de Spring (Capítulo 2).
+
+**Async/await** — La sintaxis nativa de corrutinas de Python para E/S no bloqueante. PyFly está construido de forma nativamente asíncrona: cada manejador HTTP, método de repositorio, llamada al bus y cliente de servicio se declara `async def` y se planifica en el bucle de eventos. Las llamadas bloqueantes dentro de una función `async def` congelan el bucle y deben evitarse (Capítulo 1).
+
+**Autocableado (autowiring)** — El mecanismo por el cual el contenedor de inyección de dependencias resuelve los argumentos del constructor de un bean únicamente a partir de las anotaciones de tipo, sin necesidad de código de factoría. PyFly inspecciona las firmas de `__init__` en el arranque e inyecta automáticamente los beans coincidentes; la anotación `@primary` selecciona la implementación preferida cuando existen varios candidatos (Capítulo 2).
+
+**Bean** — Cualquier objeto Python que el contenedor de inyección de dependencias crea, cablea y gestiona. Declaras una clase como bean aplicando un decorador de estereotipo (`@service`, `@repository`, `@component`, `@configuration` o `@rest_controller`), o anotando un método de factoría con `@bean` dentro de una clase `@configuration` (Capítulo 2).
+
+**BFF (Backend for Frontend)** — Una capa de pasarela de API que se sitúa frente a varios microservicios y compone sus capacidades en una API enfocada al recorrido del usuario, adaptada a un cliente de frontend específico. En el Capítulo 11, el nivel BFF de Lumen agrega los datos del monedero y de los pagos para que la aplicación móvil haga una sola petición en lugar de dos.
+
+**Contexto delimitado (bounded context)** — Un ámbito a nivel de DDD dentro del cual un modelo de dominio tiene un significado único e inequívoco. Los servicios en una arquitectura de microservicios a menudo se corresponden uno a uno con contextos delimitados: `WalletService` posee el modelo del monedero; `PaymentsService` posee el modelo de pagos. Se necesitan núcleos compartidos o capas anticorrupción cuando dos contextos deben intercambiar datos (Capítulo 6).
+
+**Mamparo (bulkhead)** — Un patrón de resiliencia que limita el número de llamadas concurrentes a un recurso o servicio dependiente concreto, evitando que una dependencia lenta agote el pool de hilos o de corrutinas y degrade rutas no relacionadas. El decorador `@bulkhead(max_concurrent=N)` de PyFly implementa el mamparo basado en semáforo (Capítulo 13).
+
+**Cortacircuitos (circuit breaker)** — Un patrón de resiliencia que cuenta los fallos consecutivos hacia una dependencia remota; una vez que se alcanza el umbral de fallos, el cortacircuitos salta al estado abierto y cortocircuita las llamadas posteriores con un error rápido, dando tiempo a la dependencia para recuperarse antes de reanudar las llamadas. El decorador `@circuit_breaker` y `@service_client` de PyFly inyectan este comportamiento automáticamente (Capítulos 11, 13).
+
+**Comando (CQRS)** — Un dataclass inmutable y congelado que expresa una única intención de escritura —«abrir un monedero», «depositar fondos»— y lleva los datos exactos necesarios para satisfacerla. Los comandos heredan de `Command[R]`, donde `R` es el tipo de retorno del manejador, y fluyen a través del `CommandBus`. Opcionalmente pueden implementar `validate()` y `authorize()` (Capítulo 7).
+
+**CommandBus** — La canalización que recibe un `Command`, ejecuta la validación y la autorización, lo despacha al `CommandHandler` coincidente y luego publica cualquier evento de dominio almacenado en búfer por el agregado. Se registra un manejador (handler) por cada tipo de comando; el bus impone esta restricción en el arranque (Capítulo 7).
+
+**Compensación** — Una operación hacia adelante que revierte semánticamente el efecto de un paso de saga completado previamente cuando un paso posterior falla. A diferencia de un rollback de base de datos, la compensación es una nueva escritura que deshace explícitamente el cambio anterior (por ejemplo, «reembolsar pago» compensa «capturar pago»). Cada `@saga_step` nombra su método de compensación (Capítulo 12).
+
+**Component** — Un estereotipo genérico para un bean gestionado que no encaja en los roles más específicos de `@service`, `@repository` o `@rest_controller`. `@component` registra la clase con el contenedor y habilita la inyección, pero no aporta ningún significado semántico adicional (Capítulo 2).
+
+**Clase de configuración** — Una clase decorada con `@configuration` que agrupa métodos de factoría `@bean`. El contenedor la trata como una fuente de definiciones de beans, llamando a cada método de factoría y registrando el valor de retorno como un bean nombrado y tipado. Se pueden aplicar guardas de perfil y anotaciones condicionales a la clase o a métodos de factoría individuales (Capítulo 3).
+
+**Contenedor (DI)** — Véase *ApplicationContext*.
+
+**Convención sobre configuración** — El principio según el cual unos valores predeterminados sensatos eliminan el código repetitivo: una clase anotada con `@service` queda automáticamente con ámbito singleton, es descubierta por el escaneo de componentes e inyectada por tipo sin ningún XML ni registro explícito. PyFly adopta esto como valor de diseño central, exigiendo anulaciones explícitas solo cuando el valor predeterminado es incorrecto (Capítulo 1).
+
+**CQRS (Segregación de Responsabilidad entre Comandos y Consultas)** — Un patrón arquitectónico que separa las operaciones de escritura (comandos) de las operaciones de lectura (consultas) en rutas de código, buses y, potencialmente, modelos de datos distintos. Las lecturas pueden almacenarse en caché de forma independiente de las escrituras; los manejadores pueden probarse de forma aislada; las preocupaciones transversales se aplican uniformemente por el bus respectivo (Capítulo 7).
+
+**Cola de mensajes fallidos (DLQ)** — Una cola o topic de mensajes dedicado que recibe los mensajes que no pudieron procesarse tras el número configurado de reintentos. El `@message_listener` de PyFly enruta automáticamente los mensajes envenenados a la DLQ, evitando que bloqueen los mensajes sanos (Capítulo 10).
+
+**Inyección de dependencias (DI)** — Un patrón de diseño en el que un objeto declara sus colaboradores como parámetros del constructor y un contenedor externo proporciona las instancias concretas. La inyección de dependencias desacopla la construcción del uso, lo que facilita intercambiar implementaciones y probar clases con dobles (fakes) o mocks (Capítulo 2).
+
+**Evento de dominio** — Un registro inmutable de un hecho de negocio que ya ha ocurrido —«monedero abierto», «fondos depositados»—. Los eventos de dominio son producidos por las raíces de agregado mediante `raise_event()`, publicados a través del puerto `EventPublisher` y consumidos por escuchadores independientes. En event sourcing, son además la fuente de verdad del estado del agregado (Capítulos 6, 8, 9).
+
+**DTO (Objeto de Transferencia de Datos)** — Un objeto plano y serializable usado para transportar datos a través del límite de una capa —entre el controlador HTTP y el servicio, o entre un servicio y su cliente de API— sin exponer los tipos internos del dominio. En PyFly, las subclases de `BaseModel` de Pydantic sirven como DTO de petición/respuesta (Capítulo 4).
+
+**EDA (Arquitectura Orientada a Eventos)** — Un estilo arquitectónico en el que los servicios se comunican publicando y suscribiéndose a eventos en lugar de mediante llamadas síncronas directas. Productores y consumidores están desacoplados: un productor no sabe qué consumidores existen. El `EventPublisher` y `@event_listener` de PyFly son las primitivas de EDA intra-proceso; `MessageBrokerPort` extiende el patrón a través de los límites de proceso (Capítulos 8, 10).
+
+**Entidad** — Un objeto de dominio con una identidad estable que persiste a lo largo del tiempo y a través de los cambios de estado. Dos entidades son iguales si y solo si comparten el mismo `id` no nulo. En PyFly, `Entity[TID]` rastrea la identidad; `BaseEntity` añade columnas de auditoría (`created_at`, `updated_at`) para la capa de persistencia (Capítulos 5, 6).
+
+**Event sourcing (abastecimiento de eventos)** — Una estrategia de persistencia en la que cada cambio de estado se almacena como un evento de dominio inmutable en un flujo de solo adición. El estado actual de un agregado se calcula reproduciendo todos los eventos del flujo. El módulo `pyfly.eventsourcing` de PyFly proporciona `AggregateRoot`, `EventStore`, `EventSourcedRepository`, soporte para instantáneas y un `ProjectionRunner` (Capítulo 9).
+
+**EventEnvelope** — El envoltorio de metadatos que empaqueta la carga útil de un evento de dominio para su entrega: ID del evento, tipo de evento, ID del flujo del agregado, número de secuencia, marca de tiempo, ID de correlación e ID de causalidad. Cada evento que llega a un escuchador llega dentro de un `EventEnvelope`; nunca construyes uno manualmente (Capítulos 8, 9).
+
+**EventStore** — La capa de persistencia de solo adición para un sistema con event sourcing. Registra los eventos de dominio indexados por ID de flujo y número de secuencia, impone concurrencia optimista mediante el token `version` y soporta consultas por rango para la reproducción. PyFly incluye `SQLAlchemyEventStore` e `InMemoryEventStore` (Capítulo 9).
+
+**Arquitectura hexagonal** — Un estilo arquitectónico que coloca la lógica de dominio y de aplicación en el centro, rodeada de puertos (interfaces), con adaptadores en los bordes. El código de negocio depende únicamente de los puertos; los adaptadores implementan esos puertos usando tecnologías específicas. Este es el principio organizador de cada módulo de PyFly (Capítulos 1, 2, 5).
+
+**Idempotencia** — La propiedad por la cual realizar la misma operación varias veces produce el mismo resultado que realizarla una sola vez. Los manejadores idempotentes son esenciales en la mensajería y la compensación de sagas: los reintentos de red o las garantías de entrega al-menos-una-vez implican que un mensaje puede llegar más de una vez. Se usan claves de deduplicación o tokens de idempotencia para detectar y descartar ejecuciones duplicadas (Capítulos 10, 12).
+
+**Migración** — Un script versionado y ordenado que hace evolucionar el esquema de una base de datos relacional sin destruir datos. PyFly integra Alembic para la gestión de migraciones; `pyfly db migrate` autogenera una migración a partir de los cambios en las entidades y `pyfly db upgrade` aplica las migraciones pendientes (Capítulo 5).
+
+**Patrón outbox** — Una técnica para publicar eventos de dominio de forma fiable junto con una escritura en la base de datos: tanto el cambio de estado como los registros de eventos se escriben en la misma transacción local; un proceso de retransmisión en segundo plano lee los eventos no enviados de la tabla outbox y los reenvía al broker. Esto elimina el commit en dos fases entre la base de datos y el broker de mensajes (Capítulos 9, 12).
+
+**Puerto (port)** — Una clase `Protocol` de Python que define la interfaz de la que depende una pieza de lógica de negocio, sin especificar ninguna implementación. El contenedor de inyección de dependencias cablea en el arranque el adaptador concreto que satisface el protocolo. Los puertos habilitan la arquitectura hexagonal y hacen que los adaptadores sean intercambiables sin ningún cambio en la lógica de negocio (Capítulos 1, 2, 5).
+
+**Bean primario** — Cuando varios beans satisfacen el mismo tipo, se prefiere para la inyección el que está anotado con `@primary`. Sin una anotación `@primary`, el contenedor lanza un error de ambigüedad. `@primary` es la forma de designar el adaptador de producción entre varias alternativas (Capítulo 2).
+
+**Perfil** — Una etiqueta de activación nombrada que selecciona qué beans y valores de configuración están activos en tiempo de ejecución. PyFly carga `pyfly-{profile}.yaml` sobre el `pyfly.yaml` base y activa los beans anotados con `@profile("prod")` solo cuando `prod` está en la lista de perfiles activos. El perfil activo se establece mediante `PYFLY_PROFILES_ACTIVE` o `pyfly.yaml` (Capítulo 3).
+
+**Proyección** — Un modelo de lectura derivado del consumo de un flujo de eventos. Una proyección se suscribe a tipos de eventos específicos y construye incrementalmente una vista consultable —una caché de saldos, una tabla de auditoría, un agregado para un panel— sin tocar el modelo de escritura. En event sourcing, `ProjectionRunner` reproduce el `EventStore` para reconstruir las proyecciones desde cero (Capítulos 8, 9).
+
+**Consulta (CQRS)** — Un dataclass inmutable que expresa una intención de lectura —«obtener el saldo del monedero», «listar transacciones»—. Las consultas heredan de `Query[R]` y fluyen a través del `QueryBus`, que puede almacenar los resultados en caché de forma transparente. Las consultas nunca mutan el estado (Capítulo 7).
+
+**QueryBus** — La canalización que recibe una `Query`, opcionalmente devuelve un resultado en caché, la despacha al `QueryHandler` coincidente y opcionalmente almacena el resultado en caché. Separar el bus de consultas del bus de comandos permite un comportamiento transversal diferente —caché, enrutamiento a réplicas de lectura— para las rutas de lectura (Capítulo 7).
+
+**Limitador de tasa (rate limiter)** — Un componente de resiliencia que limita el número de peticiones que un endpoint o cliente de servicio puede aceptar dentro de una ventana de tiempo, evitando la sobrecarga por tráfico en ráfagas. El `RateLimiter(max_tokens=N, refill_rate=r)` + `@rate_limiter(limiter)` de PyFly implementa un limitador de cubo de tokens (Capítulo 13).
+
+**Repositorio** — Una abstracción similar a una colección sobre la capa de persistencia que permite a la aplicación cargar y guardar agregados o entidades sin nada de SQL en el código de negocio. El `CrudRepository[E, ID]` de PyFly proporciona `find_by_id`, `save`, `delete` tipados y ayudantes de consultas derivadas; las implementaciones personalizadas anotadas con `@repository` reemplazan a las predeterminadas en memoria (Capítulos 2, 5).
+
+**Reintento (retry)** — Un patrón de resiliencia que vuelve a ejecutar una operación fallida tras un retardo, hasta un número máximo de intentos configurado. Los reintentos manejan fallos transitorios —breves fallos de red, errores 503 momentáneos— sin intervención del operador. El `@retry(max_attempts=N, backoff=...)` de PyFly implementa retroceso exponencial con jitter; `@service_client` incluye reintentos por defecto (Capítulos 11, 13).
+
+**Saga** — Una secuencia de transacciones locales coordinadas por un orquestador central. Cada paso confirma en la base de datos de su propio servicio; si un paso posterior falla, el orquestador llama a la transacción compensatoria de cada paso ya confirmado en orden inverso. Los decoradores `@saga` y `@saga_step` de PyFly implementan el patrón saga orquestado con un DAG de ejecución en paralelo (Capítulo 12).
+
+**Serialización** — El proceso de convertir un objeto en memoria a un formato de transmisión (JSON, Protobuf, Avro) para respuestas HTTP o publicación de mensajes, y la deserialización en sentido inverso. El bean central `PyFlyJsonSerializer` de PyFly (`from pyfly.web import PyFlyJsonSerializer`) configura una vez la serialización JSON respaldada por Pydantic y la aplica a cada respuesta HTTP y a cada envoltorio de mensaje (Capítulos 4, 10).
+
+**Servicio** — Un bean gestionado decorado con `@service` que alberga la lógica de negocio y orquesta las llamadas a repositorios, publicadores de eventos y otros servicios. Los servicios son la capa de aplicación en la arquitectura hexagonal: traducen los comandos entrantes en operaciones de dominio y persisten los resultados (Capítulo 2).
+
+**Instantánea (snapshot)** — Una copia serializada en un instante concreto del estado de un agregado con event sourcing, almacenada junto al flujo de eventos para acelerar la reproducción. Al cargar, el repositorio restaura la instantánea y reproduce solo los eventos ocurridos después de la versión de la instantánea, acotando el tiempo de reproducción independientemente de la longitud del flujo (Capítulo 9).
+
+**Estereotipo** — Un decorador que registra una clase como bean y señala su rol arquitectónico: `@service`, `@repository`, `@component`, `@configuration` o `@rest_controller`. Todos los estereotipos son técnicamente equivalentes en el contenedor; la diferencia semántica es para los lectores humanos y las herramientas (Capítulo 2).
+
+**TCC (Try-Confirm-Cancel)** — Un patrón de transacciones distribuidas en el que cada participante primero *reserva* un recurso (Try), y luego el coordinador o bien *confirma* todas las reservas o las *cancela* en función de si todos los Try tuvieron éxito. TCC es útil cuando se requiere una semántica de reserva exacta e inmediata —por ejemplo, retener fondos antes de capturar un pago—. Los decoradores `@tcc(name="…")` + `@tcc_participant(id="…", order=N)` de PyFly implementan el protocolo TCC junto al motor de sagas (Capítulo 12).
+
+**Testcontainers** — Una biblioteca que arranca contenedores Docker reales (PostgreSQL, Redis, Kafka) para las pruebas de integración y los detiene cuando la suite termina. El módulo `pyfly.testing` de PyFly proporciona los fixtures `postgres_container` y `redis_container` que cablean Testcontainers en el contenedor de inyección de dependencias mediante una configuración al estilo `@ServiceConnection` (Capítulo 16).
+
+**Objeto de valor (value object)** — Un objeto de dominio inmutable identificado por su valor en lugar de por un campo de identidad. Dos objetos de valor son iguales si todos sus campos son iguales. En PyFly, `ValueObject` es la clase base; aplica `@dataclass(frozen=True)` para imponer la inmutabilidad. `Money` —un importe entero en **unidades menores** (céntimos) y un `Currency` `StrEnum`— es el objeto de valor canónico de Lumen; `Wallet` es la raíz de agregado que lo posee (Capítulo 6).
+
+**Webhook** — Una llamada de retorno HTTP entrante que un proveedor externo (Stripe, Twilio, etc.) invoca para notificar a tu servicio de un evento asíncrono, como un cambio en el estado de un pago. El decorador `@webhook_listener` de PyFly verifica la firma HMAC-SHA256, deduplica las repeticiones mediante una caché de nonces y enruta la carga útil a un manejador tipado (Capítulo 17).
+
+**Flujo de trabajo (workflow)** — Una variante de larga duración del patrón saga en la que los pasos pueden pausarse durante minutos, horas o a la espera de aprobación humana antes de reanudarse. Los flujos de trabajo persisten su estado entre pasos para sobrevivir a los reinicios del proceso; los decoradores `@workflow` y `@workflow_step` de PyFly proporcionan esta capacidad sobre el mismo motor de sagas (Capítulo 12).
diff --git a/book/manuscript/00-front/00-dedication.md b/book/manuscript/00-front/00-dedication.md
new file mode 100644
index 00000000..75ae9850
--- /dev/null
+++ b/book/manuscript/00-front/00-dedication.md
@@ -0,0 +1,7 @@
+*For **Jacinto Arias** and the **Taidy** team —*
+
+*for pushing us, again and again, to build a real framework for Python.*
+
+*Because of you there is, at last, **one** way to do things.*
+
+*One. Single. Way. (We give it a week.)*
diff --git a/book/manuscript/00-front/00-preface.md b/book/manuscript/00-front/00-preface.md
index 7d475abc..bfa0b83b 100644
--- a/book/manuscript/00-front/00-preface.md
+++ b/book/manuscript/00-front/00-preface.md
@@ -2,7 +2,7 @@
Enterprise Python has long meant stitching together a dozen independent libraries — one for dependency injection, another for routing, yet another for async database access — with no shared idiom to bind them. **PyFly** changes that. It brings the cohesive, convention-over-configuration experience that Spring Boot gave the Java world, rebuilt from the ground up for Python 3.12+ and `async`/`await`.
-This book teaches PyFly **by doing**. You build one real application from an empty folder to a secured, observable, event-driven service — making every concept concrete before moving to the next. Crucially, the code in these pages is not illustrative pseudocode: it is taken from a **real project that compiles, boots, and passes its tests** against PyFly v26.6.103. Every listing was verified against the running sample, so what you read is what actually works.
+This book teaches PyFly **by doing**. You build one real application from an empty folder to a secured, observable, event-driven service — making every concept concrete before moving to the next. Crucially, the code in these pages is not illustrative pseudocode: it is taken from a **real project that compiles, boots, and passes its tests** against PyFly v26.6.110. Every listing was verified against the running sample, so what you read is what actually works.
### Who This Book Is For
@@ -14,6 +14,7 @@ Spring Boot developers will feel especially at home. Wherever PyFly mirrors a Sp
Every chapter advances **Lumen**, a digital-wallet and ledger service. The journey follows a deliberate arc, one part at a time:
+- **Quick Start — Build Lumen Step by Step.** Before the deep dive, a single guided walkthrough takes you from an empty folder to a running, tested wallet feature — open a wallet, deposit, read the balance over HTTP — so you see the whole shape of a PyFly application before zooming into any one part. Every later chapter then expands one slice of what you built here.
- **Part I — Foundations (Chapters 1–4).** You scaffold the first Lumen service with `pyfly new`, run it under an ASGI server, wire PyFly's dependency-injection container, bind typed configuration and profiles, and expose your first validated REST endpoints.
- **Part II — Modeling & Persisting (Chapters 5–7).** You introduce the repository pattern over a port, persist wallets with async SQLAlchemy (SQLite, no infrastructure required), model the domain with a `Money` value object and a `Wallet` aggregate, and split reads from writes with CQRS command and query handlers dispatched through a bus.
- **Part III — Event-Driven (Chapters 8–10).** The aggregate raises domain events; a listener projects them; an **event-sourced ledger** rebuilds every balance by replaying its event stream; and the same events flow out to Kafka or RabbitMQ for other services.
diff --git a/book/manuscript/00-quickstart.md b/book/manuscript/00-quickstart.md
new file mode 100644
index 00000000..3dd14f10
--- /dev/null
+++ b/book/manuscript/00-quickstart.md
@@ -0,0 +1,965 @@
+Quick Start
+
+# Build Lumen Step by Step {.chtitle}
+
+::: figure art/openers/ch01.svg |
+
+Welcome. This is the very first thing you will build with PyFly, and we are going to take it slowly. By the end of this chapter you will have gone from an *empty folder* to a *running, tested* slice of a real digital-wallet service — opening a wallet, persisting it to a database, reading its balance back over HTTP, and reacting to a domain event. Every concept gets a small, complete piece of code and a "Run it" checkpoint so you can see it working before moving on.
+
+This is a *tour*, not the deep dive. Each step previews a topic that Part I and Part II cover thoroughly later. The goal here is momentum: by the time you reach Chapter 1 you will have already met dependency injection, configuration, HTTP, persistence, CQRS, and events — in the small — and the rest of the book will fill in the *why*.
+
+The application you build is called **Lumen**: a DDD-flavoured digital wallet. A wallet can be opened, deposited to, and withdrawn from, protecting one core rule — **the balance never goes negative** — and modelling money with exact integer arithmetic so there is never any floating-point drift. It is the same application the entire book builds, so nothing you learn here is throwaway.
+
+!!! note "Note"
+ This chapter is written against PyFly **v26.6.110**. Every listing is taken from the real, running `samples/lumen` project that ships with the book — the code compiles, boots, and passes its tests. You will recognise these exact files again, in more depth, in later chapters.
+
+---
+
+## Step 1 — Prerequisites and install
+
+PyFly is a Python framework, and the smoothest way to work with it is through [**uv**](https://docs.astral.sh/uv/), Astral's fast Python package and project manager. uv handles your Python version, your virtual environment, and your dependencies in one tool, and the `pyfly` command-line tool runs through it.
+
+You need two things:
+
+* **Python 3.12 or newer.** PyFly uses modern typing features (`StrEnum`, `X | None` unions, PEP 695 generics).
+* **uv.** Install it once, system-wide.
+
+Install uv with the official one-liner:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh # macOS / Linux
+# Windows (PowerShell):
+# powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+### Run it
+
+Confirm both tools are available:
+
+```bash
+uv --version
+uv python install 3.12 # ensures a 3.12+ interpreter is available
+```
+
+You should see a uv version printed, and uv will report that Python 3.12 is installed (or already present).
+
+!!! tip "Following along with the finished sample"
+ Everything in this chapter exists, finished, in the book's repository under `samples/lumen`. If at any point you want to compare your code with the real thing — or just run it — clone the repo and do:
+
+ ```bash
+ cd samples/lumen
+ uv sync --extra dev # framework + pytest
+ uv run pyfly run --server uvicorn
+ ```
+
+ You can build alongside it, copying one file at a time, or read the finished version when a step is unclear. Both work.
+
+---
+
+## Step 2 — Scaffold the project
+
+PyFly ships a project generator, `pyfly new`, the same way Spring has the Spring Initializr. It writes a conventional project layout so you do not start from a blank page. Because `pyfly` lives inside the framework package, the very first thing we do is create a project directory and add PyFly to it.
+
+For this tour we will build the directories by hand as we go — it keeps every file visible and nothing hidden behind a generator — but the generator is there when you want a head start:
+
+```bash
+pyfly new lumen --archetype hexagonal --features web,data-relational
+```
+
+That command creates a `lumen/` folder, a `pyproject.toml`, a `pyfly.yaml`, and a layered source tree. Let's create the same shape ourselves so you see exactly what each piece is for. Start with the project and its dependencies:
+
+```bash
+mkdir lumen && cd lumen
+uv init --package --name lumen
+uv add "pyfly[cli,web,data-relational]" "pydantic>=2.5"
+uv add --dev "pytest>=8" "pytest-asyncio>=0.24" "httpx>=0.27"
+```
+
+The three PyFly extras you just added map to the three things Lumen needs: `cli` brings the `pyfly` command itself, `web` brings the ASGI server, and `data-relational` brings SQLAlchemy 2 (async) plus `aiosqlite` so we can persist to a SQLite file with no external database to install.
+
+### The project layout
+
+PyFly applications follow a layered structure that separates the public contract, the domain model, the application logic, and the web edge. Create these packages under `src/lumen`:
+
+```
+lumen/
+├── pyproject.toml
+├── pyfly.yaml # framework configuration
+└── src/lumen/
+ ├── interfaces/ # the public contract: DTOs + enums
+ │ ├── dtos/v1/
+ │ └── enums/v1/
+ ├── models/ # the domain model + persistence
+ │ ├── entities/v1/
+ │ └── repositories/
+ ├── core/ # application logic: commands, queries, handlers
+ │ ├── services/
+ │ └── mappers/
+ ├── web/ # the HTTP edge: controllers
+ │ └── controllers/
+ ├── app.py # the application class
+ └── main.py # the ASGI entry point
+```
+
+Each layer has one job. `interfaces` is the boundary other code (and other services) talks to. `models` holds the rich domain objects and the rows they persist as. `core` holds the business operations. `web` exposes them over HTTP. We will fill these in one layer at a time.
+
+!!! spring "Spring parity"
+ `pyfly new` is the equivalent of the Spring Initializr (`start.spring.io`). The `web` and `data-relational` features are the PyFly counterparts of the `spring-boot-starter-web` and `spring-boot-starter-data-jpa` starters — naming a feature pulls in exactly the dependencies and auto-configuration that feature needs, and nothing more.
+
+### The application class
+
+Two files turn a package into a PyFly application. The first, `app.py`, declares the application itself: which packages to scan for components and which framework tiers to switch on.
+
+::: listing lumen/app.py | Listing 0.1 — The application class
+from __future__ import annotations
+
+from pyfly.core import pyfly_application
+from pyfly.starters.domain import enable_domain_stack
+
+
+@enable_domain_stack
+@pyfly_application(
+ name="lumen",
+ version="1.0.0",
+ description="Lumen — a DDD digital-wallet service built on the PyFly framework.",
+ scan_packages=[
+ "lumen.models.repositories",
+ "lumen.core.services.wallets",
+ "lumen.web.controllers",
+ ],
+)
+class LumenApplication:
+ pass
+:::
+
+`@pyfly_application` marks the class as a PyFly app and `scan_packages` tells the dependency-injection container where to look for the components you will declare — your repositories, services, command/query handlers, and controllers. `@enable_domain_stack` switches on the domain tiers we will lean on later: CQRS, the transactional engine, the relational data layer, and events.
+
+### The ASGI entry point
+
+The second file, `main.py`, is what an ASGI server actually imports and serves. It bootstraps PyFly — loads configuration, scans your packages, and builds the application context — then hands the resulting web application to Starlette.
+
+::: listing lumen/main.py | Listing 0.2 — The ASGI entry point
+from __future__ import annotations
+
+from lumen.app import LumenApplication
+from pyfly.core import PyFlyApplication
+from pyfly.web.adapters.starlette import create_app
+
+# Bootstrap: load config, scan packages, build the DI context.
+_pyfly = PyFlyApplication(LumenApplication)
+
+app = create_app(
+ title="lumen",
+ version="1.0.0",
+ description="Lumen — a DDD digital-wallet service built on the PyFly framework.",
+ context=_pyfly.context,
+)
+:::
+
+!!! note "Note"
+ The real `samples/lumen/main.py` adds a `lifespan` hook and a `/static` mount. Those are refinements you will meet in Chapter 4; the two essentials — `PyFlyApplication(LumenApplication)` to bootstrap, and `create_app(...)` to build the web app — are exactly what you see here.
+
+### Configuration
+
+PyFly reads `pyfly.yaml` from the project root. Create one that names the app, sets the HTTP port, and switches on the tiers we need. Everything is nested under a top-level `pyfly` key.
+
+::: listing pyfly.yaml | Listing 0.3 — pyfly.yaml
+pyfly:
+ app:
+ name: lumen
+ version: 1.0.0
+ server:
+ # App on 8080; the actuator + admin default to the management port 9090.
+ port: 8080
+ cqrs:
+ enabled: true
+ transactional:
+ enabled: true
+ eda:
+ provider: memory # in-memory event bus, no broker needed
+ data:
+ relational:
+ enabled: true
+ url: "sqlite+aiosqlite:///./lumen.db"
+ ddl-auto: create # create tables on startup
+:::
+
+A few keys are worth a moment now and a chapter later. `pyfly.server.port` is the application's HTTP port — `8080` by default, exactly like Spring's `server.port`. `data.relational` points at a SQLite file (`lumen.db`) and `ddl-auto: create` tells the framework to create the database schema on startup, so there is no migration step to run for this tour. `eda.provider: memory` gives us an in-process event bus.
+
+!!! warning "Warning"
+ If you are coming from an older PyFly, note that the port key is `pyfly.server.port` (env override `PYFLY_SERVER_PORT`). The old `pyfly.web.port` / `PYFLY_WEB_PORT` were removed — set the port under `pyfly.server` from now on.
+
+### Run it
+
+Even with no endpoints yet, the application boots. Start it:
+
+```bash
+uv run pyfly run --server uvicorn
+```
+
+You will see the PyFly banner, structured startup logs, and a line telling you the server is listening on `http://0.0.0.0:8080`. The `--server uvicorn` flag selects the Uvicorn server (it comes with `pyfly[web]`); for development, add `--reload` to restart automatically when you edit a file.
+
+PyFly also exposes a **health endpoint** so orchestrators can tell the app is alive. Actuator endpoints and the admin dashboard run on a *separate management port*, `9090` by default, which keeps operational endpoints off your public application port. In another terminal:
+
+```bash
+curl -s localhost:9090/actuator/health
+```
+
+```json
+{"status":"UP"}
+```
+
+!!! note "Two ports, on purpose"
+ The application serves your API on `8080`; the **management port** `9090` serves `/actuator/health`, `/actuator/info`, and the admin dashboard. This is Spring Boot's `management.server.port` behaviour. The management port is *open and unauthenticated by default* — fine on a private network, but in production you would set `pyfly.management.security.enabled: true` to lock it down, or `pyfly.management.server.port: -1` to disable management endpoints entirely. By default only `health` and `info` are exposed over HTTP; expose more (metrics, env, …) with `pyfly.management.endpoints.web.exposure.include`.
+
+Stop the server with `Ctrl-C`. The shell is empty, but the foundation is live: the DI container builds, the server starts, and health reporting works. Now we give it something to do.
+
+---
+
+## Step 3 — The first slice of the domain
+
+We start where DDD says to start: with the model. Two objects carry the whole domain — `Money`, a value object for exact amounts, and `Wallet`, the aggregate that owns the balance.
+
+### Money — a value object
+
+`Money` is the textbook *value object*: it has no identity, two instances with the same amount and currency are interchangeable, and it never changes. We store amounts as integer **minor units** (cents) plus an ISO-4217 currency code, so arithmetic is exact — `Money(1050, EUR)` is €10.50, and there is no floating-point rounding to worry about.
+
+First the tiny currency enum it depends on, under `interfaces/enums/v1/`:
+
+::: listing lumen/interfaces/enums/v1/currency.py | Listing 0.4 — The Currency enum
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class Currency(StrEnum):
+ """ISO-4217 currency codes Lumen wallets can hold."""
+
+ EUR = "EUR"
+ USD = "USD"
+ GBP = "GBP"
+:::
+
+Now `Money` itself, under `models/entities/v1/`. It builds on `pyfly.domain.ValueObject` and is a frozen dataclass, so equality is structural and instances are immutable. Arithmetic returns *new* `Money` objects and refuses to mix currencies.
+
+::: listing lumen/models/entities/v1/money.py | Listing 0.5 — The Money value object
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from lumen.interfaces.enums.v1.currency import Currency
+from pyfly.domain import BusinessRuleViolation, ValueObject
+
+
+@dataclass(frozen=True)
+class Money(ValueObject):
+ """An exact monetary amount in a single currency (minor units)."""
+
+ amount: int
+ currency: Currency
+
+ def __post_init__(self) -> None:
+ if not isinstance(self.amount, int) or isinstance(self.amount, bool):
+ raise BusinessRuleViolation(
+ "money-amount-integer", "amount must be an integer number of minor units"
+ )
+
+ @classmethod
+ def zero(cls, currency: Currency) -> Money:
+ """The additive identity for *currency* (a zero balance)."""
+ return cls(amount=0, currency=currency)
+
+ def add(self, other: Money) -> Money:
+ self._assert_same_currency(other)
+ return Money(amount=self.amount + other.amount, currency=self.currency)
+
+ def subtract(self, other: Money) -> Money:
+ self._assert_same_currency(other)
+ return Money(amount=self.amount - other.amount, currency=self.currency)
+
+ @property
+ def is_positive(self) -> bool:
+ return self.amount > 0
+
+ @property
+ def is_negative(self) -> bool:
+ return self.amount < 0
+
+ @property
+ def major_units(self) -> float:
+ """The amount as a major-unit decimal (cents / 100)."""
+ return round(self.amount / 100, 2)
+
+ def _assert_same_currency(self, other: Money) -> None:
+ if self.currency is not other.currency:
+ raise BusinessRuleViolation(
+ "money-currency-mismatch",
+ f"cannot combine {self.currency.value} with {other.currency.value}",
+ )
+:::
+
+`BusinessRuleViolation` is the framework's signal that a domain rule was broken — here, "amounts are whole minor units" and "you cannot add euros to dollars". Notice there is no HTTP, no database, no framework wiring: a value object is pure domain.
+
+### Wallet — the aggregate
+
+The `Wallet` is the *aggregate root*: the object that owns the invariant. State only changes through intent-revealing methods (`open`, `deposit`, `withdraw`), each of which protects the rule **balance never goes negative** and records a *domain event* describing what happened. Built on `pyfly.domain.AggregateRoot`, it raises events with `raise_event(...)`, which we will drain and publish in Step 9.
+
+::: listing lumen/models/entities/v1/wallet_entity.py | Listing 0.6 — The Wallet aggregate and its domain events
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+
+from lumen.interfaces.enums.v1.currency import Currency
+from lumen.models.entities.v1.money import Money
+from pyfly.domain import AggregateRoot, BusinessRuleViolation, DomainEvent
+
+
+@dataclass(frozen=True)
+class WalletOpened(DomainEvent):
+ wallet_id: str = ""
+ owner_id: str = ""
+ currency: str = ""
+
+
+@dataclass(frozen=True)
+class FundsDeposited(DomainEvent):
+ wallet_id: str = ""
+ amount: int = 0
+ currency: str = ""
+ balance: int = 0
+
+
+class Wallet(AggregateRoot[str]):
+ """Wallet aggregate root — owns the ``balance >= 0`` invariant."""
+
+ __slots__ = ("owner_id", "balance", "created_at")
+
+ def __init__(
+ self,
+ id: str,
+ owner_id: str,
+ balance: Money,
+ created_at: datetime | None = None,
+ ) -> None:
+ super().__init__(id)
+ self.owner_id = owner_id
+ self.balance = balance
+ self.created_at = created_at or datetime.now(UTC)
+
+ @property
+ def currency(self) -> Currency:
+ return self.balance.currency
+
+ @classmethod
+ def open(cls, wallet_id: str, owner_id: str, currency: Currency) -> Wallet:
+ """Open a new, empty wallet; raises :class:`WalletOpened`."""
+ if not owner_id.strip():
+ raise BusinessRuleViolation("wallet-owner-required", "owner_id is required")
+ wallet = cls(id=wallet_id, owner_id=owner_id, balance=Money.zero(currency))
+ wallet.raise_event(
+ WalletOpened(wallet_id=wallet_id, owner_id=owner_id, currency=currency.value)
+ )
+ return wallet
+
+ def deposit(self, amount: Money) -> None:
+ """Credit *amount* to the balance; raises :class:`FundsDeposited`."""
+ self._assert_currency(amount)
+ if not amount.is_positive:
+ raise BusinessRuleViolation("wallet-deposit-positive", "deposit amount must be > 0")
+ self.balance = self.balance.add(amount)
+ assert self.id is not None
+ self.raise_event(
+ FundsDeposited(
+ wallet_id=self.id,
+ amount=amount.amount,
+ currency=amount.currency.value,
+ balance=self.balance.amount,
+ )
+ )
+
+ def _assert_currency(self, amount: Money) -> None:
+ if amount.currency is not self.balance.currency:
+ raise BusinessRuleViolation(
+ "wallet-currency-mismatch",
+ f"wallet holds {self.balance.currency.value}, got {amount.currency.value}",
+ )
+:::
+
+::: figure art/figures/06-aggregate.svg | Figure 0.1 — The Wallet aggregate owns its invariant; all state changes go through its methods.
+
+!!! note "Note"
+ The finished `Wallet` in `samples/lumen` also has a `withdraw` method and a `FundsWithdrawn` event, which follow the same shape — we have left them out here to keep this first listing short. Chapter 6 builds the full aggregate.
+
+### Run it
+
+You do not need the server running to exercise the domain. Open a Python REPL inside the project and drive the model directly:
+
+```bash
+uv run python
+```
+
+```python
+>>> from lumen.interfaces.enums.v1.currency import Currency
+>>> from lumen.models.entities.v1.money import Money
+>>> from lumen.models.entities.v1.wallet_entity import Wallet
+>>> w = Wallet.open("wlt-1", "alice", Currency.EUR)
+>>> w.deposit(Money(1500, Currency.EUR))
+>>> w.balance.amount, w.balance.currency.value
+(1500, 'EUR')
+>>> w.deposit(Money(100, Currency.USD)) # wrong currency → rejected
+pyfly.domain.exceptions.BusinessRuleViolation: wallet holds EUR, got USD
+```
+
+The aggregate enforces its own rules in pure Python — no infrastructure required.
+
+---
+
+## Step 4 — Persist it
+
+A wallet that lives only in memory is not much use. We need to save it. PyFly's data layer gives you a *Spring-Data-style repository* over SQLAlchemy, and because we configured SQLite there is no database to install.
+
+### The persistence row
+
+The aggregate is rich; the row it persists as is flat. We map `Wallet` onto a `WalletEntity` — one row per wallet, with the balance split into an integer column (`balance_minor`) and a currency column. It inherits the framework's declarative `Base`, which lets it keep the aggregate's own string id as its primary key.
+
+::: listing lumen/models/entities/v1/wallet_orm.py | Listing 0.7 — The WalletEntity persistence row
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from sqlalchemy import String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from pyfly.data.relational.sqlalchemy import Base
+
+
+class WalletEntity(Base):
+ """One persisted wallet row, keyed by the aggregate's own string id."""
+
+ __tablename__ = "wallets"
+
+ id: Mapped[str] = mapped_column(String(64), primary_key=True)
+ owner_id: Mapped[str] = mapped_column(String(255), nullable=False, index=True)
+ currency: Mapped[str] = mapped_column(String(3), nullable=False)
+ balance_minor: Mapped[int] = mapped_column(nullable=False, default=0)
+ created_at: Mapped[datetime] = mapped_column(default=lambda: datetime.now(UTC))
+:::
+
+Because the class subclasses `Base`, importing it registers the `wallets` table; with `ddl-auto: create` the framework creates that table on startup.
+
+### The repository
+
+Instead of hand-writing SQL, you subclass the framework's generic `Repository[Entity, IdType]`. That single declaration tells the framework the entity type and the primary-key type, and in return you get the full async repository surface for free — `save`, `find_by_id`, `find_all`, `count`, `delete`, paging, and more — with the database session injected for you.
+
+::: listing lumen/models/repositories/wallet_repository.py | Listing 0.8 — A Spring-Data-style repository
+from __future__ import annotations
+
+from lumen.models.entities.v1.wallet_orm import WalletEntity
+from pyfly.container import repository
+from pyfly.data.relational.sqlalchemy import Repository
+
+
+@repository
+class WalletRepository(Repository[WalletEntity, str]):
+ """CRUD for :class:`WalletEntity`, plus a convenience upsert."""
+
+ async def find_by_owner_id(self, owner_id: str) -> list[WalletEntity]:
+ """All wallets owned by *owner_id* (derived query stub)."""
+ ...
+
+ async def upsert(self, entity: WalletEntity) -> WalletEntity:
+ """Insert *entity*, or update the row with the same id."""
+ session = self._require_session()
+ merged = await session.merge(entity)
+ await session.flush()
+ return merged
+:::
+
+Two things here are pure Spring Data. `find_by_owner_id` is a **derived query** — its body is an elided stub (`...`), and at startup the framework parses the method *name* and compiles a real `SELECT … WHERE owner_id = :owner_id` for you. `upsert` is a small convenience over `session.merge` so a handler can persist a wallet whether it is new or already exists, with a single call.
+
+The `@repository` decorator registers the class as a managed component — a *bean* in the DI container — so it can be injected into the handlers we write next.
+
+::: figure art/figures/05-repository.svg | Figure 0.2 — A framework Repository turns a typed declaration into a full CRUD surface.
+
+!!! spring "Spring parity"
+ `Repository[WalletEntity, str]` is the direct analogue of Spring Data's `JpaRepository`. You declare the interface; the framework provides the implementation. Derived queries (`findByOwnerId` in Spring, `find_by_owner_id` here) are parsed from the method name in exactly the same way.
+
+---
+
+## Step 5 — A write path with CQRS
+
+Now we wire the model to the repository through a *command*. PyFly uses **CQRS** — Command Query Responsibility Segregation — which means writes flow through one path (commands) and reads through another (queries). A command is a small, immutable object describing intent; a handler executes it.
+
+### The command
+
+`OpenWallet` carries the data needed to open a wallet and validates itself before anything runs. It is a frozen dataclass extending `Command[str]` — the `str` says "this command, when handled, produces a wallet id".
+
+::: listing lumen/core/services/wallets/open_wallet_command.py | Listing 0.9 — The OpenWallet command
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from lumen.interfaces.enums.v1.currency import Currency
+from pyfly.cqrs import Command, ValidationResult
+
+
+@dataclass(frozen=True)
+class OpenWallet(Command[str]):
+ """Open a new wallet. Returns the generated wallet id."""
+
+ owner_id: str
+ currency: Currency
+
+ async def validate(self) -> ValidationResult: # type: ignore[override]
+ if not self.owner_id.strip():
+ return ValidationResult.failure("owner_id", "Owner id is required")
+ return ValidationResult.success()
+:::
+
+### The handler
+
+The handler is where the work happens: generate an id, create the `Wallet` aggregate, persist it through the repository, then drain and publish the aggregate's events. It runs inside `@transactional()`, which opens a unit of work, commits on success, and rolls back on failure. The repository and the event publisher are injected by the container — you only declare them in `__init__`.
+
+::: listing lumen/core/services/wallets/open_wallet_handler.py | Listing 0.10 — The OpenWallet handler
+from __future__ import annotations
+
+from uuid import uuid4
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from lumen.core.mappers.wallet_mapper import to_entity
+from lumen.core.services.wallets.event_publishing import publish_domain_events
+from lumen.core.services.wallets.open_wallet_command import OpenWallet
+from lumen.models.entities.v1.wallet_entity import Wallet
+from lumen.models.repositories.wallet_repository import WalletRepository
+from pyfly.container import service
+from pyfly.cqrs import CommandHandler, command_handler
+from pyfly.data.relational.sqlalchemy import transactional
+from pyfly.eda import EventPublisher
+
+
+@command_handler
+@service
+class OpenWalletHandler(CommandHandler[OpenWallet, str]):
+ """Open a new, empty wallet."""
+
+ def __init__(
+ self,
+ repository: WalletRepository,
+ events: EventPublisher,
+ session_factory: async_sessionmaker[AsyncSession],
+ ) -> None:
+ super().__init__()
+ self._repository = repository
+ self._events = events
+ self._session_factory = session_factory
+
+ @transactional()
+ async def do_handle(self, command: OpenWallet) -> str: # type: ignore[override]
+ wallet_id = f"wlt-{uuid4()}"
+ wallet = Wallet.open(
+ wallet_id=wallet_id,
+ owner_id=command.owner_id,
+ currency=command.currency,
+ )
+ await self._repository.upsert(to_entity(wallet))
+ await publish_domain_events(self._events, wallet.clear_events())
+ return wallet_id
+:::
+
+The handler calls `to_entity(wallet)` — a small mapper that flattens the aggregate into a `WalletEntity` row. Create it under `core/mappers/`. (We will add the read-side projection it also needs in the next step.)
+
+::: listing lumen/core/mappers/wallet_mapper.py | Listing 0.11 — Mapping the aggregate to its row
+from __future__ import annotations
+
+from lumen.models.entities.v1.wallet_entity import Wallet
+from lumen.models.entities.v1.wallet_orm import WalletEntity
+
+
+def to_entity(wallet: Wallet) -> WalletEntity:
+ """Flatten a :class:`Wallet` aggregate into a persistable row."""
+ assert wallet.id is not None
+ return WalletEntity(
+ id=wallet.id,
+ owner_id=wallet.owner_id,
+ currency=wallet.currency.value,
+ balance_minor=wallet.balance.amount,
+ created_at=wallet.created_at,
+ )
+:::
+
+::: figure art/figures/07-cqrs.svg | Figure 0.3 — A command flows through the bus to its handler; queries take a separate path.
+
+!!! spring "Spring parity"
+ `@command_handler` + `@service` registers a handler the command bus dispatches to — much like a Spring `@Service` whose method handles a request. `@transactional()` is the PyFly counterpart of Spring's `@Transactional`: it manages the unit of work so the persist either fully commits or fully rolls back.
+
+---
+
+## Step 6 — A read path
+
+Reads take the other lane. A *query* asks a question; a *query handler* answers it, typically projecting a database row onto a small, purpose-built DTO. We will read just the balance.
+
+### The DTO and the query
+
+The balance response is a tiny Pydantic model under `interfaces/dtos/v1/`:
+
+::: listing lumen/interfaces/dtos/v1/balance_dto.py | Listing 0.12 — The BalanceDto response model
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from lumen.interfaces.enums.v1.currency import Currency
+
+
+class BalanceDto(BaseModel):
+ """Lightweight balance projection for the balance endpoint."""
+
+ id: str
+ currency: Currency
+ balance_minor: int
+ balance: float
+:::
+
+The query carries just the wallet id and declares it returns a `BalanceDto` or `None`:
+
+::: listing lumen/core/services/wallets/get_balance_query.py | Listing 0.13 — The GetBalance query
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from lumen.interfaces.dtos.v1.balance_dto import BalanceDto
+from pyfly.cqrs import Query
+
+
+@dataclass(frozen=True)
+class GetBalance(Query[BalanceDto | None]):
+ """Look up just the balance of a wallet by its identifier."""
+
+ wallet_id: str
+:::
+
+### The handler and the projection
+
+Add the read-side mapper to `wallet_mapper.py` — a small function that projects a row onto the DTO, computing the major-unit balance:
+
+::: listing lumen/core/mappers/wallet_mapper.py | Listing 0.14 — Projecting a row onto the balance DTO
+from __future__ import annotations
+
+from lumen.interfaces.dtos.v1.balance_dto import BalanceDto
+from lumen.interfaces.enums.v1.currency import Currency
+from lumen.models.entities.v1.wallet_orm import WalletEntity
+
+
+def entity_to_balance_dto(entity: WalletEntity) -> BalanceDto:
+ """Project a persisted row onto the lightweight balance DTO."""
+ return BalanceDto(
+ id=entity.id,
+ currency=Currency(entity.currency),
+ balance_minor=entity.balance_minor,
+ balance=round(entity.balance_minor / 100, 2),
+ )
+:::
+
+The query handler loads the row by id and projects it — returning `None` when there is no such wallet:
+
+::: listing lumen/core/services/wallets/get_balance_handler.py | Listing 0.15 — The GetBalance handler
+from __future__ import annotations
+
+from lumen.core.mappers.wallet_mapper import entity_to_balance_dto
+from lumen.core.services.wallets.get_balance_query import GetBalance
+from lumen.interfaces.dtos.v1.balance_dto import BalanceDto
+from lumen.models.repositories.wallet_repository import WalletRepository
+from pyfly.container import service
+from pyfly.cqrs import QueryHandler, query_handler
+
+
+@query_handler
+@service
+class GetBalanceHandler(QueryHandler[GetBalance, BalanceDto | None]):
+ def __init__(self, repository: WalletRepository) -> None:
+ super().__init__()
+ self._repository = repository
+
+ async def do_handle(self, query: GetBalance) -> BalanceDto | None: # type: ignore[override]
+ entity = await self._repository.find_by_id(query.wallet_id)
+ return entity_to_balance_dto(entity) if entity is not None else None
+:::
+
+Notice the asymmetry CQRS gives you: the write side rehydrates the full aggregate to protect invariants; the read side touches only the columns the balance view needs and never constructs an aggregate at all. Each side is shaped for its own job.
+
+---
+
+## Step 7 — Expose it over HTTP
+
+The domain works, it persists, and it has write and read paths. Now we put a web edge on it. A **controller** maps HTTP requests onto commands and queries and dispatches them through the bus — it holds no business logic of its own.
+
+First the request DTO for opening a wallet, under `interfaces/dtos/v1/`:
+
+::: listing lumen/interfaces/dtos/v1/open_wallet_request.py | Listing 0.16 — The OpenWalletRequest payload
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from lumen.interfaces.enums.v1.currency import Currency
+
+
+class OpenWalletRequest(BaseModel):
+ """Wallet-opening request payload."""
+
+ owner_id: str = Field(min_length=1, max_length=64, description="Identifier of the wallet owner")
+ currency: Currency = Field(default=Currency.EUR, description="ISO-4217 currency the wallet holds")
+:::
+
+Now the controller, under `web/controllers/`. The DI container injects the command and query buses; each handler builds a command or query and `await`s it on the bus. Parameter annotations declare where data comes from: `Valid[Body[...]]` binds and validates the JSON body, `PathVar[str]` binds a URL segment.
+
+::: listing lumen/web/controllers/wallet_controller.py | Listing 0.17 — The wallet controller
+from __future__ import annotations
+
+from lumen.core.services.wallets.get_balance_query import GetBalance
+from lumen.core.services.wallets.open_wallet_command import OpenWallet
+from lumen.interfaces.dtos.v1.balance_dto import BalanceDto
+from lumen.interfaces.dtos.v1.open_wallet_request import OpenWalletRequest
+from pyfly.container import rest_controller
+from pyfly.cqrs import DefaultCommandBus, DefaultQueryBus
+from pyfly.kernel import ResourceNotFoundException
+from pyfly.web import Body, PathVar, Valid, get_mapping, post_mapping, request_mapping
+
+
+@rest_controller
+@request_mapping("/api/v1/wallets")
+class WalletController:
+ """Digital-wallet REST API: open a wallet, read its balance."""
+
+ def __init__(self, commands: DefaultCommandBus, queries: DefaultQueryBus) -> None:
+ self._commands = commands
+ self._queries = queries
+
+ @post_mapping("", status_code=201)
+ async def open_wallet(self, request: Valid[Body[OpenWalletRequest]]) -> dict[str, str]:
+ wallet_id = await self._commands.send(
+ OpenWallet(owner_id=request.owner_id, currency=request.currency)
+ )
+ return {"wallet_id": wallet_id}
+
+ @get_mapping("/{wallet_id}/balance")
+ async def wallet_balance(self, wallet_id: PathVar[str]) -> BalanceDto:
+ result = await self._queries.query(GetBalance(wallet_id=wallet_id))
+ if result is None:
+ raise ResourceNotFoundException(
+ f"Wallet {wallet_id!r} not found",
+ code="WALLET_NOT_FOUND",
+ context={"wallet_id": wallet_id},
+ )
+ return result
+:::
+
+::: figure art/figures/04-request.svg | Figure 0.4 — A request binds to a handler, which dispatches a command or query through the bus.
+
+### Run it
+
+Start the server:
+
+```bash
+uv run pyfly run --server uvicorn
+```
+
+In another terminal, open a wallet:
+
+```bash
+curl -s -X POST localhost:8080/api/v1/wallets \
+ -H 'content-type: application/json' \
+ -d '{"owner_id":"alice","currency":"EUR"}'
+```
+
+```json
+{"wallet_id":"wlt-7d2c1a9e-..."}
+```
+
+Read the balance back (substitute the id you got above):
+
+```bash
+curl -s localhost:8080/api/v1/wallets/wlt-7d2c1a9e-.../balance
+```
+
+```json
+{"id":"wlt-7d2c1a9e-...","currency":"EUR","balance_minor":0,"balance":0.0}
+```
+
+A freshly opened wallet has a zero balance — exactly what `Money.zero(EUR)` produced back in the aggregate's `open` factory. The request travelled from HTTP, through the command bus, into the handler, through the repository, to SQLite, and back out the read path. That is the whole arc, end to end.
+
+!!! tip "Interactive docs for free"
+ While the server runs, open `http://localhost:8080/docs` in a browser. PyFly generated an OpenAPI document and a Swagger UI from your controller and DTOs — you can try the endpoints right there, no extra code.
+
+---
+
+## Step 8 — Prove it with a test
+
+Running `curl` by hand is fine once; a test proves it forever. PyFly is designed to be testable without a running server — you can dispatch commands and queries straight through the buses. Write a test under `tests/`:
+
+::: listing tests/test_quickstart.py | Listing 0.18 — An end-to-end test through the buses
+from __future__ import annotations
+
+import pytest
+from lumen.core.services.wallets.get_balance_query import GetBalance
+from lumen.core.services.wallets.open_wallet_command import OpenWallet
+from lumen.interfaces.enums.v1.currency import Currency
+
+from pyfly.cqrs import DefaultCommandBus, DefaultQueryBus
+
+
+@pytest.mark.asyncio
+async def test_open_wallet_then_read_balance(
+ command_bus: DefaultCommandBus,
+ query_bus: DefaultQueryBus,
+) -> None:
+ wallet_id = await command_bus.send(OpenWallet(owner_id="alice", currency=Currency.EUR))
+ assert wallet_id.startswith("wlt-")
+
+ balance = await query_bus.query(GetBalance(wallet_id=wallet_id))
+ assert balance is not None
+ assert balance.balance_minor == 0
+ assert balance.currency is Currency.EUR
+:::
+
+The `command_bus` and `query_bus` parameters are *fixtures*: they boot the application context once and hand you wired buses, the same components the controller uses in production. (The finished `samples/lumen/tests/conftest.py` defines these fixtures; copy it when you build your own suite — Chapter 16 explains it in full.)
+
+### Run it
+
+```bash
+uv run --extra dev pytest -q
+```
+
+```
+. [100%]
+1 passed in 0.42s
+```
+
+Green. You now have a wallet feature that is not just running but *verified* — the same test runs in CI on every change.
+
+!!! spring "Spring parity"
+ Dispatching through the buses in a test mirrors Spring Boot's slice tests: you exercise real wired beans without standing up the HTTP server. The `command_bus` / `query_bus` fixtures are the PyFly equivalent of an injected Spring `ApplicationContext` in an `@SpringBootTest`.
+
+---
+
+## Step 9 — A taste of events
+
+The aggregate has been recording domain events all along — `WalletOpened`, `FundsDeposited` — and the handler drains them with `wallet.clear_events()` and publishes them. So far nothing has *listened*. Let's add a small listener that reacts.
+
+First, the publishing bridge the handler already imports. It turns each drained domain event into a payload and publishes it on the event bus, under `core/services/wallets/`:
+
+::: listing lumen/core/services/wallets/event_publishing.py | Listing 0.19 — Publishing drained domain events
+from __future__ import annotations
+
+import dataclasses
+from collections.abc import Iterable
+from typing import Any
+
+from lumen.core.services.listeners.wallet_audit_listener import WALLET_EVENTS_DESTINATION
+from pyfly.domain import DomainEvent
+from pyfly.eda import EventPublisher
+
+
+def _to_payload(event: DomainEvent) -> dict[str, Any]:
+ """Flatten a frozen-dataclass domain event into a JSON-friendly dict."""
+ payload: dict[str, Any] = dataclasses.asdict(event)
+ payload.setdefault("event_type", event.event_type)
+ return payload
+
+
+async def publish_domain_events(publisher: EventPublisher, events: Iterable[DomainEvent]) -> None:
+ """Publish each drained domain event on the wallet events channel."""
+ for event in events:
+ await publisher.publish(
+ destination=WALLET_EVENTS_DESTINATION,
+ event_type=event.event_type,
+ payload=_to_payload(event),
+ )
+:::
+
+Now the listener, under `core/services/listeners/`. It is a plain `@service` whose method is stamped `@event_listener`; at startup PyFly discovers it and subscribes it to the bus — no wiring by hand. Here it keeps a tiny in-memory audit log and a running total per wallet.
+
+::: listing lumen/core/services/listeners/wallet_audit_listener.py | Listing 0.20 — A domain-event listener
+from __future__ import annotations
+
+from pyfly.container import service
+from pyfly.eda import EventEnvelope, event_listener
+
+# The logical channel the wallet handlers publish domain events to.
+WALLET_EVENTS_DESTINATION = "wallet.events"
+
+
+@service
+class WalletAuditListener:
+ """In-memory audit log + running-total projection over wallet events."""
+
+ def __init__(self) -> None:
+ self._running_totals: dict[str, int] = {}
+
+ @event_listener(event_types=["WalletOpened", "FundsDeposited"])
+ async def on_wallet_event(self, envelope: EventEnvelope) -> None:
+ payload = dict(envelope.payload)
+ wallet_id = str(payload.get("wallet_id", ""))
+ if envelope.event_type == "WalletOpened":
+ self._running_totals.setdefault(wallet_id, 0)
+ elif envelope.event_type == "FundsDeposited":
+ amount = int(payload.get("amount", 0))
+ self._running_totals[wallet_id] = self._running_totals.get(wallet_id, 0) + amount
+
+ def running_total(self, wallet_id: str) -> int:
+ """Net funds for *wallet_id*, in minor units."""
+ return self._running_totals.get(wallet_id, 0)
+:::
+
+Add the listeners package to `scan_packages` in `app.py` so the container discovers it:
+
+```python
+scan_packages=[
+ "lumen.models.repositories",
+ "lumen.core.services.wallets",
+ "lumen.core.services.listeners", # <-- add this
+ "lumen.web.controllers",
+],
+```
+
+::: figure art/figures/08-eda.svg | Figure 0.5 — A handler publishes domain events; listeners subscribe and react, decoupled from the command.
+
+### Run it
+
+Open a wallet, then deposit, and the listener's running total updates as a side effect of those commands — without the command knowing the listener exists. That decoupling is the whole point of events: you add reactions (audit logs, notifications, projections) without touching the code that triggered them.
+
+!!! spring "Spring parity"
+ `@event_listener` is the PyFly counterpart of Spring's `@EventListener`. Publishing through an `EventPublisher` and subscribing with a stamped method is the same publish/subscribe model as Spring's `ApplicationEventPublisher` and `@EventListener`-annotated beans.
+
+---
+
+## What you built {.recap}
+
+You just built — and tested — a real vertical slice of a service: a domain model, a database, a write path, a read path, an HTTP edge, and an event reaction. Every one of those was a *preview*. The rest of the book takes each one apart and rebuilds it properly, with the reasoning, the alternatives, and the production details.
+
+Here is the map from what you just did to the chapter that goes deep:
+
+| In this Quick Start you… | Goes deep in |
+|---|---|
+| Saw the container build and inject your beans (`@repository`, `@service`) | **Chapter 2** — Dependency Injection & the Application Context |
+| Configured the app with `pyfly.yaml` and the management port | **Chapter 3** — Configuration, Profiles & Secrets |
+| Exposed an HTTP API with `@rest_controller`, binding, and validation | **Chapter 4** — Your First HTTP API |
+| Persisted with a framework `Repository` over SQLAlchemy/SQLite | **Chapter 5** — Persistence & the Repository Pattern |
+| Modelled `Money`, `Wallet`, invariants, and domain events | **Chapter 6** — Domain-Driven Design |
+| Split writes and reads with commands, queries, and the bus | **Chapter 7** — CQRS: Commands & Queries |
+| Published and reacted to domain events with `@event_listener` | **Chapter 8** — Domain Events & Event-Driven Architecture |
+| (Next) rebuilt state from an event log | **Chapter 9** — Event Sourcing the Ledger |
+| (Next) called other services and split the monolith | **Chapters 11–12** — HTTP Clients, the BFF & Sagas |
+| (Next) secured, observed, and shipped it | **Chapters 14–18** — Security, Observability, Testing & Production |
+
+When you are ready for the *why* behind all of it, turn the page to Chapter 1.
+
+---
+
+## Try it yourself {.exercises}
+
+If you want to keep moving on your own first, three small extensions build directly on what you have:
+
+1. **Add a deposit endpoint.** You already have the `FundsDeposited` event and the aggregate's `deposit` method. Add a `DepositFunds` command + handler (model them on `OpenWallet`), a `POST /{wallet_id}/deposit` route, and watch the listener's running total climb.
+2. **Add a `withdraw` path** that refuses to overdraw — the aggregate's `balance >= 0` invariant should reject it, and your handler should surface that as a clean error. Add a `FundsWithdrawn` domain event that mirrors the `FundsDeposited` event shown in Listing 0.6.
+3. **Write a test for the listener**, asserting that opening a wallet and depositing leaves the expected running total — proving the event path end to end.
diff --git a/book/manuscript/01-why-pyfly.md b/book/manuscript/01-why-pyfly.md
index 5f27b4e6..aed79479 100644
--- a/book/manuscript/01-why-pyfly.md
+++ b/book/manuscript/01-why-pyfly.md
@@ -49,25 +49,46 @@ Every layer follows the same **hexagonal architecture** principle: your code liv
To make these ideas concrete, you will build **Lumen** — a fintech wallet platform — throughout the book. Lumen starts simply: a REST API that records ledger entries and reports wallet balances. By the final chapter it will span multiple services communicating over events, with sagas coordinating cross-service transfers. Starting with a well-structured skeleton saves you the pain of retrofitting architecture later, so PyFly's scaffolder generates that structure for you up front.
-First, verify you have Python 3.12 or later and [uv](https://docs.astral.sh/uv/) (PyFly's recommended package manager):
+We will take this one short step at a time. Nothing here assumes prior PyFly experience — if you can run a command in a terminal, you can follow along.
-::: listing terminal | Listing 1.1 — Verify prerequisites and scaffold Lumen
+!!! note "New term: uv"
+ [uv](https://docs.astral.sh/uv/) is a fast Python package manager and project runner (think `pip` + `virtualenv` + a task runner, rolled into one binary). PyFly recommends it, and every command in this book that starts with `uv run` simply means "run this inside the project's virtual environment". If you have only ever used `pip`, you lose nothing — uv reads the same standard `pyproject.toml`.
+
+**Step 1 — Check your prerequisites.** PyFly targets Python 3.12+ and uses uv. Confirm both are installed:
+
+::: listing terminal | Listing 1.1 — Verify prerequisites
python --version
# Python 3.12.0 or later
uv --version
# uv 0.5.0 or later
+:::
+
+If either command is missing or reports an older version, install it before continuing (uv's install instructions are one short script on its website). Everything else PyFly needs, it pulls in for you.
+
+**Step 2 — Scaffold the project.** A single command generates a complete, production-shaped project directory:
-# Scaffold the Lumen wallet service (web-api archetype, web feature)
+::: listing terminal | Listing 1.2 — Scaffold the Lumen wallet service
+# web-api archetype, web feature
uv run pyfly new lumen --archetype web-api --features web
+:::
+
+!!! note "New term: scaffold / archetype"
+ To *scaffold* is to generate a ready-made project skeleton so you start from working code instead of an empty folder. An *archetype* is the template that scaffolding uses — `web-api` is the REST-service template. The `--features web` flag adds the ASGI server dependency (the piece that actually accepts HTTP requests). `uv run pyfly new` calls PyFly's archetype registry and writes the whole directory in one shot.
+**Step 3 — Move into the project and install dependencies.**
+
+::: listing terminal | Listing 1.3 — Enter the project and sync dependencies
cd lumen
# Install dependencies (including the pyfly CLI and ASGI server)
uv sync
:::
-`uv run pyfly new` calls the PyFly archetype registry and generates a production-shaped project directory in one shot. The `--archetype web-api` flag selects the REST service template; `--features web` adds the ASGI server dependency. `uv sync` installs the declared dependencies, including the `pyfly` command itself (available via the `cli` extra in `pyproject.toml`).
+`uv sync` reads the declared dependencies from `pyproject.toml` and installs them into a project-local virtual environment — including the `pyfly` command itself (available via the `cli` extra). The first sync downloads packages; subsequent syncs are near-instant because uv caches everything.
+
+!!! tip "Run it: confirm the CLI works"
+ From the project root, run `uv run pyfly --help`. You should see the PyFly command list (`new`, `run`, and friends). If that prints, your toolchain is healthy and you are ready to inspect the generated project.
!!! tip "Tip"
Run `pyfly new` **without arguments** to enter interactive mode. It walks you through archetype and feature selection with arrow-key navigation — handy when you want to pre-select extras like relational data or messaging support.
@@ -114,9 +135,12 @@ The apparent simplicity is deliberate. `pyproject.toml` gives you a standards-co
Understanding the scaffold's entry-point structure early will save you confusion later. The scaffold generates two files that work together: `app.py` declares the application and `main.py` exposes the ASGI `app` that the server imports. Each has a distinct responsibility.
-Open `src/lumen/app.py`:
+!!! note "New term: ASGI"
+ *ASGI* (Asynchronous Server Gateway Interface) is the standard contract between a Python web server and an async web application — the modern, async successor to WSGI. You do not have to implement it; PyFly hands the server a ready-made ASGI `app` object. Just remember: the *server* (Uvicorn or Granian) speaks ASGI to your *app*.
-::: listing lumen/app.py | Listing 1.2 — Application declaration (@pyfly_application)
+**Step 1 — Open the application declaration.** Look at `src/lumen/app.py`:
+
+::: listing lumen/app.py | Listing 1.4 — Application declaration (@pyfly_application)
from pyfly.core import pyfly_application
@@ -139,9 +163,12 @@ Short as it is, every parameter pulls its weight:
The `Application` class body is intentionally empty. You never instantiate it yourself — `PyFlyApplication` does that during startup: it loads configuration from `pyfly.yaml`, configures structured logging, prints the startup banner, scans packages, initialises the `ApplicationContext`, and logs startup timing.
-Now open `src/lumen/main.py`:
+!!! note "New terms: DI and the ApplicationContext"
+ *Dependency injection* (DI) means a class declares what it needs in its constructor and the framework supplies those collaborators, rather than the class building them itself. The *ApplicationContext* (often just "the container") is the registry that holds every wired object — PyFly calls each one a *bean*, the same term Spring uses. `scan_packages` is what populates it.
+
+**Step 2 — Open the ASGI entry point.** Now look at `src/lumen/main.py`:
-::: listing lumen/main.py | Listing 1.3 — ASGI entry point (main.py)
+::: listing lumen/main.py | Listing 1.5 — ASGI entry point (main.py)
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager
@@ -182,15 +209,18 @@ app = create_app(
This is the file that `pyfly run` (and any ASGI server like Uvicorn) discovers. The module-level `app` object is a Starlette application: `create_app` mounts every `@rest_controller` found in the DI context and wires the lifespan hook so startup and shutdown happen cleanly. The `@pyfly_application` decorator alone does **not** create the ASGI `app` — `main.py` is the explicit bridge between the DI world (`app.py`) and the HTTP world.
+!!! note "What just happened"
+ Two small files split one job in two. `app.py` answers *what is this application and where does its code live* (name, version, scan packages). `main.py` answers *how does a web server reach it* — it bootstraps PyFly into an `ApplicationContext`, then exposes a single ASGI `app` object. When you later add a controller or service, you edit neither file: you just drop the new class into one of the scanned packages and PyFly wires it on the next boot.
+
---
## Project files
The other two files you will edit most often are `pyproject.toml` and `pyfly.yaml`. Each plays a distinct role: `pyproject.toml` manages dependencies, while `pyfly.yaml` owns every runtime knob.
-`pyproject.toml` records the project's dependencies. Notice the extras:
+**Step 1 — Read the dependency manifest.** `pyproject.toml` records the project's dependencies. Notice the extras:
-::: listing lumen/pyproject.toml | Listing 1.4 — pyproject.toml (key sections)
+::: listing lumen/pyproject.toml | Listing 1.6 — pyproject.toml (key sections)
[project]
name = "lumen-demo"
version = "0.1.0"
@@ -210,21 +240,22 @@ dev = [
]
:::
+!!! note "New term: extras"
+ An *extra* is an optional bundle of dependencies named in square brackets — `pyfly[web]` means "install PyFly plus its `web` optional group". Extras keep your install lean: you pull in a database driver, a CLI, or a faster server only when you actually use it.
+
The `web` extra in `pyfly[web]` bundles Uvicorn together with the ASGI adapter. The `cli` extra (add it when you need the `pyfly` command outside of `uv run`) provides the command-line tooling. Other extras — `data-relational`, `granian` — are opt-in; you add them only when a feature needs them. The Lumen wallet sample, for example, declares `pyfly[cli,web,data-relational]` because it connects to SQLite.
-`pyfly.yaml` is where all runtime settings live:
+**Step 2 — Read the runtime configuration.** `pyfly.yaml` is where all runtime settings live:
-::: listing lumen/pyfly.yaml | Listing 1.5 — pyfly.yaml (scaffold default)
+::: listing lumen/pyfly.yaml | Listing 1.7 — pyfly.yaml (scaffold default)
pyfly:
app:
name: lumen-demo
+ version: 0.1.0
module: lumen_demo.main:app
- web:
- port: 8080
- adapter: auto
-
server:
+ port: 8080
type: "auto"
event-loop: "auto"
workers: 0
@@ -241,7 +272,13 @@ pyfly:
root: INFO
:::
-The `module` key tells `pyfly run` exactly where the ASGI `app` lives — `lumen_demo.main:app`. Port, server type, actuator endpoints, and log level all have sensible defaults; you override only what you actually need to change.
+The `module` key tells `pyfly run` exactly where the ASGI `app` lives — `lumen_demo.main:app`. The application listens on `pyfly.server.port` (default `8080`); server type, actuator endpoints, and log level all have sensible defaults too, so you override only what you actually need to change.
+
+!!! spring "Spring parity"
+ `pyfly.server.port` is the direct counterpart of Spring Boot's `server.port`, right down to the `8080` default. The matching environment-variable override is `PYFLY_SERVER_PORT` (Spring's `SERVER_PORT`). Application identity follows the same pattern: `pyfly.app.name` and `pyfly.app.version` mirror `spring.application.name`.
+
+!!! warning "Renamed key: use server.port, not web.port"
+ Earlier PyFly releases used `pyfly.web.port` (and the `PYFLY_WEB_PORT` environment variable) for the listen port. Both were **removed** in v26.06.102 in favour of `pyfly.server.port` / `PYFLY_SERVER_PORT`. If you copy an old config and the port seems ignored, this is almost always why — rename the key under `server:` and the override takes effect.
!!! note "Default server: Granian vs Uvicorn"
PyFly's default ASGI server is **Granian**, a high-performance Rust-based server. The scaffold's `pyfly[web]` dependency bundles **Uvicorn** instead (lighter install). The two are interchangeable: pass `--server uvicorn` on the command line, or add `pyfly[granian]` to your dependencies to use Granian. The Lumen wallet sample runs with `--server uvicorn` for this reason.
@@ -250,12 +287,17 @@ The `module` key tells `pyfly run` exactly where the ASGI `app` lives — `lumen
## Your first run
-With the project in place, start the server. From the project root:
+With the project in place, start the server.
+
+**Step 1 — Start the server.** From the project root, run:
-::: listing terminal | Listing 1.6 — Run the server with uv
+::: listing terminal | Listing 1.8 — Run the server with uv
uv run pyfly run --server uvicorn
:::
+!!! note "Why `--server uvicorn`"
+ PyFly's default server is Granian, but the `pyfly[web]` extra ships Uvicorn (a lighter install). Passing `--server uvicorn` tells PyFly to use the server you actually have. If you ever see an error about Granian not being installed, this flag is the fix — or add `pyfly[granian]` and drop the flag.
+
After a moment you will see the PyFly ASCII banner followed by a stream of structured startup events:
```
@@ -266,10 +308,10 @@ ______ ___.__._/ ____\ | ___.__.
| __// ____| |__| |____/ ____|
|__| \/ \/
-:: PyFly Framework :: (v26.06.103) (Python 3.13.13)
+:: PyFly Framework :: (v26.06.110) (Python 3.13.13)
Copyright 2026 Firefly Software Foundation. | Apache License 2.0
2026-06-07 20:34:32,442 [INFO] pyfly.core: starting_application |
- app=lumen version=1.0.0 python=3.13.13 pid=72300
+ app=lumen-demo version=0.1.0 python=3.13.13 pid=72300
2026-06-07 20:34:32,442 [INFO] pyfly.core: runtime_environment |
os=Darwin os_version=25.5.0 arch=arm64 cpus=11
2026-06-07 20:34:32,442 [INFO] pyfly.core: loaded_config |
@@ -277,7 +319,7 @@ Copyright 2026 Firefly Software Foundation. | Apache License 2.0
2026-06-07 20:34:32,442 [INFO] pyfly.core: loaded_config |
source=pyfly.yaml
2026-06-07 20:34:32,442 [INFO] pyfly.core: scanned_package |
- package=lumen.web.controllers beans_found=1
+ package=lumen_demo.controllers beans_found=1
2026-06-07 20:34:32,580 [INFO] pyfly.core: bean_summary |
total=127 services=6 repositories=2 controllers=4
2026-06-07 20:34:32,580 [INFO] pyfly.core: mapped_endpoints | count=5
@@ -285,6 +327,10 @@ Copyright 2026 Firefly Software Foundation. | Apache License 2.0
method=POST path=/api/v1/wallets handler=open_wallet
2026-06-07 20:34:32,580 [INFO] pyfly.core: api_documentation |
swagger_ui=http://0.0.0.0:8080/docs
+2026-06-07 20:34:32,580 [INFO] pyfly.core: management_server |
+ url=http://0.0.0.0:9090 endpoints=actuator + admin
+2026-06-07 20:34:32,580 [INFO] pyfly.core: admin_dashboard |
+ url=http://0.0.0.0:9090/admin
2026-06-07 20:34:32,581 [INFO] pyfly.core: server_started |
server=uvicorn host=0.0.0.0 port=8080 workers=1
```
@@ -296,14 +342,29 @@ Read these log lines as a story of what the framework did on your behalf. Each e
3. **`loaded_config`** (×2) — configuration is layered: the framework ships `pyfly-defaults.yaml` with safe production defaults; your `pyfly.yaml` overrides only what you need. Activate a profile (e.g., `--profile prod`) and you will see a third entry.
4. **`scanned_package`** — the DI container found one `@rest_controller` in the web controllers package. `beans_found` grows as you add services and repositories.
5. **`bean_summary`** — the total DI context size, including framework-internal beans. Even with 127 beans registered, PyFly boots in well under a second.
-6. **`server_started`** — Uvicorn is accepting connections.
+6. **`management_server`** — the actuator endpoints and admin dashboard are served on a *separate* management port (default `9090`), independent of the app's `8080`.
+7. **`admin_dashboard`** — the exact URL of the live admin UI, `http://0.0.0.0:9090/admin`.
+8. **`server_started`** — Uvicorn is accepting connections on the application port.
-Two endpoints are already live before you have written a single line of application logic. Try the health check first:
+!!! note "What just happened"
+ You ran one command and PyFly did the work of an entire boilerplate sprint: it loaded layered configuration, scanned your packages, wired the DI container, mapped your HTTP routes, published interactive API docs, brought up a separate management server with health checks and an admin dashboard, and started accepting requests — all logged as named, machine-filterable events. Leave this server running in its terminal; you will call it from a second terminal in the next steps. Press `Ctrl+C` when you want to stop it.
+
+!!! spring "Spring parity"
+ Serving actuator and the admin dashboard on a dedicated port mirrors Spring Boot's `management.server.port`. In PyFly the key is `pyfly.management.server.port` (default `9090`). Set it equal to `pyfly.server.port` for single-port behaviour, or set it to `-1` to disable the management endpoints entirely. By default this port is **open and unauthenticated** (also Spring parity) — fine for local development, but in production secure it with `pyfly.management.security.enabled: true`.
-::: listing terminal | Listing 1.7 — Health check
-curl -s localhost:8080/actuator/health
+Two endpoints are already live before you have written a single line of application logic. Open a *second* terminal (leave the server running in the first) and try the health check.
+
+**Step 2 — Check the live health endpoint.** It lives on the management port, `9090`:
+
+::: listing terminal | Listing 1.9 — Health check (management port 9090)
+curl -s localhost:9090/actuator/health
:::
+!!! note "New term: actuator"
+ The *actuator* is PyFly's built-in operations layer: a small set of HTTP endpoints that report on the running app — `/actuator/health`, `/actuator/info`, and (when you expose them) metrics, environment, and more. It is the same concept, and the same `/actuator` base path, as Spring Boot Actuator. By default only `health` and `info` are exposed over HTTP; widen that with `pyfly.management.endpoints.web.exposure.include`.
+
+You should see a JSON document with a top-level `"status": "UP"` and a `components` map — one entry per health indicator the framework registered:
+
```json
{
"status": "UP",
@@ -328,22 +389,39 @@ curl -s localhost:8080/actuator/health
}
```
-Then call the first business endpoint — opening a wallet:
+**Step 3 — Open a wallet.** Now call the first business endpoint. Unlike the actuator, this lives on the *application* port, `8080`:
-::: listing terminal | Listing 1.8 — Open a wallet
+::: listing terminal | Listing 1.10 — Open a wallet (application port 8080)
curl -s -X POST localhost:8080/api/v1/wallets \
-H 'content-type: application/json' \
-d '{"owner_id":"u-1","currency":"EUR"}'
:::
+The response is the new wallet's identifier (your UUID will differ):
+
```json
{"wallet_id": "wlt-c5bbb2a7-dd49-4321-932e-e4c6bfa5cc2c"}
```
-Open `http://localhost:8080/docs` in your browser for the interactive Swagger UI; `http://localhost:8080/redoc` gives you ReDoc; the raw OpenAPI spec is at `/openapi.json`.
+!!! note "What just happened"
+ That single `curl` travelled through the whole stack the framework built for you: the JSON body was validated against the `OpenWalletRequest` model, the `WalletController` turned it into an `OpenWallet` command, the command bus dispatched it to its handler, a `Wallet` aggregate was created and persisted, and the new id came back as JSON. You will build each of those layers yourself in later chapters — for now, notice that it already works end to end.
+
+**Step 4 — Explore the interactive docs.** Open `http://localhost:8080/docs` in your browser for the interactive Swagger UI; `http://localhost:8080/redoc` gives you ReDoc; the raw OpenAPI spec is at `http://localhost:8080/openapi.json`. The docs live on the application port alongside your API.
!!! note "Note"
- All three doc URLs are emitted in the boot log (`api_documentation` entries) so you never have to remember them. `http://localhost:8080/admin` opens the PyFly Admin Dashboard — a live view of beans, endpoints, health indicators, and recent log events.
+ All three doc URLs are emitted in the boot log (`api_documentation` entries) so you never have to remember them. The PyFly Admin Dashboard — a live view of beans, endpoints, health indicators, and recent log events — opens at `http://localhost:9090/admin` on the management port (its exact URL is the `admin_dashboard` boot-log line).
+
+**Step 5 — Run the generated tests.** The scaffold ships a working test suite so you can confirm the toolchain end to end. Install the dev tools, then run pytest:
+
+::: listing terminal | Listing 1.11 — Run the test suite
+uv sync --group dev
+uv run --group dev pytest -q
+:::
+
+!!! note "Expected output"
+ You should see a short run of dots (or `PASSED` lines) and a green summary like `3 passed in 0.42s` — the exact count depends on the archetype. Any green summary means PyFly, your virtual environment, and pytest are all wired correctly. (The Lumen wallet sample you study throughout the book ships a far larger suite, but it runs the same way: `uv run --group dev pytest -q`.)
+
+That completes the loop: install, scaffold, run, call, and test — all before writing a line of your own logic.
---
@@ -355,11 +433,11 @@ In under five minutes you installed PyFly, scaffolded a production-shaped servic
|---|---|
| Structured JSON logging with runtime metadata | Framework default — emitted on every boot |
| Interactive API docs (Swagger UI + ReDoc) | Built-in; always on, opt out via `pyfly.yaml` |
-| Health endpoint (`/actuator/health`) | `actuator.endpoints.enabled: true` in scaffold |
+| Health endpoint (`/actuator/health` on port 9090) | `actuator.endpoints.enabled: true` in scaffold |
| Profile-aware configuration layering | `pyfly.yaml` + `--profile` flag |
| Auto-discovery DI container | `scan_packages` in `@pyfly_application` |
| Startup timing, bean summary, endpoint map | Emitted as structured log events on every boot |
-| Admin Dashboard (`/admin`) | Enabled in the scaffold by default |
+| Admin Dashboard (`/admin` on management port 9090) | Enabled in the scaffold by default |
That is the PyFly promise: sensible decisions made for you, conventions consistent across every service, and production-ready defaults from the very first run.
@@ -369,8 +447,10 @@ That is the PyFly promise: sensible decisions made for you, conventions consiste
1. **Rename the service.** Open `pyfly.yaml` and change `app.name` from `lumen-demo` to `lumen-wallet`. Also update the `name` parameter in `@pyfly_application`. Re-run with `uv run pyfly run --server uvicorn` and confirm the new name appears in the `starting_application` log line.
-2. **Explore the live docs.** With the server running, open `http://localhost:8080/docs`. Notice the service name and version at the top of the Swagger UI. Then navigate to `http://localhost:8080/redoc` and compare the two doc renderers. Check the health response at `http://localhost:8080/actuator/health` and note which health indicators are already reporting.
+2. **Explore the live docs.** With the server running, open `http://localhost:8080/docs`. Notice the service name and version at the top of the Swagger UI. Then navigate to `http://localhost:8080/redoc` and compare the two doc renderers. Check the health response at `http://localhost:9090/actuator/health` (remember: the actuator lives on the management port, not the application port) and note which health indicators are already reporting. Open `http://localhost:9090/admin` to see the same information in the live dashboard.
3. **Switch to Granian.** Add `pyfly[granian]` to the `dependencies` list in `pyproject.toml`, run `uv sync`, then start the server without the `--server uvicorn` flag. Compare the `server_started` log line — the `server` field should now read `granian`.
4. **Map files to responsibilities.** Look at the two entry-point files `app.py` and `main.py`. Write a one-sentence description of what each one is responsible for. Where does the DI container come from? Where does the ASGI `app` object live? Which one would you edit to change the scan packages?
+
+5. **Collapse to a single port.** Add `pyfly.management.server.port: 8080` under the `server`-sibling `management:` section in `pyfly.yaml` (so it equals `pyfly.server.port`). Re-run the server and watch the boot log: the `management_server` line disappears and `http://localhost:8080/actuator/health` now responds on the application port. Then try `pyfly.management.server.port: -1`, re-run, and confirm the actuator and admin routes are gone entirely.
diff --git a/book/manuscript/02-dependency-injection.md b/book/manuscript/02-dependency-injection.md
index 9a8bf233..3e56bfbc 100644
--- a/book/manuscript/02-dependency-injection.md
+++ b/book/manuscript/02-dependency-injection.md
@@ -12,6 +12,23 @@ maps the persistence row, and a CQRS handler that depends on both —
and let PyFly wire them together from nothing but type hints.
No factories, no manual `new`, no glue code.
+This chapter is hands-on. We will build each piece in small,
+numbered steps, and after every milestone there is a **Run it**
+checkpoint that shows the exact command to type and the output you
+should see on screen. If your output matches, you are on track; if
+it does not, the gap tells you precisely what to fix. You are
+following along inside `samples/lumen` with PyFly **v26.6.110**
+installed (`uv sync` from the Lumen directory pulls it in).
+
+!!! note "New term: container"
+ Throughout the chapter we talk about *the container*. A
+ **container** is simply the object PyFly creates at startup that
+ knows how to build, connect, and hand out all your application's
+ objects. You never construct it yourself — when you run the app,
+ PyFly stands the container up, fills it with your beans, and keeps
+ it alive until shutdown. Think of it as a smart warehouse that
+ both stores your objects and assembles them on demand.
+
Before a single line of Lumen code appears, it is worth pausing on
*why* that matters. In a conventional Python project you would write
something like:
@@ -44,6 +61,15 @@ owns. You make a class visible to the container by applying a
**stereotype decorator** — a thin annotation that registers the class
and signals its architectural role.
+!!! note "New terms: bean and stereotype"
+ A **bean** is just an instance the container owns — it builds it,
+ supplies its dependencies, and (usually) keeps a single shared copy
+ around. A **stereotype** is the decorator you put on a class to say
+ "container, this is yours, please manage it." The word *stereotype*
+ is borrowed from Spring; it simply means "a labelled role." Putting
+ `@service` on a class is the whole act of registration — there is no
+ separate config file to edit.
+
PyFly ships five stereotypes:
| Decorator | Meaning |
@@ -117,20 +143,118 @@ found?" confusion when adding new subpackages. `@enable_domain_stack`
activates the CQRS, transactional engine, event sourcing, relational
data, and rule-engine auto-configurations in a single line.
+Read that listing as four decisions:
+
+- **Step 1 — name the application.** `name="lumen"` and
+ `version="1.0.0"` become the identity the startup banner and the
+ `/actuator/info` endpoint report. (These are the *application's* name
+ and version; the framework version is separate — v26.6.110 here.)
+- **Step 2 — describe it.** `description=...` is human-facing metadata
+ surfaced in the generated API docs.
+- **Step 3 — list the packages to scan.** Every entry in
+ `scan_packages` is a dotted Python path the container will import and
+ inspect. If a class with a stereotype lives in a package *not* on
+ this list, the container never sees it.
+- **Step 4 — enable the stack.** `@enable_domain_stack` switches on the
+ domain-tier auto-configurations so the CQRS buses, the transactional
+ session, and the relational data layer all exist before your beans
+ are wired.
+
+!!! tip "Tip: scan the package, not the class"
+ `scan_packages` entries are *package* paths (`lumen.web.controllers`),
+ never individual module or class paths. The container walks the
+ package and discovers every stereotype-decorated class inside it.
+ When you add a new handler under `lumen.core.services.wallets`, it is
+ picked up automatically — no edit to `scan_packages` needed. You only
+ touch this list when you introduce a brand-new subpackage.
+
+**Run it.** From the Lumen project root, boot the application and watch
+the container assemble itself:
+
+```bash
+cd samples/lumen
+uv run pyfly run --server uvicorn
+```
+
+You should see the banner followed by structured startup lines — the
+container reporting exactly what it scanned and wired:
+
+```text
+:: PyFly Framework :: (v26.6.110) (Python 3.12.13)
+
+pyfly.core: starting_application | app=lumen version=1.0.0
+pyfly.core: scanned_package | package=lumen.models.repositories beans_found=1
+pyfly.core: scanned_package | package=lumen.core.services.wallets beans_found=7
+pyfly.core: scanned_package | package=lumen.core.services.transfers beans_found=2
+pyfly.core: scanned_package | package=lumen.core.services.listeners beans_found=1
+pyfly.core: scanned_package | package=lumen.web.controllers beans_found=1
+pyfly.core: bean_summary | total=137 services=10 repositories=1 controllers=4 configurations=19
+pyfly.core: server_started | server=uvicorn host=0.0.0.0 port=8080 workers=1
+pyfly.core: application_started | app=lumen startup_time_s=0.143 beans_initialized=137
+```
+
+The `scanned_package` lines are `scan_packages` doing its job: one line
+per entry, each reporting how many beans it found. The final
+`application_started` line — the equivalent of Spring Boot's "Started
+Application in N seconds" — is your signal that the context booted
+cleanly. Press `Ctrl-C` to stop the server.
+
+!!! note "New term: the management port"
+ Two ports appear at startup. Your application's HTTP API listens on
+ `pyfly.server.port` (default **8080**). Operational endpoints — the
+ health check, info, and the admin dashboard — listen separately on
+ the **management port** `pyfly.management.server.port` (default
+ **9090**), which is open and unauthenticated by default. You will
+ not touch either in this chapter, but it is worth knowing why two
+ ports light up. (The older `pyfly.web.port` key was removed in
+ v26.6.102; always use `pyfly.server.port` now.)
+
+**What just happened.** A single command did a lot. PyFly loaded
+`pyfly.yaml`, imported each package in `scan_packages`, found every
+stereotype-decorated class, asked the container to build them in
+dependency order, and reported the totals — 137 beans, of which most
+are framework auto-configuration beans and only a handful are yours so
+far. From this point on, the rest of the chapter is about *adding* to
+that bean count: an entity, a repository, and a command handler, each
+discovered by exactly this mechanism.
+
!!! spring "Spring parity"
`scan_packages` is the equivalent of Spring's
`@ComponentScan(basePackages = {...})`. The semantics are identical:
list every subpackage you want the framework to introspect, and it
- will register everything it finds.
+ will register everything it finds. The `application_started` log line
+ mirrors Spring Boot's "Started Application in N seconds (process
+ running for M)" startup summary.
### The entity and the repository
Lumen stores wallets in a relational database. Two classes carry this
responsibility: `WalletEntity` (the persistence row) and
-`WalletRepository` (the data-access bean).
+`WalletRepository` (the data-access bean). We will build them in order:
+first the row shape, then the data-access bean that reads and writes it.
+
+!!! note "New term: entity"
+ An **entity** is the in-database shape of one record — here, one
+ wallet, stored as one row in a `wallets` table. It is deliberately
+ plain: just typed columns, no behaviour. (Lumen keeps the *rich*
+ domain object, the `Wallet` aggregate, separate; you will meet it in
+ Chapter 6. For now, the entity is simply how a wallet is written to
+ and read from the database.)
**The entity.** `WalletEntity` is a plain SQLAlchemy-mapped class that
-inherits the framework's `Base`:
+inherits the framework's `Base`. Build it field by field:
+
+- **Step 1 — inherit `Base`.** Subclassing PyFly's declarative `Base`
+ is what enrols the class in the ORM's metadata so the framework can
+ create its table.
+- **Step 2 — name the table.** `__tablename__ = "wallets"` is the SQL
+ table this class maps to.
+- **Step 3 — declare the primary key.** `id` is a `str` column marked
+ `primary_key=True` — the wallet keeps its own domain id (`wlt-…`)
+ rather than a generated number.
+- **Step 4 — declare the remaining columns.** `owner_id`, `currency`,
+ `balance_minor` (the balance in minor units — cents — so there is
+ never a floating-point rounding bug), and a `created_at` timestamp.
::: listing lumen/models/entities/v1/wallet_orm.py | Listing 2.2a — WalletEntity: the persistence row
from __future__ import annotations
@@ -167,6 +291,33 @@ Inheriting `Base` (PyFly's declarative base) registers the `wallets`
table in `Base.metadata`; the framework's engine lifecycle creates it
on startup. No further wiring is needed.
+**Run it.** With `ddl-auto: create` set in `pyfly.yaml`, the framework
+builds the schema from your mapped entities the moment the app boots.
+Start the app again and look for the data-layer lines:
+
+```bash
+uv run pyfly run --server uvicorn
+```
+
+```text
+pyfly.data.relational.auto_configuration: Initializing database schema (ddl-auto=create)
+pyfly.data.relational.auto_configuration: Database schema initialized (1 tables)
+```
+
+`1 tables` is your `wallets` table — created purely because
+`WalletEntity` inherits `Base`. There is no migration script to run and
+no `CREATE TABLE` to write by hand. (Lumen uses SQLite by default, so
+the database is just a `lumen.db` file in the project directory.)
+
+!!! note "New term: repository"
+ A **repository** is the object your code talks to when it wants to
+ load or save entities. Instead of writing SQL, you call methods like
+ `find_by_id` or `save`. PyFly's `Repository` base class *generates*
+ those methods for you from the entity and key types, so the
+ repository you write is mostly empty — you declare it, and the
+ framework fills in the implementation. (CRUD, used below, just stands
+ for Create, Read, Update, Delete — the four basic data operations.)
+
**The repository.** `WalletRepository` subclasses the framework's
generic `Repository[WalletEntity, str]`. The two type arguments tell
the framework the *entity type* (`WalletEntity`) and the *primary-key
@@ -233,18 +384,38 @@ maintain: **the framework supplies and injects the implementation;
you depend on the repository class itself by type.**
The three extra methods show the extension points the framework
-exposes on top of the inherited CRUD:
-
-- `find_by_owner_id` is a **derived query** — the
- `RepositoryBeanPostProcessor` parses the method name and compiles
- a real `SELECT … WHERE owner_id = :owner_id` at startup; you write
- the stub (`...`) and the framework fills it in.
-- `find_rich` is a **Specification query** — it composes a reusable
- `Specification` predicate and runs it with pagination and sorting
- via the inherited `find_all_by_spec_paged`.
-- `upsert` is a thin convenience over `session.merge` so a command
- handler can persist an entity whether it is new or already exists
- with a single call.
+exposes on top of the inherited CRUD. Look at them one at a time:
+
+- **Step 1 — a derived query.** `find_by_owner_id` is a **derived
+ query**: the `RepositoryBeanPostProcessor` (a startup component that
+ edits beans after they are built) parses the method *name* and
+ compiles a real `SELECT … WHERE owner_id = :owner_id`. You write only
+ the stub body (`...`); the framework supplies the SQL. The naming
+ convention is the API — `find_by_` becomes
+ `WHERE = ?`.
+- **Step 2 — a Specification query.** `find_rich` composes a reusable
+ `Specification` predicate (here, `balance_at_least`) and runs it with
+ pagination and sorting via the inherited `find_all_by_spec_paged`.
+ Specifications are how you build a composable, type-safe `WHERE`
+ clause when a method name would get unwieldy.
+- **Step 3 — an upsert.** `upsert` is a thin convenience over
+ `session.merge` so a command handler can persist an entity whether it
+ is new (INSERT) or already exists (UPDATE) with a single call. Because
+ the wallet owns its own id, both cases key on the same primary key.
+
+**What just happened.** You declared a repository whose body is almost
+entirely empty, yet it now exposes a complete async CRUD surface plus
+one derived query, one specification query, and an upsert. The
+`@repository` stereotype registered it as a bean; the framework read the
+`Repository[WalletEntity, str]` base, generated the implementation, and
+made it injectable by type. You wrote intent; PyFly wrote the plumbing.
+
+!!! tip "Tip: confirm the repository is registered"
+ Re-run `uv run pyfly run --server uvicorn` and look at the
+ `bean_summary` line: `repositories=1`. That single registered
+ repository is your `WalletRepository`. If you ever add a second
+ repository and it does not appear in this count, the usual cause is
+ that its package is missing from `scan_packages`.
!!! spring "Spring parity"
`@service`, `@component`, `@repository`, and `@configuration` map
@@ -267,6 +438,14 @@ never call constructors yourself. You declare what a class *needs* as
them in automatically. This is **constructor injection**, and it is the
recommended approach for all mandatory dependencies.
+!!! note "New term: injection"
+ **Injection** is the act of the container *handing* a class the
+ objects it depends on, rather than the class building them itself.
+ With *constructor* injection, you simply list the dependencies as
+ typed `__init__` parameters; the container reads those type hints and
+ passes in matching beans when it builds the object. The class never
+ says *how* to obtain its dependencies — only *what* it needs.
+
The mental model is a simple wishlist: list the types you need; the
container delivers the right instances. If a dependency does not exist
at startup, you get a clear `NoSuchBeanError` immediately — not a
@@ -280,8 +459,25 @@ decorators: `@command_handler` (or `@query_handler`) **stacked on
class as a bean; the CQRS decorator adds only routing metadata
(`__pyfly_command_type__` or `__pyfly_query_type__`) so the
command/query bus can dispatch to the right handler. Without `@service`,
-the container never sees the class and the bus raises `NoHandlerError`
-at dispatch time.
+the container never sees the class and the command bus raises
+`CommandHandlerNotFoundException` at dispatch time (the query bus raises
+`QueryHandlerNotFoundException` for a missing query handler).
+
+Before reading the listing, here is the shape of what you are about to
+write, step by step:
+
+- **Step 1 — register the bean.** Put `@service` directly on the class.
+ This is the line that makes the container manage it.
+- **Step 2 — add routing metadata.** Stack `@command_handler` *above*
+ `@service`. It reads `CommandHandler[DepositFunds, int]` and records
+ "this bean handles `DepositFunds` commands."
+- **Step 3 — declare dependencies in `__init__`.** List the repository,
+ the event publisher, and the session factory as typed parameters.
+ This single signature is the complete wiring specification — the
+ container reads it and supplies all three.
+- **Step 4 — write the business logic in `do_handle`.** Wrap it in
+ `@transactional()` so the whole load-mutate-save sequence is one
+ committed unit of work.
The `DepositFundsHandler` shows the pattern in full:
@@ -398,6 +594,35 @@ The container resolves dependencies **recursively**. When it constructs
framework-generated CRUD bean), the `EventPublisher`, and the
`async_sessionmaker` — none of which the handler needs to know about.
+**What just happened.** You declared a handler that needs three
+collaborators and wrote not one line of wiring code. The container read
+the `__init__` type hints, built each dependency (and *their*
+dependencies, recursively), and handed the finished object to whoever
+asks for `DepositFundsHandler`. Swapping the in-memory event bus for
+Kafka later will not touch this class at all — it asks for an
+`EventPublisher` and is content with whatever the container provides.
+
+**Run it.** The surest way to confirm the whole graph wires together is
+the integration test that boots the *real* application context and
+drives a deposit through the command bus. From the Lumen project root:
+
+```bash
+uv run --extra dev pytest tests/test_app_context_integration.py -q
+```
+
+```text
+. [100%]
+1 passed in 0.19s
+```
+
+That single dot is the container proving itself: it scanned the
+packages, generated the repository, resolved the `EventPublisher` and
+session factory, constructed `DepositFundsHandler` with all three
+injected, and ran an `open → deposit → withdraw → reload` lifecycle
+end to end. If a dependency were missing, this test would fail at
+*startup* with a `NoSuchBeanError` long before any assertion ran — which
+is exactly the early, loud failure the container is designed to give you.
+
::: figure art/figures/02-di.svg | Figure 2.1 — The container injects dependencies from type hints.
!!! spring "Spring parity"
@@ -581,10 +806,27 @@ as a single factory. For all of these situations, PyFly provides the
participates fully in the container's resolution and lifecycle
machinery.
+!!! note "New terms: @configuration and @bean"
+ A `@configuration` class is a place to put **factory methods**. A
+ `@bean` method is one such factory: the container *calls* it during
+ startup and registers whatever it returns as a bean. You reach for
+ this pattern when a dependency cannot simply be stereotyped — for
+ example a third-party object you do not own, or one that needs custom
+ construction. The method's **return type annotation** is what the
+ container uses to register the result, so it is mandatory.
+
A `@configuration` class acts as a factory. Its `@bean` methods are
called during the startup sequence, and each method's return value is
registered as a bean whose type comes from the method's return
-annotation:
+annotation. Read the listing below in two steps:
+
+- **Step 1 — mark the class `@configuration`.** This tells the context
+ to scan it for `@bean` methods before any stereotype beans are built.
+- **Step 2 — write a `@bean` method with a return annotation.**
+ `event_publisher(self) -> EventPublisher` constructs an
+ `InMemoryEventBus` and — because the annotation says `EventPublisher`
+ — registers it *as* an `EventPublisher`. Anything that asks for an
+ `EventPublisher` now receives this instance.
::: listing lumen/infra_config.py | Listing 2.4 — Producing an EventPublisher bean via @configuration
from pyfly.container import configuration, bean
@@ -614,6 +856,17 @@ Swapping to a Kafka adapter for production means replacing
`InMemoryEventBus()` with `KafkaEventPublisher(settings.kafka_url)` in
a single method. The rest of the codebase is untouched.
+!!! note "Note: how Lumen actually gets its EventPublisher"
+ The listing above shows the `@configuration` / `@bean` pattern you
+ would write to hand-build a bean. Lumen itself does *not* need this
+ for its event bus: setting `eda.provider: memory` in `pyfly.yaml`
+ asks the framework's EDA auto-configuration to register an
+ `EventPublisher` bean for you (the same `InMemoryEventBus` you see
+ in the `events_is InMemoryEventBus` wiring at startup). That is why
+ `DepositFundsHandler` can simply ask for an `EventPublisher` — the
+ auto-configuration already supplied one. Reach for `@bean` when you
+ need a bean the framework does *not* provide out of the box.
+
`@bean` methods can also declare parameters; the container resolves
them automatically:
@@ -760,6 +1013,26 @@ direct call for synchronous methods.
destroyed in **reverse** initialisation order, so a listener started
after the repository is stopped before it.
+**Run it.** Add the bean above to a scanned package, then start and stop
+the app to watch both hooks fire. The `@post_construct` line appears
+during the startup pass; pressing `Ctrl-C` triggers the
+`@pre_destroy` line:
+
+```bash
+uv run pyfly run --server uvicorn
+```
+
+```text
+... wallet_audit_listener_ready # @post_construct, during startup
+^C
+... shutting_down | app=lumen
+... wallet_audit_listener_shutting_down # @pre_destroy, during shutdown
+```
+
+Seeing `..._ready` *before* `application_started` confirms the hook runs
+as part of the eager startup pass; seeing `..._shutting_down` after the
+`Ctrl-C` confirms the symmetric teardown.
+
::: figure art/figures/02-lifecycle.svg | Figure 2.2 — A bean's lifecycle.
### Conditional beans
diff --git a/book/manuscript/03-configuration.md b/book/manuscript/03-configuration.md
index 34ee1584..3590f94c 100644
--- a/book/manuscript/03-configuration.md
+++ b/book/manuscript/03-configuration.md
@@ -14,7 +14,32 @@ This chapter shows how PyFly solves that with a single `pyfly.yaml`, a four-laye
Every non-trivial application has at least two audiences for its configuration: a developer who wants verbose logs and a relaxed local database, and a production system that demands structured JSON logs, a real connection pool, and no debug mode. The naive solution — `if os.getenv("ENV") == "prod":` scattered through a dozen files — quickly becomes impossible to audit. PyFly's answer is one canonical YAML (or TOML) file that holds everything your application knows about itself, with separate mechanisms for what changes between environments.
-PyFly auto-discovers this file in your project root. The framework checks candidates in order — `pyfly.yaml`, `pyfly.toml`, `config/pyfly.yaml`, `config/pyfly.toml` — and loads the first one it finds. Here is Lumen's base `pyfly.yaml`:
+PyFly auto-discovers this file in your project root. The framework checks candidates in order — `pyfly.yaml`, `pyfly.toml`, `config/pyfly.yaml`, `config/pyfly.toml` — and loads the first one it finds.
+
+!!! note "New term: auto-discovery"
+ "Auto-discovery" simply means you do not have to tell PyFly where the config file is. You drop `pyfly.yaml` in your project root and the framework finds it on startup. No path argument, no registration call.
+
+Let us look at Lumen's base `pyfly.yaml` one section at a time, then read it as a whole.
+
+**Step 1 — Identify the service.** The first block names the application and gives it a version. These two values flow into the startup banner, the health endpoint, and trace metadata, so every part of the system reports the same identity:
+
+```yaml
+pyfly:
+ app:
+ name: lumen
+ version: 1.0.0
+```
+
+**Step 2 — Pick the listen port.** PyFly's business API listens on `pyfly.server.port`. The default is `8080`, so this line is technically redundant — it is written out for clarity. (If you have read older PyFly material that mentioned `pyfly.web.port`, note that key was removed in v26.06.102; use `pyfly.server.port` now.)
+
+```yaml
+ server:
+ port: 8080
+```
+
+**Step 3 — Turn on the domain features Lumen uses.** The remaining blocks switch on observability, CQRS, the transactional engine, event sourcing, caching, the in-memory event bus, and the relational data layer. Each block is one feature; you enable what you need and leave the rest at their framework defaults.
+
+Here is the complete file. Notice that `pyfly:` is the only top-level key — everything Lumen tells the framework lives under it:
::: listing pyfly.yaml | Listing 3.1 — Lumen's base configuration file
pyfly:
@@ -23,7 +48,8 @@ pyfly:
version: 1.0.0
banner:
mode: console
- web:
+ server:
+ # App on 8080; actuator + admin default to the management port 9090.
port: 8080
observability:
metrics:
@@ -40,14 +66,16 @@ pyfly:
enabled: true
cache:
provider: in-memory
- # Event-Driven Architecture: in-memory bus (no broker needed).
- # The EventPublisher bean that wallet command handlers publish
- # through — and that @event_listener projections subscribe to —
- # is activated by setting provider to "memory".
+ # Event-Driven Architecture: the in-memory bus (no broker needed).
+ # Setting the provider registers the EventPublisher bean that the
+ # wallet command handlers publish domain events through and that the
+ # @event_listener audit projection auto-subscribes to.
eda:
provider: memory
- # Relational data layer (SQLAlchemy + SQLite via aiosqlite).
- # The framework creates the schema on startup (ddl-auto=create).
+ # Relational data layer (SQLAlchemy + SQLite via aiosqlite). The
+ # framework creates the schema on startup (ddl-auto=create) and backs
+ # the WalletRepository (a framework Repository[WalletEntity, str]) that
+ # the command handlers persist through inside @transactional().
data:
relational:
enabled: true
@@ -55,21 +83,48 @@ pyfly:
ddl-auto: create
:::
+!!! note "Run it"
+ From the Lumen project root, start the app and watch which file the framework loads:
+
+ ```bash
+ cd samples/lumen
+ uv sync
+ uv run pyfly run
+ ```
+
+ The startup banner prints the framework version, then PyFly logs each
+ configuration source it merged (one `loaded_config` line per layer) before the
+ application binds to port `8080`:
+
+ ```
+ :: PyFly Framework :: (v26.06.110) (Python 3.12.13)
+ Copyright 2026 Firefly Software Foundation. | Apache License 2.0
+ no_active_profiles message=No active profiles set, falling back to default
+ loaded_config source=pyfly-defaults.yaml (framework defaults)
+ loaded_config source=.../samples/lumen/pyfly.yaml
+ Uvicorn running on http://0.0.0.0:8080
+ ```
+
+ Leave it running; you will hit it with `curl` shortly. Press `Ctrl+C` to stop.
+
Three things are worth noting. First, the `pyfly:` top-level key is reserved exclusively for framework settings — web server, observability, CQRS, EDA, data access, and profiles all live there. Your own application keys go under a different top-level name (such as `lumen:`). Second, `pyfly.app.name` and `pyfly.app.version` identify the service throughout — startup banner, health endpoints, and trace metadata all read these values. Third, the `pyfly.data.relational.*` block configures the SQLAlchemy/aiosqlite layer; `url`, `ddl-auto`, and `enabled` are its three core keys.
-Nested keys map directly to dot-notation access through `Config.get()`:
+Nested keys map directly to dot-notation access through `Config.get()`. To read a nested value, you join the key path with dots — `pyfly.server.port` walks `pyfly:` then `server:` then `port:`:
```python
-config.get("pyfly.app.name") # "lumen"
-config.get("pyfly.server.port") # 8080
-config.get("pyfly.data.relational.url") # "sqlite+aiosqlite:///./lumen.db"
-config.get("pyfly.eda.provider") # "memory"
+config.get("pyfly.app.name") # "lumen"
+config.get("pyfly.server.port") # 8080
+config.get("pyfly.data.relational.url") # "sqlite+aiosqlite:///./lumen.db"
+config.get("pyfly.eda.provider") # "memory"
```
`Config.get()` uses **relaxed segment matching**: `ddl-auto` and `ddl_auto` resolve to the same key. Your YAML can use kebab-case (the conventional YAML style) and your Python code can use snake_case — no need to remember which form you used in the file.
PyFly uses `PyYAML` (`yaml.safe_load`) for YAML parsing; native YAML types are preserved. The integer `8080` in YAML arrives as a Python `int` — no string parsing required.
+!!! note "What just happened"
+ You wrote one YAML file, and PyFly turned it into a typed, queryable configuration object. The `pyfly:` block told the framework which features to switch on (data layer, CQRS, event bus); `Config.get("…")` reads any value back out by its dotted path; and the relaxed matching means you never have to remember whether you wrote `ddl-auto` or `ddl_auto`. That single object is the source of truth the rest of this chapter builds on.
+
!!! tip "Tip"
You can also use TOML if your team prefers INI-like syntax with strict typing. Rename the file to `pyfly.toml` and use TOML table syntax — `[pyfly.web]`, `[pyfly.data.relational]` — instead of YAML nesting. Every feature described in this chapter works identically with both formats.
@@ -140,6 +195,9 @@ The layering system provides the mechanism for varying configuration between env
A **profile** is a named environment variant — `dev`, `test`, `staging`, `prod`. Activating a profile loads an overlay file and can conditionally include or exclude beans.
+!!! note "New term: overlay file"
+ An "overlay" is a small YAML file that contains *only the keys that change* for one environment. PyFly merges it on top of the base `pyfly.yaml`. You never repeat the full configuration — you just state the differences, and the deep merge from the previous section fills in everything else.
+
### Activating profiles
PyFly must know which profiles are active *before* loading the full configuration, because it needs to know which overlay files to merge. This **early profile resolution** follows a deliberate priority order:
@@ -151,12 +209,14 @@ PyFly must know which profiles are active *before* loading the full configuratio
In production, override with an env var — no code change, no file edit:
```bash
-PYFLY_PROFILES_ACTIVE=prod python main.py
+PYFLY_PROFILES_ACTIVE=prod uv run pyfly run
```
### Profile overlay files
-For each active profile `{name}`, PyFly looks for `pyfly-{name}.yaml` next to the base file. Lumen ships three overlays, each containing only the keys that differ from the base:
+For each active profile `{name}`, PyFly looks for `pyfly-{name}.yaml` next to the base file. We will add three overlays to Lumen, each containing only the keys that differ from the base. Build them one at a time.
+
+**Step 1 — The development overlay.** Create `pyfly-dev.yaml` alongside `pyfly.yaml`. Dev wants the loudest possible feedback loop: full tracebacks, every SQL query echoed to the terminal, and framework internals visible at `DEBUG`.
::: listing pyfly-dev.yaml | Listing 3.2 — Development overlay: verbose logging, debug mode
pyfly:
@@ -172,6 +232,8 @@ pyfly:
Three keys cover everything the dev environment needs: debug mode for detailed tracebacks, SQL echo so every query appears in the terminal, and `DEBUG` log level so framework internals are visible. Everything else comes unchanged from the base file. Note that `echo` lives under `pyfly.data.relational.*`, consistent with the base file structure.
+**Step 2 — The test overlay.** Create `pyfly-test.yaml`. The test environment wants the opposite of dev: quiet. Silence the banner so test output stays readable, turn off real persistence (unit tests mock the repository), and raise the log threshold so passing tests print nothing.
+
::: listing pyfly-test.yaml | Listing 3.3 — Test overlay: in-memory SQLite, silent banner
pyfly:
banner:
@@ -186,6 +248,8 @@ pyfly:
The test overlay silences the startup banner so test output stays clean, disables data persistence (unit tests mock the repository layer), and raises the log threshold to `WARNING` so passing tests produce no noise.
+**Step 3 — The production overlay.** Create `pyfly-prod.yaml`. Production flips many switches at once: a real PostgreSQL URL, structured JSON logs, the interactive docs turned off, and a quiet banner.
+
::: listing pyfly-prod.yaml | Listing 3.4 — Production overlay: real database, JSON logging, docs off
pyfly:
server:
@@ -208,6 +272,25 @@ pyfly:
The production overlay makes several deliberate choices. It disables the interactive API docs — you do not want a live Swagger UI on a production endpoint. It switches logging to `json` format so aggregators like Datadog or CloudWatch can parse structured fields rather than scraping human-readable text. It points `pyfly.data.relational.url` at the real PostgreSQL instance. It sets `pyfly.server.port: 443`, though in practice you will override this with `PYFLY_SERVER_PORT` from your deployment pipeline so no topology details enter the repository.
+!!! note "Run it"
+ With the three overlay files in place, activate the dev profile and watch the merge happen. The `PYFLY_PROFILES_ACTIVE` environment variable tells PyFly which overlays to load before it reads the rest of the config:
+
+ ```bash
+ PYFLY_PROFILES_ACTIVE=dev uv run pyfly run
+ ```
+
+ The startup log now lists the dev overlay among the merged sources, and because dev sets `pyfly.data.relational.echo: true`, every SQL statement appears in the terminal as soon as the app touches the database:
+
+ ```
+ active_profiles profiles=['dev']
+ loaded_config source=pyfly-defaults.yaml (framework defaults)
+ loaded_config source=.../samples/lumen/pyfly.yaml
+ loaded_config source=.../samples/lumen/pyfly-dev.yaml (profile: dev)
+ INFO sqlalchemy.engine.Engine BEGIN (implicit)
+ ```
+
+ Stop the app, run it again *without* the env var, and the dev overlay disappears from the source list — the base file's quieter defaults take over. That is the whole profile mechanism in one experiment: one env var swaps an entire layer in and out.
+
!!! tip "Tip"
Multiple profiles are comma-separated in the env var and are applied in order, so the last profile wins on conflicts: `PYFLY_PROFILES_ACTIVE=prod,metrics` first applies `pyfly-prod.yaml`, then `pyfly-metrics.yaml`. Use this to compose cross-cutting concerns — a `metrics` profile can enable Prometheus scraping without duplicating your entire prod config.
@@ -233,8 +316,14 @@ class VerboseAuditLogger:
...
```
+!!! note "New term: bean"
+ A "bean" is any object the DI container creates and manages for you — a `@service`, `@repository`, `@command_handler`, and so on (the term comes straight from Spring). "Profile-scoped" means the container only creates the bean when a matching profile is active.
+
`Environment.accepts_profiles()` evaluates profile expressions during the first pass of `ApplicationContext.start()`. Beans whose expression does not match the active set are removed before any resolution takes place — never instantiated, never wired, never present in the container. The result is a container that is structurally different per environment, with no `if` statement in your application code.
+!!! note "What just happened"
+ Profiles gave you two independent tools. The *overlay files* (`pyfly-{name}.yaml`) change configuration *values* per environment. The `profile=` parameter on a stereotype changes which *beans exist* per environment. Both are driven by the same active-profile set — set once via `PYFLY_PROFILES_ACTIVE` — so a single env var reshapes both your settings and your object graph, with zero conditional logic in your business code.
+
---
## Type-safe settings with @config_properties
@@ -243,9 +332,14 @@ String-key lookups like `config.get("pyfly.data.relational.url")` work for occas
`@config_properties` solves exactly this by binding a config section to a typed Python dataclass.
+!!! note "New term: binding"
+ "Binding" means copying values out of the config tree into the fields of a typed object. A Python `@dataclass` is a class whose fields are declared with type hints (`url: str`, `pool_size: int`); after binding, you read `props.pool_size` and get a real `int`, not a string you have to convert yourself.
+
### Declaring a properties class
-Decorate a `@dataclass` with `@config_properties(prefix="...")`. The `prefix` identifies the config section to bind; field names must match the keys under that section (kebab/snake interchangeable). Here is the framework's own `RelationalProperties`, which binds the `pyfly.data.relational.*` block:
+Decorate a `@dataclass` with `@config_properties(prefix="...")`. The `prefix` identifies the config section to bind; field names must match the keys under that section (kebab/snake interchangeable).
+
+**Step 1 — Write the class.** Here is the framework's own `RelationalProperties`, which binds the `pyfly.data.relational.*` block:
::: listing pyfly/config/properties/data.py | Listing 3.5 — RelationalProperties: typed settings for the data layer
from dataclasses import dataclass
@@ -268,7 +362,7 @@ The decorator sets `__pyfly_config_prefix__` on the class and marks it as an inj
Notice that each field carries a default value matching the framework's built-in `pyfly-defaults.yaml`. This is intentional: the class is self-documenting, and it can be constructed and used in unit tests without any YAML file on disk — just instantiate `RelationalProperties()` and you get the development defaults.
-Apply the same pattern to your own application-level settings. Here is how a `WalletProperties` class would look for Lumen's business rules:
+**Step 2 — Apply the pattern to your own settings.** The same decorator works for application-level configuration. Here is how a `WalletProperties` class would look for Lumen's business rules:
```python
from dataclasses import dataclass
@@ -282,7 +376,14 @@ class WalletProperties:
default_currency: str = "USD"
```
-Add the matching block to `pyfly.yaml` under the `lumen:` top-level key (outside `pyfly:`) and the framework binds it automatically — no special registration required.
+**Step 3 — Add the matching YAML.** Put the block under the `lumen:` top-level key (outside `pyfly:`, since this is your application's own namespace, not the framework's) and the framework binds it automatically — no special registration required:
+
+```yaml
+lumen:
+ wallet:
+ daily-transfer-limit: 10000.0
+ default-currency: USD
+```
### Binding and injecting
@@ -331,6 +432,27 @@ When the DI container starts Lumen, `WalletService.__init__` receives the shared
The critical detail in step 2 is that `effective_section()` applies the full four-layer stack — defaults, file, profile overlay, env vars — before the dataclass is constructed. By the time `bind()` finishes, `RelationalProperties` reflects whatever the production overlay or a runtime env var says, not just the base YAML.
+!!! note "What just happened"
+ You replaced scattered `config.get("…")` string lookups with a single typed object. `config.bind(RelationalProperties)` reads the whole `pyfly.data.relational.*` section once, applies the four-layer precedence, coerces strings to the right types, and hands back a plain dataclass. From then on your service reads `self.db.enabled` as a `bool` with IDE autocompletion — and a typo in a field name is caught at startup, not at request time in production.
+
+!!! note "Run it"
+ You can prove the env-var layer reaches a bound property with a tiny check. The base `pyfly.yaml` sets `pyfly.data.relational.enabled: true`; here we override it from the environment. From the Lumen project root:
+
+ ```bash
+ PYFLY_DATA_RELATIONAL_ENABLED=false uv run python -c "
+ from pyfly.core import Config
+ from pyfly.config.properties import RelationalProperties
+ db = Config.from_file('pyfly.yaml').bind(RelationalProperties)
+ print('enabled =', db.enabled, type(db.enabled).__name__)
+ "
+ ```
+
+ Expected output — the env var wins over the YAML and the string `"false"` is coerced to a `bool`:
+
+ ```
+ enabled = False bool
+ ```
+
### Injecting individual values with Value
For isolated settings that do not warrant a full properties class, PyFly provides a `Value` descriptor. Declare it as a class-level field and the DI container resolves it at bean creation time — exactly like Spring Boot's `@Value("${...}")`:
@@ -360,9 +482,11 @@ Native YAML types arrive correctly typed — integers, booleans, and floats need
|---|---|
| `int` | `int(value)` |
| `float` | `float(value)` |
-| `bool` | `value.lower() in ("true", "1", "yes", "on")` |
+| `bool` | `value.lower() in ("true", "1", "yes")` |
| `str` | no coercion needed |
+The `bind()` dataclass path treats `"true"`, `"1"`, and `"yes"` as `True`; the read-time `get()`/env override path additionally accepts `"on"`.
+
Calling `bind()` on a class not decorated with `@config_properties` raises `ValueError` immediately — a clear fail-fast signal at startup rather than a silent wrong-value bug at request time.
!!! spring "Spring parity"
@@ -413,7 +537,7 @@ Activating the production profile and overriding the database URL for a specific
PYFLY_PROFILES_ACTIVE=prod \
PYFLY_DATA_RELATIONAL_URL="postgresql+asyncpg://rds-prod:5432/lumen" \
PYFLY_SERVER_PORT=8080 \
- python main.py
+ uv run pyfly run
```
Here, `PYFLY_SERVER_PORT=8080` overrides the prod overlay's `port: 443`. The precedence stack resolves like this:
@@ -441,13 +565,16 @@ PYFLY_SECURITY_JWT_SECRET="$(vault kv get -field=jwt_secret secret/lumen)"
`Config.bind()` also handles values that exist *only* as environment variables — no matching entry in any YAML file. `effective_section()` injects these env-only keys into the bound section so `bind()` sees the same value that `get()` would. Add a new field to a `@config_properties` class, set it exclusively via an env var in your deployment pipeline, and it is populated correctly even when the YAML files have not been updated yet:
```bash
-# No YAML entry for pyfly.data.relational.pool-size?
+# No YAML entry for pyfly.data.relational.echo?
# Set it exclusively via env var — bind() still picks it up.
-PYFLY_DATA_RELATIONAL_POOL_SIZE=20 python main.py
+PYFLY_DATA_RELATIONAL_ECHO=true uv run pyfly run
```
This is a practical escape hatch during incremental rollouts: the deploying team can inject a new value before the YAML file is updated and reviewed, and the application picks it up without a code change.
+!!! warning "Multi-word field names and env-only injection"
+ Env-only injection treats each underscore in a `PYFLY_*` name as a path separator, so `PYFLY_DATA_RELATIONAL_POOL_SIZE` is read as the nested path `pool` → `size`, not the flat field `pool_size`. For a single-word field like `echo` this is unambiguous and `bind()` injects it cleanly. For a multi-word field such as `pool_size`, give the key a real home in your YAML (even just `pool-size: 5`) so the env var overrides an existing leaf instead of relying on env-only injection. Read-time `config.get("pyfly.data.relational.pool-size")` always returns the env value regardless, because `get()` maps the whole dotted key in one step.
+
---
## What you built {.recap}
@@ -482,15 +609,46 @@ adapter (Granian, Uvicorn, Hypercorn). Two values change the topology: set
single port (the pre-`v26.06.102` behaviour), or set it to **`-1`** to disable the
management web endpoints entirely.
+!!! warning "The management port is open by default"
+ For Spring Boot parity, the management port (9090) is **open and
+ unauthenticated** by default — it is meant to live on an internal network
+ protected by network isolation, not by the app's login filters. Before you
+ expose it anywhere reachable, secure it with
+ `pyfly.management.security.enabled: true`, which applies the app's security,
+ session, and CSRF filters to the management port too. By default only the
+ `health` and `info` actuator endpoints are exposed over HTTP; widen that with
+ `pyfly.management.endpoints.web.exposure.include` (for example
+ `"health,info,metrics,prometheus"`).
+
+!!! note "Run it"
+ Start Lumen and hit the management port directly. The health endpoint lives on
+ 9090, not on the application's 8080:
+
+ ```bash
+ uv run pyfly run # in one terminal
+ curl http://localhost:9090/actuator/health # in another
+ ```
+
+ Expected output — a small JSON document reporting the service is up:
+
+ ```json
+ {"status":"UP"}
+ ```
+
+ The same path on the app port (`curl http://localhost:8080/actuator/health`)
+ will not answer, because the actuator listens only on the management port.
+
!!! spring "Spring parity"
`pyfly.server.port` ≡ Spring `server.port`, `pyfly.server.host` ≡
`server.address`, and `pyfly.management.server.port` ≡
`management.server.port`. Setting a distinct management port runs the actuator
- on its own connector, exactly as Spring Boot does.
+ on its own connector, exactly as Spring Boot does. `pyfly.management.security.enabled`
+ and `pyfly.management.endpoints.web.exposure.include` mirror Spring's
+ management security and `management.endpoints.web.exposure.include` settings.
## Try it yourself {.exercises}
-1. **Add a staging overlay.** Create `pyfly-staging.yaml` with a PostgreSQL URL for a shared test database under `pyfly.data.relational.url`, `pyfly.data.relational.enabled: true`, and logging at `INFO`. Activate it with `PYFLY_PROFILES_ACTIVE=staging python main.py` and verify from the startup log that the staging source was loaded. Compare the effective configuration to what the prod overlay would produce.
+1. **Add a staging overlay.** Create `pyfly-staging.yaml` with a PostgreSQL URL for a shared test database under `pyfly.data.relational.url`, `pyfly.data.relational.enabled: true`, and logging at `INFO`. Activate it with `PYFLY_PROFILES_ACTIVE=staging uv run pyfly run` and verify from the startup log that the staging source was loaded. Compare the effective configuration to what the prod overlay would produce.
2. **Bind a new typed property and use it.** Add a `max_wallets_per_owner: int = 5` field to a new `WalletProperties` class decorated with `@config_properties(prefix="lumen.wallet")`, and a matching `lumen.wallet.max-wallets-per-owner: 5` key in `pyfly.yaml` (outside the `pyfly:` block). Inject `Config` into `WalletService`, call `config.bind(WalletProperties)`, and add a guard in `open_wallet` that raises `ValueError` when the owner already holds the maximum number of wallets. Write a quick test that overrides the limit to `1` by setting `PYFLY_LUMEN_WALLET_MAX_WALLETS_PER_OWNER=1` and verifying the error fires on the second wallet.
diff --git a/book/manuscript/04-first-http-api.md b/book/manuscript/04-first-http-api.md
index 1970d20e..384e3c3a 100644
--- a/book/manuscript/04-first-http-api.md
+++ b/book/manuscript/04-first-http-api.md
@@ -27,6 +27,16 @@ manages and the web layer routes requests into. Two decorators mark it:
stereotype; `@request_mapping` from `pyfly.web` sets the URL prefix inherited by
every handler in the class.
+A few terms in that paragraph will recur throughout the chapter, so let us pin
+them down once. A **bean** is simply an object the DI container creates and
+hands out for you — you never call `WalletController()` yourself; the framework
+constructs it and keeps a single shared instance. A **stereotype** is a label
+the framework stamps on a class so it knows *what kind* of bean it is —
+`@rest_controller` stamps "this is a web controller", which is the cue the
+startup machinery uses to go looking for routes inside it. A **handler** is one
+`async def` method on the controller that answers one kind of request. With
+those three words in hand, the rest of the chapter reads as plain English.
+
Route handlers are plain `async def` methods, each decorated with
`@get_mapping`, `@post_mapping`, `@put_mapping`, `@patch_mapping`, or
`@delete_mapping`. Every mapping decorator accepts an optional relative path and
@@ -191,6 +201,90 @@ on success. `@get_mapping("/{wallet_id}")` maps `GET /api/v1/wallets/{wallet_id}
Paths are concatenated at startup; duplicate or trailing slashes are normalised
automatically.
+### Building the controller, step by step
+
+If you are typing this in from scratch, the listing above lands all at once.
+Here is the same controller assembled in the order you would actually build it,
+so each decorator has a job to do before the next one arrives.
+
+**Step 1 — Create the file and the class.** Make
+`src/lumen/web/controllers/wallet_controller.py` and define an empty class
+decorated with the two class-level decorators. This is enough for PyFly to
+discover the controller at startup, even before it has a single route.
+
+```python
+from pyfly.container import rest_controller
+from pyfly.web import request_mapping
+
+
+@rest_controller
+@request_mapping("/api/v1/wallets")
+class WalletController:
+ """Digital-wallet REST API: open, deposit, inspect."""
+```
+
+**Step 2 — Add the first handler.** Give the class one `async def` method and
+mark it with a mapping decorator. `@post_mapping("", status_code=201)` maps
+`POST /api/v1/wallets` — the empty path means "the base path with nothing
+appended" — and promises a `201 Created` on success.
+
+**Step 3 — Add the remaining handlers.** Repeat the pattern: one `async def`
+per route, each with its own mapping decorator and relative path. The full set
+in Listing 4.1 gives you open, fetch, balance, deposit, and list.
+
+**Step 4 — Wire the store.** The module-level `_wallets` dictionary is the only
+"database" Part I needs. Each handler reads from and writes to it directly;
+Chapter 5 swaps it for a real repository without touching a single decorator.
+
+!!! note "Note"
+ Notice what you did *not* write: no router file mapping URLs to functions,
+ no registration call in `main.py`, no manual OpenAPI entry. The decorators
+ are the registration. At startup `ControllerRegistrar` finds every
+ `@rest_controller` bean and mounts its routes for you.
+
+!!! tip "Run it"
+ Start the server and confirm the routes are live. From the project root:
+
+ ```bash
+ uv run pyfly run --server uvicorn
+ ```
+
+ The boot banner reports the framework version and the bound port:
+
+ ```
+ :: PyFly Framework :: (v26.06.110) (Python 3.13.13)
+ ```
+
+ In a second terminal, open a wallet and read it back:
+
+ ```bash
+ curl -s -X POST localhost:8080/api/v1/wallets \
+ -H 'Content-Type: application/json' \
+ -d '{"owner_id": "alice", "currency": "EUR"}'
+ ```
+
+ You should see a `201` body with the generated id:
+
+ ```json
+ {"wallet_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}
+ ```
+
+ Copy that id and fetch the wallet:
+
+ ```bash
+ curl -s localhost:8080/api/v1/wallets/a1b2c3d4-e5f6-7890-abcd-ef1234567890
+ ```
+
+ ```json
+ {"id": "a1b2c3d4-...", "owner_id": "alice", "currency": "EUR",
+ "balance_minor": 0, "balance": 0.0, "created_at": "2026-06-15T10:30:00+00:00"}
+ ```
+
+**What just happened.** Two class-level decorators registered the controller and
+fixed its URL prefix; one method-level decorator turned an `async def` into a
+live route; the framework did the routing, JSON serialisation, and status-code
+handling. You wrote business intent, not plumbing.
+
::: figure art/figures/04-request.svg | Figure 4.1 — How a request flows to your handler.
!!! spring "Spring parity"
@@ -213,8 +307,15 @@ from**.
This approach makes handler signatures self-documenting. The parameter list of
any handler tells you exactly which parts of the request it reads and what types
-it expects — without opening a router file or consulting the docs. The
-`ParameterResolver` inspects each handler signature at startup and builds a
+it expects — without opening a router file or consulting the docs.
+
+In plain terms, **binding** is the framework copying a piece of the incoming
+request into one of your handler's parameters, converting it to the type you
+asked for along the way. You declare *what you want and where it comes from* with
+a type annotation; PyFly does the extracting, parsing, and type-coercion before
+your method body runs.
+
+The `ParameterResolver` inspects each handler signature at startup and builds a
resolution plan, so there is zero overhead per request for introspection. Five
binding types cover every part of an HTTP request:
@@ -262,6 +363,21 @@ admit `None`. A missing required `QueryParam` raises `InvalidRequestException`
(HTTP 400). To make a parameter optional, give it a default value or annotate it
`QueryParam[str | None]`.
+!!! tip "Run it"
+ With the server running and at least one wallet opened, exercise the
+ `list_wallets` handler — first with no filter, then with the optional
+ `owner_id` query parameter:
+
+ ```bash
+ curl -s 'localhost:8080/api/v1/wallets'
+ curl -s 'localhost:8080/api/v1/wallets?owner_id=alice'
+ ```
+
+ The first returns every wallet; the second returns only Alice's. Because
+ `owner_id` has a default of `None`, omitting it is perfectly valid — no 400.
+ The path variable behaves the same way in reverse: ask for a wallet id that
+ does not exist and you get a clean `404`, which the next section dissects.
+
### Body[T] — request body
Deserialises the JSON (or XML) request body. When `T` is a Pydantic `BaseModel`,
@@ -300,6 +416,13 @@ query parameter.
`T | None` = optional. The rule is uniform across `QueryParam`, `Header`,
and `Cookie` — you learn it once, it applies everywhere.
+**What just happened.** You learned the whole binding vocabulary as five
+parallel annotations — `PathVar`, `QueryParam`, `Body`, `Header`, `Cookie` —
+that all read like English in a handler signature and all share one
+required-vs-optional rule. The framework reads the annotation, pulls the value
+from the right place, coerces it to your type, and hands you a ready-to-use
+argument. There is nothing else to wire.
+
---
## Validation with Valid[T]
@@ -315,10 +438,20 @@ constraints for free. `Valid[T]` is PyFly's marker that converts a Pydantic
`ValidationError` into a **structured 422 response** instead of letting it
bubble up to a 500.
+A quick gloss before the code. A **DTO** — Data Transfer Object — is a small
+class that describes the *shape* of data crossing the wire: what fields a request
+must carry, or what fields a response will return. Lumen's DTOs are plain
+Pydantic models, so the field declarations double as validation rules.
+**Validation** is the act of checking incoming data against those rules and
+rejecting it cleanly if it does not fit — before any of your handler code runs.
+
### Pydantic DTOs for Lumen
The request and response DTOs used in Lumen's wallet API live under
-`lumen/interfaces/dtos/v1/` — one file per DTO. Here they are in full.
+`lumen/interfaces/dtos/v1/` — one file per DTO. The directory name encodes a
+convention worth noting: `interfaces` holds the contracts the outside world sees,
+and `v1` versions them so a future `v2` payload shape can live alongside the old
+one without breaking existing clients. Here they are in full.
::: listing lumen/interfaces/dtos/v1/open_wallet_request.py | Listing 4.2a — OpenWalletRequest: wallet-opening payload
from __future__ import annotations
@@ -467,6 +600,21 @@ Content-Type: application/json
{"owner_id": ""}
```
+!!! tip "Run it"
+ With the server running, send the bad payload and watch for the `422`:
+
+ ```bash
+ curl -s -w '\nHTTP %{http_code}\n' -X POST localhost:8080/api/v1/wallets \
+ -H 'Content-Type: application/json' \
+ -d '{"owner_id": ""}'
+ ```
+
+ The `-w '\nHTTP %{http_code}\n'` flag prints the status line after the body,
+ so you can confirm it is `HTTP 422` — not the `201` a valid request returns,
+ and not a `500`. The body is the structured envelope shown below. Try a
+ second variant — `-d '{"owner_id": "alice", "currency": "XYZ"}'` — to see the
+ `Currency` enum reject an unknown code with the same envelope shape.
+
The response is HTTP 422:
```json
@@ -515,6 +663,13 @@ Use `Valid[Body[T]]` for every endpoint that accepts user input.
422 response shape (field-level errors with location paths) mirrors Spring
Boot 3's `MethodArgumentNotValidException` payload.
+**What just happened.** The validation rules never left the DTO. `Field(min_length=1)`
+on `owner_id`, the `Currency` enum, and `Field(gt=0)` on `amount` are the entire
+specification — and wrapping the body in `Valid` turned any breach of those rules
+into a predictable, machine-readable `422` before your handler ran. You wrote
+constraints once, on the data; the framework enforced them everywhere the data
+arrives.
+
---
## Errors that clients can trust
@@ -596,11 +751,32 @@ response:
}
```
+!!! tip "Run it"
+ Ask for a wallet that was never opened and watch the framework turn your
+ `raise` into a clean `404`:
+
+ ```bash
+ curl -s -w '\nHTTP %{http_code}\n' localhost:8080/api/v1/wallets/w-999
+ ```
+
+ The status line reads `HTTP 404` and the body is the envelope above, with
+ `"code": "WALLET_NOT_FOUND"` and your `context` carried through verbatim. You
+ never wrote a status code in `get_wallet` — `ResourceNotFoundException` maps
+ to 404 for you. Note the `transaction_id` in the response; copy it and grep
+ your server log to find the exact request.
+
The `transaction_id` is free: the `TransactionIdFilter` assigns a UUID to every
request and threads it through all error responses. Clients log it; support uses
it to find the corresponding server log entry. A single ID is all that is needed
to reconstruct what happened.
+**What just happened.** Your handler expressed a domain fact — "this wallet does
+not exist" — by raising a typed exception with a message, a code, and some
+context. The web layer's global handler did the HTTP translation: it picked the
+status code from the exception's class, wrapped everything in the standard error
+envelope, and stamped a `transaction_id`. HTTP concerns stayed out of your
+business code entirely.
+
!!! note "RFC 7807"
The default error envelope — `{"error": {...}}` — is PyFly's own format. If
your team prefers the IETF standard, set
@@ -660,16 +836,41 @@ As soon as Lumen starts, three documentation endpoints are live at no cost:
The `OpenAPIGenerator` introspects `ControllerRegistrar`'s route metadata —
every path, method, path variable, query parameter, and request/response schema
(from Pydantic model introspection) — and assembles the spec at startup. You
-never write the spec by hand. Disable it in production with
-`pyfly.web.docs.enabled: false` in `pyfly.yaml`.
-
-!!! tip "Tip"
- Open `http://localhost:8080/docs` while Lumen is running. You will see
+never write the spec by hand. The docs endpoints live on the **application**
+port (8080) alongside your API; they are on by default (`pyfly.web.docs.enabled:
+true`). Disable them in production with `pyfly.web.docs.enabled: false` in
+`pyfly.yaml`.
+
+!!! note "Note"
+ Do not confuse the docs endpoints with the **admin dashboard**. `/docs`,
+ `/redoc`, and `/openapi.json` describe *your* API and serve on the app port
+ (8080). The PyFly Admin Dashboard (`/admin`) and the actuator health
+ endpoints (`/actuator/*`) describe the *running process* and serve on the
+ separate **management** port (`pyfly.management.server.port`, default 9090),
+ introduced in Chapter 3. They are two different listeners with two different
+ audiences.
+
+!!! tip "Run it"
+ With the server running, fetch the raw spec and confirm your routes are in
+ it:
+
+ ```bash
+ curl -s localhost:8080/openapi.json | head -c 200
+ ```
+
+ You will see the OpenAPI 3.0 header and the start of the `paths` map. Then
+ open `http://localhost:8080/docs` in a browser. You will see
`POST /api/v1/wallets`, `GET /api/v1/wallets/{wallet_id}`,
`POST /api/v1/wallets/{wallet_id}/deposit`, and the others — each with the
correct request and response schemas derived from your Pydantic models, and
- the `owner_id` query parameter on `list_wallets` already documented with
- its type and default.
+ the `owner_id` query parameter on `list_wallets` already documented with its
+ type and default. Click "Try it out" on `POST /api/v1/wallets` to open a
+ real wallet straight from the browser.
+
+**What just happened.** You did not write a line of API documentation, yet a
+complete, interactive, always-accurate spec appeared. The same route and model
+metadata that drives request handling also drives the docs, so the two can never
+drift apart.
---
@@ -681,8 +882,10 @@ different trade-offs in throughput, HTTP version support, OS compatibility, and
ecosystem tooling. Locking an application to a single server at the framework
level forces you to accept those trade-offs permanently.
-PyFly does not hardcode an ASGI server. At startup, `ServerAutoConfiguration`
-runs a cascading selection based on what is installed:
+An **ASGI server** is the process that actually accepts TCP connections, parses
+HTTP, and calls your application — the layer between the operating system's
+socket and your handlers. PyFly does not hardcode one. At startup,
+`ServerAutoConfiguration` runs a cascading selection based on what is installed:
| Priority | Server | Characteristic |
|---|---|---|
@@ -699,15 +902,31 @@ pyfly run --server uvicorn --reload # development: auto-reload
pyfly run --server granian --workers 4 # production: multi-worker
```
+!!! tip "Run it"
+ For day-to-day development, run with auto-reload so the server restarts on
+ every save:
+
+ ```bash
+ uv run pyfly run --reload
+ ```
+
+ PyFly logs the chosen server and the bound port at startup. Because
+ `--reload` requires a built-in file watcher, PyFly selects **Uvicorn** for
+ reload mode regardless of the cascade order. Edit a handler, save, and watch
+ the log report the restart — then re-run any `curl` from earlier and see your
+ change live without stopping the process.
+
The event loop is pluggable too: `uvloop` (Linux/macOS) and `winloop` (Windows)
are selected automatically when installed, delivering a 2–4× throughput
improvement over the asyncio default. Install them with `uv add "pyfly[web-fast]"`.
!!! tip "Tip"
For development, `pyfly run --reload` is all you need — it picks the best
- available server and event loop automatically. For production,
- `pyfly run --server granian --workers 0` resolves `0` to the CPU count,
- maximising throughput. CLI flags always override `pyfly.yaml`.
+ available server and event loop automatically. For production, pass an
+ explicit positive worker count to scale across cores —
+ `pyfly run --server granian --workers 4`, as in the example above. A `0`
+ or negative `--workers` value resolves to a single worker, so multi-worker
+ is always an explicit opt-in. CLI flags always override `pyfly.yaml`.
---
@@ -741,6 +960,17 @@ built here carry forward intact.
## Try it yourself {.exercises}
+Each exercise is small and self-contained. After every change, restart with
+`uv run pyfly run --reload` and re-run the suggested `curl` to confirm the
+behaviour. If you have the dev dependencies installed, you can also run the
+project's test suite at any point to make sure nothing regressed:
+
+```bash
+uv run --extra dev pytest
+```
+
+You should see a row of passing dots and a `passed` summary line.
+
1. **Add a `DELETE /api/v1/wallets/{wallet_id}` endpoint.** Remove the wallet
from `_wallets` and return 204 No Content. Raise `ResourceNotFoundException`
if the wallet does not exist. Decorate with
diff --git a/book/manuscript/05-persistence.md b/book/manuscript/05-persistence.md
index f1fbebe9..c3b04677 100644
--- a/book/manuscript/05-persistence.md
+++ b/book/manuscript/05-persistence.md
@@ -8,7 +8,37 @@ Lumen has a wallet API that works — but every wallet disappears the moment you
The naïve approach is to scatter SQLAlchemy `select()` and `session.commit()` calls through the command handlers. PyFly offers something far better: a **Spring-Data-style repository layer**. You declare an interface — `class WalletRepository(Repository[WalletEntity, str])` — and the framework *implements it for you*. Full async CRUD comes for free. Query methods are derived from their **names**. Pagination, sorting, composable filters, and read projections are first-class. There is no hand-written adapter and no SQL in the application code.
-This chapter rebuilds Lumen's persistence on that layer, exactly as the running sample does it: the SQLAlchemy entity, the repository with its derived and specification queries, `Page`/`Pageable`/`Sort`, projections for read views, and the transaction seam that keeps the `Wallet` aggregate intact. Everything here runs against a real SQLite file with zero external infrastructure — the sample's 41 tests are green on it.
+This chapter rebuilds Lumen's persistence on that layer, exactly as the running sample does it: the SQLAlchemy entity, the repository with its derived and specification queries, `Page`/`Pageable`/`Sort`, projections for read views, and the transaction seam that keeps the `Wallet` aggregate intact. Everything here runs against a real SQLite file with zero external infrastructure — the sample's 41 tests are green on it. This chapter targets PyFly **v26.6.110**.
+
+We will build the persistence layer one piece at a time, and at every milestone there is a **Run it** box with the exact command to type and the output you should see. If you are following along in the Lumen sample, work from the project root (`samples/lumen`) where `pyfly.yaml` and `pyproject.toml` live; every command below assumes that directory.
+
+!!! note "Run it: see the problem first"
+ Before adding persistence, it is worth feeling the gap it closes. Open a wallet, then stop and restart the process — with the in-memory store from Part I the wallet is gone. The rest of this chapter makes it survive that restart.
+
+ ```bash
+ # Terminal 1 — start the app
+ uv run pyfly run --server uvicorn
+ # ... startup banner, then: Uvicorn running on http://0.0.0.0:8080
+
+ # Terminal 2 — open a wallet, then read it back
+ curl -s -X POST localhost:8080/api/v1/wallets \
+ -H 'content-type: application/json' \
+ -d '{"owner_id": "alice", "currency": "EUR"}'
+ ```
+
+ You get back the new id, then the balance read confirms it exists:
+
+ ```
+ {"wallet_id": "wlt-7f3c..."}
+ ```
+
+ Now press `Ctrl+C` in Terminal 1, start the app again, and ask for that wallet's balance. Before this chapter, the row was never written to disk, so it is gone:
+
+ ```
+ {"detail": "Wallet 'wlt-7f3c...' not found", "code": "WALLET_NOT_FOUND"}
+ ```
+
+ By the end of this chapter the same sequence returns the balance after a restart.
---
@@ -27,7 +57,17 @@ This is the Repository pattern as Spring Data popularised it, translated to idio
## The entity: one row per wallet
-Before a repository can store anything, it needs an **entity** — the on-disk shape of a wallet, one flat row per aggregate. PyFly entities are ordinary SQLAlchemy 2.0 models built on a declarative base the framework exports:
+Before a repository can store anything, it needs an **entity** — the on-disk shape of a wallet, one flat row per aggregate. (An *entity*, in this layer, is just a Python class that maps to one database table; each instance is one row.) PyFly entities are ordinary SQLAlchemy 2.0 models built on a declarative base the framework exports.
+
+We will build it field by field. Create the file `src/lumen/models/entities/v1/wallet_orm.py` and add the pieces in order.
+
+**Step 1 — import the framework's declarative base.** Every entity inherits from a *declarative base*: a SQLAlchemy class that records each table you define so the framework can create them all on startup. PyFly exports one as `Base`:
+
+```python
+from pyfly.data.relational.sqlalchemy import Base
+```
+
+**Step 2 — name the table and declare the columns.** Subclass `Base`, set `__tablename__`, and write one typed attribute per column. The full entity is short:
::: listing lumen/models/entities/v1/wallet_orm.py | Listing 5.1 — WalletEntity: the SQLAlchemy persistence row
from __future__ import annotations
@@ -56,7 +96,10 @@ class WalletEntity(Base):
)
:::
-The `Mapped[T]` / `mapped_column(...)` syntax is SQLAlchemy 2.0 style: each type annotation drives both the Python attribute type and the generated column DDL, so every column has a single source of truth. Because `WalletEntity` subclasses `Base`, importing this module registers the `wallets` table in `Base.metadata`; the framework's engine lifecycle then creates it on startup.
+The `Mapped[T]` / `mapped_column(...)` syntax is SQLAlchemy 2.0 style: each type annotation drives both the Python attribute type and the generated column DDL (the `CREATE TABLE` statement), so every column has a single source of truth. Because `WalletEntity` subclasses `Base`, importing this module registers the `wallets` table in `Base.metadata` — the registry of every table the base knows about — and the framework's engine lifecycle then creates it on startup.
+
+!!! note "What just happened"
+ You wrote one class, no SQL. The five typed attributes became five columns; `primary_key=True` marked `id` as the key; `index=True` on `owner_id` will speed up the "wallets owned by X" query you build later; `nullable=False` and `default=...` set the constraints. Importing this module is enough for the framework to know the table exists — you never call `CREATE TABLE` yourself.
Two design choices are worth calling out.
@@ -71,7 +114,19 @@ Two design choices are worth calling out.
## The repository: CRUD for free
-Now the centrepiece. Lumen's `WalletRepository` subclasses `Repository[WalletEntity, str]` — entity type `WalletEntity`, primary-key type `str` — and is registered with `@repository`. That single declaration is enough for the framework to supply the entire CRUD surface:
+Now the centrepiece. Lumen's `WalletRepository` subclasses `Repository[WalletEntity, str]` — entity type `WalletEntity`, primary-key type `str` — and is registered with `@repository`. (A *stereotype* like `@repository` is a class decorator that tells the framework's container, "manage an instance of this for me." That managed instance is a **bean** — an object the container creates once and hands to anything that asks for it. *Dependency injection*, or *DI*, is the container doing that handing-over for you, so a handler never constructs its own repository.) That single declaration is enough for the framework to supply the entire CRUD surface — *CRUD* being the four basic table operations: Create, Read, Update, Delete.
+
+Create `src/lumen/models/repositories/wallet_repository.py` in two steps.
+
+**Step 1 — import what the declaration needs.** Three imports: your entity, the `@repository` stereotype, and the generic `Repository` base.
+
+```python
+from lumen.models.entities.v1.wallet_orm import WalletEntity
+from pyfly.container import repository
+from pyfly.data.relational.sqlalchemy import Repository
+```
+
+**Step 2 — subclass the generic base and mark it `@repository`.** The two type parameters carry all the wiring:
::: listing lumen/models/repositories/wallet_repository.py | Listing 5.2 — WalletRepository: subclass the framework repository
from __future__ import annotations
@@ -118,15 +173,36 @@ There is no `__init__`, no SQL, and no adapter class. With just that declaration
That is more than enough for most entities. Lumen adds three methods of its own on top — a derived query, a specification query, and an upsert — which the next sections build up.
+!!! spring "Spring parity"
+ This inherited surface is exactly Spring Data's repository hierarchy, carried over name-for-name and stable as of PyFly **v26.6.110**: `CrudRepository` → `ReactiveSortingRepository` → `PagingAndSortingRepository`. `save`/`save_all`, `find_by_id`, `find_all`, `exists_by_id`, `count`, and the `delete*` family map to their Spring equivalents; `find_all(pageable) -> Page[T]` is `findAll(Pageable)`, and `find_all_by_spec*` is the `JpaSpecificationExecutor`. If you know `JpaRepository`, you already know this table.
+
### How the framework knows the types
-When you write `Repository[WalletEntity, str]`, the base class's `__init_subclass__` hook inspects `__orig_bases__` at class-definition time and pulls the entity type (`WalletEntity`) and id type (`str`) out of the generic parameters. The `AsyncSession` is then supplied as an injected dependency by the relational auto-configuration. Nothing is passed manually — the type parameters *are* the wiring.
+When you write `Repository[WalletEntity, str]`, the base class's `__init_subclass__` hook inspects `__orig_bases__` at class-definition time and pulls the entity type (`WalletEntity`) and id type (`str`) out of the generic parameters. (`__init_subclass__` is a Python hook that runs once, automatically, when a subclass is *defined* — so this happens at import time, before any object is created.) The `AsyncSession` — the database connection-and-transaction handle every query runs through — is then supplied as an injected dependency by the relational auto-configuration. Nothing is passed manually — the type parameters *are* the wiring.
+
+!!! note "Run it: confirm the repository wires up"
+ The fastest proof that the entity and repository are sound is the test suite, which exercises the repository against a real SQLite file with no server. From the Lumen project root:
+
+ ```bash
+ uv run --extra dev pytest tests/test_sql_wallet_repository.py -q
+ ```
+
+ You should see every repository test pass:
+
+ ```
+ ...... [100%]
+ 6 passed in 0.30s
+ ```
+
+ These tests construct the repository directly and drive `upsert`, `find_by_id`, `count`, the derived query, and the specification path — the same methods this chapter builds. If they are green, your entity columns and the `Repository[WalletEntity, str]` declaration are correct.
---
## Derived queries: the method name is the query
-CRUD covers lookups by primary key. Real applications also need to query by other columns — "all wallets owned by this customer." In most frameworks you would write the SQL by hand. In PyFly you declare a **stub** and let the framework compile the query *from the method name*:
+CRUD covers lookups by primary key. Real applications also need to query by other columns — "all wallets owned by this customer." In most frameworks you would write the SQL by hand. In PyFly you declare a **stub** — a method with no body, just `...` — and let the framework compile the query *from the method name*.
+
+**Step 1 — declare the stub.** Add a method to `WalletRepository`. The *name* describes the query; the body is literally `...`:
::: listing lumen/models/repositories/wallet_repository.py | Listing 5.3 — A derived query: declared as a stub, compiled from its name
@repository
@@ -140,7 +216,10 @@ class WalletRepository(Repository[WalletEntity, str]):
...
:::
-The body is literally `...`. At startup a `BeanPostProcessor` — the `RepositoryBeanPostProcessor` — scans the repository, spots that `find_by_owner_id` is a stub, parses the **name** into a parsed query, and replaces the stub with a real implementation that runs `SELECT … FROM wallets WHERE owner_id = :owner_id`. Calling `await repo.find_by_owner_id("alice")` now returns exactly the rows for that owner.
+**Step 2 — let the framework fill in the body.** You write no more code. At startup a `BeanPostProcessor` — the `RepositoryBeanPostProcessor` — does the work. (A *BeanPostProcessor* is a hook the container runs over every bean just after it is created; this one specialises in repositories.) It scans the repository, spots that `find_by_owner_id` is a stub, parses the **name** into a parsed query, and replaces the stub with a real implementation that runs `SELECT … FROM wallets WHERE owner_id = :owner_id`. Calling `await repo.find_by_owner_id("alice")` now returns exactly the rows for that owner.
+
+!!! note "What just happened"
+ You declared a method and got a working query — the framework read the *intent* from the name `find_by_owner_id` and wrote the SQL for you. The naming is not magic; it follows a grammar, covered next. The key idea: in this layer you describe *what* you want by how you name the method, and the post-processor supplies the *how*.
The grammar is the Spring Data convention. A method name is a **prefix** followed by a **subject** built from field names, operators, connectors, and an optional ordering clause:
@@ -188,7 +267,9 @@ The prefix decides the *shape* of the result: `find_by` returns a list, `count_b
## Pagination: Page, Pageable, and Sort
-A list endpoint should never return *every* wallet. PyFly's pagination types — `Pageable` (what page, what size, what sort), `Sort` (the ordering), and `Page[T]` (the slice plus metadata) — are inherited straight from the CRUD surface via `find_all(pageable)`.
+A list endpoint should never return *every* wallet. *Pagination* is the standard fix: return one fixed-size **page** of rows at a time, plus enough metadata for the client to ask for the next one. PyFly's pagination types — `Pageable` (what page, what size, what sort), `Sort` (the ordering), and `Page[T]` (the slice plus metadata) — are inherited straight from the CRUD surface via `find_all(pageable)`.
+
+There are three small pieces to assemble: the handler that calls `find_all(pageable)`, the `Page[T]` it returns, and the controller that builds the `Pageable` from the request. We will take them in that order.
Lumen's `ListWallets` query handler is the whole story in three lines:
@@ -246,13 +327,37 @@ async def list_wallets(
`Sort.by("created_at").descending()` names the column and the direction; `Pageable.of(page, size, sort)` packages it with the page coordinates. The handler returns a framework `Page`, and the controller folds it into a serialisable `PageDto` — a plain Pydantic mirror of the page — so `GET /api/v1/wallets?page=1&size=20` returns JSON like `{"items": [...], "total": 42, "page": 1, "total_pages": 3, "has_next": true, ...}`.
+!!! note "Run it: page through the wallets"
+ With the relational layer turned on (the "Turning it on" section below switches it on; the Lumen sample ships it already enabled), open a couple of wallets, then ask for the first page. From a running app:
+
+ ```bash
+ curl -s 'localhost:8080/api/v1/wallets?page=1&size=20'
+ ```
+
+ The response carries the rows *and* the pager metadata — note `total`, `page`, `total_pages`, and `has_next` alongside `items`:
+
+ ```json
+ {
+ "items": [
+ {"id": "wlt-...", "owner_id": "alice", "currency": "EUR",
+ "balance_minor": 0, "balance": 0.0, "created_at": "..."}
+ ],
+ "total": 1, "page": 1, "size": 20, "total_pages": 1,
+ "has_next": false, "has_previous": false
+ }
+ ```
+
+ Those are exactly the `Page[T]` members from the table above, serialised by `PageDto`. The client renders a pager straight from this shape — no extra count query needed.
+
---
## Specifications: composable, reusable filters
-Derived queries answer fixed questions. Sometimes you want a **reusable predicate** you can compose at the call site — "wallets with at least this balance," combined freely with other conditions. That is what a `Specification` is: a small object wrapping a `WHERE` fragment, composable with `&`, `|`, and `~`.
+Derived queries answer fixed questions. Sometimes you want a **reusable predicate** — a `WHERE` condition you can name once and reuse — that you compose at the call site: "wallets with at least this balance," combined freely with other conditions. That is what a `Specification` is: a small object wrapping a `WHERE` fragment, composable with `&` (AND), `|` (OR), and `~` (NOT).
-Lumen defines one as a module-level factory and uses it in a `find_rich` method:
+We build it in two steps: a factory that *returns* a `Specification`, then a repository method that *runs* it.
+
+**Step 1 — write a factory that returns a `Specification`.** It takes the parameter (the minimum balance) and returns a predicate object. **Step 2 — add a repository method that runs it** through the inherited `find_all_by_spec_paged`. Lumen does both in one file:
::: listing lumen/models/repositories/wallet_repository.py | Listing 5.6 — A Specification factory and a method that runs it paged
def balance_at_least(min_minor: int) -> Specification[WalletEntity]:
@@ -313,6 +418,22 @@ class ListRichWalletsHandler(
`GET /api/v1/wallets/rich?min_minor=1000&page=1&size=20` now returns a page of wallets at or above €10.00, newest first.
+!!! note "Run it: filter to the rich wallets"
+ Open one wallet and deposit €25.00 into it (2500 minor units), open another and leave it empty, then ask for wallets with at least €10.00:
+
+ ```bash
+ curl -s 'localhost:8080/api/v1/wallets/rich?min_minor=1000&page=1&size=20'
+ ```
+
+ Only the funded wallet comes back, and `total` counts just the matches — the empty wallet is filtered out by the `Specification`:
+
+ ```json
+ {"items": [{"id": "wlt-...", "balance_minor": 2500, "balance": 25.0, ...}],
+ "total": 1, "page": 1, "total_pages": 1, "has_next": false}
+ ```
+
+ The same predicate (`balance_at_least`) that runs here can be combined with others using `&`, `|`, and `~` — that is the payoff of writing the filter as a `Specification` instead of a one-off query.
+
!!! note "Filters without lambdas"
For the common case — equality and a handful of comparisons — you don't even need to write a lambda. `FilterOperator.gte("balance_minor", 1000) & FilterOperator.eq("currency", "EUR")` produces the same composable `Specification` from static factory methods, and `FilterUtils.by(currency="EUR")` builds one from keyword arguments (Query-by-Example). Lumen uses an explicit lambda here because the intent reads clearly; both styles produce a `Specification` you can pass to the same repository methods.
@@ -320,9 +441,11 @@ class ListRichWalletsHandler(
## Projections: read only the columns you need
-The balance endpoint does not need the whole row — just the id, currency, and a computed balance. PyFly supports **interface projections**, Spring Data's idea of declaring the subset of fields a read-view wants and letting the framework copy exactly those.
+The balance endpoint does not need the whole row — just the id, currency, and a computed balance. PyFly supports **interface projections**, Spring Data's idea of declaring the subset of fields a read-view wants and letting the framework copy exactly those. (A *projection* is a read-only view onto a subset of an entity's columns — you name the few fields you care about, and the framework copies only those, leaving the rest of the row unread.)
-A projection is a class marked `@projection`. In Lumen it is a concrete dataclass:
+Building one takes three pieces: the projection class, the mapper that knows how to fill it, and the handler that uses it. We take them in order.
+
+**Step 1 — declare the projection.** A projection is a class marked `@projection`. In Lumen it is a concrete dataclass:
::: listing lumen/interfaces/dtos/v1/balance_dto.py | Listing 5.8 — BalanceView: a @projection of just the balance fields
from dataclasses import dataclass
@@ -346,7 +469,7 @@ class BalanceView:
balance: float
:::
-The mapper reads those four fields off a `WalletEntity` and constructs the view. Three (`id`, `currency`, `balance_minor`) are copied straight across; the fourth (`balance`, the major-unit decimal) is supplied by a transform registered on the mapper:
+**Step 2 — register the projection on a `Mapper`.** A `Mapper` is the framework helper that copies entity fields onto a projection. It reads those four fields off a `WalletEntity` and constructs the view. Three (`id`, `currency`, `balance_minor`) are copied straight across; the fourth (`balance`, the major-unit decimal) is supplied by a *transform* — a small function registered against a field name that computes a value the entity does not store directly:
::: listing lumen/core/mappers/wallet_mapper.py | Listing 5.9 — Registering and running the projection via Mapper
from pyfly.data import Mapper
@@ -370,7 +493,7 @@ def entity_to_balance_dto(entity: WalletEntity) -> BalanceDto:
)
:::
-`Mapper.project(entity, BalanceView)` reads only the declared fields, applies the `balance` transform, and returns a `BalanceView`. The query handler then loads the row by id and projects it:
+**Step 3 — use the projection from a read handler.** `Mapper.project(entity, BalanceView)` reads only the declared fields, applies the `balance` transform, and returns a `BalanceView`. The query handler then loads the row by id and projects it:
::: listing lumen/core/services/wallets/get_balance_handler.py | Listing 5.10 — The balance read handler: find by id, then project
@query_handler
@@ -391,6 +514,19 @@ class GetBalanceHandler(QueryHandler[GetBalance, BalanceDto | None]):
)
:::
+!!! note "Run it: read just the balance"
+ The balance endpoint returns only the four projected fields, not the whole row. Against a running app with a funded wallet:
+
+ ```bash
+ curl -s localhost:8080/api/v1/wallets/wlt-.../balance
+ ```
+
+ ```json
+ {"id": "wlt-...", "currency": "EUR", "balance_minor": 2500, "balance": 25.0}
+ ```
+
+ No `owner_id`, no `created_at` — the projection declared four fields, so four fields are read and returned. `balance` (the major-unit `25.0`) is the computed transform; the rest are copied straight from the row.
+
!!! warning "A projection must be instantiable"
Spring lets a projection be a bare interface and returns a runtime proxy. Python has no such proxy, so a PyFly projection must be a **concrete** type the mapper can construct — here, a `@dataclass`. Marking a *Protocol* `@projection` will not work: a Protocol cannot be instantiated, and `Mapper.project` has nothing to build. Use a dataclass (or any plain class with matching fields) and you are safe.
@@ -402,9 +538,11 @@ The repository surface is clean — but two honest subtleties decide whether you
### save() flushes; it does not commit
-This is the single most important thing to understand about the data layer. The framework uses **one shared `AsyncSession`**, and `Repository.save()` calls `session.add()` followed by `session.flush()` and `session.refresh()` — it **flushes**, making the write visible *within* the current session, but it never **commits**. If nothing commits, the write is rolled back when the session closes and the wallet does not survive a restart.
+This is the single most important thing to understand about the data layer. Two database verbs are easy to confuse. To **flush** is to send the pending SQL (the `INSERT`/`UPDATE`) to the database so it is visible to *this* connection's later reads — but still inside an open transaction that can be undone. To **commit** is to make those changes permanent and visible to everyone. A flush without a commit is rolled back when the session closes.
+
+The framework uses **one shared `AsyncSession`**, and `Repository.save()` calls `session.add()` followed by `session.flush()` and `session.refresh()` — it **flushes**, making the write visible *within* the current session, but it never **commits**. If nothing commits, the write is rolled back when the session closes and the wallet does not survive a restart. (This is exactly the disappearing-wallet problem from the opening **Run it** box.)
-The commit happens at the **unit-of-work boundary**, and you declare that boundary with `@transactional()`. A handler that writes decorates its `do_handle` with `@transactional()`, injects the `async_sessionmaker` as `self._session_factory`, and the decorator opens a unit of work, swaps that transactional session onto the repository for the call, **commits on success**, and rolls back on failure:
+The commit happens at the **unit-of-work boundary**. (A *unit of work* is one all-or-nothing batch of changes: either every write in it commits together, or — if anything fails — none of them do.) You declare that boundary with `@transactional()`. A handler that writes decorates its `do_handle` with `@transactional()`, injects the `async_sessionmaker` — the factory that hands out sessions — as `self._session_factory`, and the decorator opens a unit of work, swaps that transactional session onto the repository for the call, **commits on success**, and rolls back on failure:
::: listing lumen/core/services/wallets/open_wallet_handler.py | Listing 5.11 — A write handler: @transactional() commits the unit of work
@command_handler
@@ -444,9 +582,12 @@ class OpenWalletHandler(CommandHandler[OpenWallet, str]):
`@transactional()` (imported from `pyfly.data.relational.sqlalchemy`) resolves the `async_sessionmaker` from `self._session_factory`, runs the body inside a `session.begin()` block, and commits at the end. Drop the decorator and the `upsert` would only flush — the wallet would never reach disk. The read handlers earlier in this chapter need no `@transactional`: a read makes no changes to commit.
+!!! note "What just happened"
+ The rule in one line: **reads need nothing; writes need `@transactional()`.** `save`/`upsert` only *flush*, so a write handler must run inside a unit of work that commits. The decorator does three things for you — opens the transaction, hands the repository the right session for the call, and commits (or rolls back on an exception). This is why the opening wallet survived once persistence was on, and why removing the decorator would silently lose it.
+
### upsert, not save, for an aggregate that owns its id
-Notice the handler calls `self._repository.upsert(...)`, not `save(...)`. That is the second subtlety. The framework's `save()` issues `session.add()`, which SQLAlchemy treats as a **pending INSERT**. But the `Wallet` aggregate generates its *own* primary key up front (`wlt-…`), so by the time a deposit or withdrawal persists an already-loaded wallet, a row with that id already exists — and a second `INSERT` on the same primary key raises `IntegrityError`.
+Notice the handler calls `self._repository.upsert(...)`, not `save(...)`. (*Upsert* is the portmanteau verb for "insert if new, update if already present" — one call for both cases.) That is the second subtlety. The framework's `save()` issues `session.add()`, which SQLAlchemy treats as a **pending INSERT**. But the `Wallet` aggregate generates its *own* primary key up front (`wlt-…`), so by the time a deposit or withdrawal persists an already-loaded wallet, a row with that id already exists — and a second `INSERT` on the same primary key raises `IntegrityError`.
The fix is `session.merge`, which inserts when the id is new and updates when it already exists. Lumen wraps it in an `upsert` convenience method:
@@ -471,6 +612,9 @@ class WalletRepository(Repository[WalletEntity, str]):
`_require_session()` is the inherited accessor that returns the active session (the transactional one, once `@transactional` has swapped it in). `merge` keys on the primary key, so both the first write (open) and every later write (deposit, withdraw) take the same code path with no `IntegrityError`. For entities whose ids are database-generated, `save` is the natural choice; for an aggregate that owns its id, `upsert` is.
+!!! note "What just happened"
+ Two questions decide every write: *did this row commit?* and *did this write insert or update?* `@transactional()` answers the first (it commits the unit of work); `upsert`/`merge` answers the second (one code path for both INSERT and UPDATE, because the aggregate owns its id). Get both right and a wallet you open, then deposit into, then read back after a restart returns the correct balance — which is exactly what the repository test below asserts against a *fresh* engine.
+
### The aggregate ↔ entity mapper seam
There is one more boundary, and it is a feature, not an accident. Lumen keeps two distinct types:
@@ -513,7 +657,7 @@ The write side calls `to_entity` before `upsert`; the read side either rehydrate
## Turning it on
-Activating the relational layer is configuration, not code. Lumen's `pyfly.yaml` carries a `data.relational` block:
+Activating the relational layer is configuration, not code — three keys in `pyfly.yaml`. Add a `data.relational` block:
::: listing pyfly.yaml | Listing 5.14 — Relational data layer configuration
pyfly:
@@ -528,6 +672,31 @@ pyfly:
The dependency footprint is tiny: `pyfly[data-relational]` pulls in `sqlalchemy[asyncio]` and `aiosqlite`, and nothing else. No database server, no driver install — which is exactly why the sample runs anywhere.
+!!! note "Run it: the disappearing wallet, fixed"
+ Re-run the opening experiment, now with persistence on. Open a wallet, stop the app, start it again, and read the balance back:
+
+ ```bash
+ # Terminal 1
+ uv run pyfly run --server uvicorn
+
+ # Terminal 2 — open a wallet
+ curl -s -X POST localhost:8080/api/v1/wallets \
+ -H 'content-type: application/json' \
+ -d '{"owner_id": "alice", "currency": "EUR"}'
+ # -> {"wallet_id": "wlt-..."}
+
+ # Ctrl+C in Terminal 1, then start it again, then:
+ curl -s localhost:8080/api/v1/wallets/wlt-.../balance
+ ```
+
+ This time the wallet survives — its row was committed to `lumen.db` on disk:
+
+ ```json
+ {"id": "wlt-...", "currency": "EUR", "balance_minor": 0, "balance": 0.0}
+ ```
+
+ Look in the project directory and you will see the `lumen.db` SQLite file the engine created on first boot, with the `wallets` table inside it. The whole chapter comes down to this: the wallet outlives the process.
+
!!! tip "Schema lifecycle in production"
`ddl-auto: create` is right for development and samples: it creates missing tables and leaves existing ones alone. In production set `ddl-auto: none` and manage the schema with a migration tool (Alembic), which generates versioned scripts from the diff between `Base.metadata` and the live database. The application code does not change — only the `ddl-auto` setting and the migration pipeline.
@@ -590,6 +759,26 @@ The first test drives the derived query: three wallets in, two owners out, and `
The fixture mirrors what the framework does at startup — build the engine, run `Base.metadata.create_all` inside a `begin()` block so the DDL commits, hand back a session factory — so the test exercises the exact table the application creates. Other tests in the same file prove `upsert` round-trips through a *fresh* engine (durability across reconnect) and that `find_all(pageable)` counts and slices a five-wallet table correctly.
+!!! note "Run it: prove the whole layer green"
+ Run the repository test file end to end. From the Lumen project root:
+
+ ```bash
+ uv run --extra dev pytest tests/test_sql_wallet_repository.py -v
+ ```
+
+ Each named test reports `PASSED` — CRUD round-trip, durability across reconnect, the derived query, the specification path, and pagination:
+
+ ```
+ tests/test_sql_wallet_repository.py::test_upsert_inserts_then_updates_and_persists PASSED
+ tests/test_sql_wallet_repository.py::test_find_by_id_unknown_returns_none PASSED
+ tests/test_sql_wallet_repository.py::test_derived_find_by_owner_id PASSED
+ tests/test_sql_wallet_repository.py::test_specification_find_rich_paged_and_sorted PASSED
+ tests/test_sql_wallet_repository.py::test_find_all_pageable_counts_and_pages PASSED
+ 6 passed in 0.31s
+ ```
+
+ Run the whole suite (`uv run --extra dev pytest -q`) to confirm the rest of Lumen still passes alongside the persistence layer.
+
!!! spring "Spring parity"
Constructing the repository directly against a real in-process database mirrors Spring's `@DataJpaTest` slice, which boots an H2 database and the JPA layer in isolation to test repositories without the full context. `Base.metadata.create_all` is the analogue of `spring.jpa.hibernate.ddl-auto=create`, and running `RepositoryBeanPostProcessor` by hand stands in for the Spring proxy that materialises derived queries on a `JpaRepository` at startup.
diff --git a/book/manuscript/06-domain-driven-design.md b/book/manuscript/06-domain-driven-design.md
index 7928802a..52170ede 100644
--- a/book/manuscript/06-domain-driven-design.md
+++ b/book/manuscript/06-domain-driven-design.md
@@ -18,6 +18,9 @@ Before you can build a model that enforces its own rules, you need a vocabulary
Think about what makes two wallets distinct. Even if two wallets happen to hold exactly one hundred euros, they are still separate wallets belonging to separate owners — you care *which one* you have. Now think about the amount itself. One hundred euros is one hundred euros; the exact Python object that holds the value is irrelevant. If a deposit adds fifty euros to a wallet's balance, you do not want to update the existing amount in place — you want to derive a brand-new amount that records the result. Mutating in place invites aliasing bugs where two parts of the code unknowingly share a reference to the same object and see each other's changes.
+!!! note "Jargon, in plain language"
+ A few words recur throughout this chapter. An **invariant** is a rule that must always hold — for a wallet, "the balance is never negative." An **aggregate** is a small cluster of objects that change together and must stay consistent as a group. An **aliasing bug** happens when two pieces of code accidentally hold the *same* object and one mutates it, surprising the other. Keep these three in mind; the rest of the chapter is largely about preventing the last one and guaranteeing the first inside the second.
+
DDD names these two roles **entities** and **value objects**, and PyFly's `pyfly.domain` module makes them first-class concepts:
| Concept | PyFly base | Equality | Mutation |
@@ -105,6 +108,55 @@ The `currency` field uses the `Currency` enum (`Currency.EUR`, `Currency.USD`, `
Both `add` and `subtract` return a *new* `Money` instance rather than modifying `self`, a direct consequence of `frozen=True`. This immutability guarantee means the aggregate holding a `Money` value can never be partially updated: either the whole replacement succeeds or the old value remains in place. The `is_positive` and `is_negative` properties expose the sign without leaking the raw integer. `major_units` converts to a decimal for display, and `__str__` formats as `"10.50 EUR"` via `currency.value`.
+**Build it step by step.** If you are creating `Money` from scratch, here is the order to write it in, and why each line matters.
+
+Step 1 — Declare the two fields and freeze the class. Add `amount: int` and `currency: Currency` to a class decorated with `@dataclass(frozen=True)` that subclasses `ValueObject`. `frozen=True` is what makes the object immutable and gives you structural equality for free: two `Money` instances with the same amount and currency are now `==`.
+
+Step 2 — Guard the constructor. Add `__post_init__` to reject anything that is not a plain integer. The `isinstance(self.amount, bool)` check is deliberate — in Python `True` is an `int`, and you do not want `Money(True, ...)` slipping through.
+
+Step 3 — Add the `zero` factory. A wallet opens at a zero balance, so `Money.zero(currency)` reads better at the call site than `Money(0, currency)`.
+
+Step 4 — Add `add` and `subtract`, each routing through `_assert_same_currency` first. Returning a brand-new `Money` (never mutating `self`) is what prevents the aliasing bug from the section opener.
+
+Step 5 — Add the display helpers: `is_positive`, `is_negative`, `major_units`, and `__str__`.
+
+**Run it.** `Money` has no dependency on the framework runtime or a database, so you can exercise every rule from a Python prompt. Start one with `uv run python` from the `samples/lumen` directory and type:
+
+```python
+>>> from lumen.models.entities.v1.money import Money
+>>> from lumen.interfaces.enums.v1.currency import Currency
+>>> ten_fifty = Money(1050, Currency.EUR)
+>>> str(ten_fifty)
+'10.50 EUR'
+>>> ten_fifty.add(Money(450, Currency.EUR))
+Money(amount=1500, currency=)
+>>> ten_fifty.add(Money(100, Currency.USD))
+Traceback (most recent call last):
+ ...
+pyfly.domain.exceptions.BusinessRuleViolation: cannot combine EUR with USD
+>>> Money(10.5, Currency.EUR)
+Traceback (most recent call last):
+ ...
+pyfly.domain.exceptions.BusinessRuleViolation: amount must be an integer number of minor units
+```
+
+The two tracebacks are the point: the model refuses a cross-currency sum and a float amount *at the moment you make the mistake*, not three layers deeper during reconciliation.
+
+Lumen ships these exact behaviours as tests. Run them with:
+
+```
+uv run --extra dev pytest tests/test_money.py -q
+```
+
+and you should see all six pass:
+
+```
+...... [100%]
+6 passed in 0.0Xs
+```
+
+**What just happened.** You built a value object that is impossible to misuse: it cannot be mutated, it cannot mix currencies, and it cannot hold a float. Every other piece of the wallet model will lean on these guarantees, which is why `Money` comes first.
+
!!! note "Minor units vs decimal"
Storing money as integer cents is one convention; another is Python's `decimal.Decimal` with a fixed scale. Both are valid. What matters is picking one and sticking to it within the bounded context. For Lumen, integer minor units keep the model free of import-time precision configuration, and `__post_init__` enforces the constraint with `BusinessRuleViolation("money-amount-integer")` so a float never silently enters the model.
@@ -264,6 +316,55 @@ class Wallet(AggregateRoot[str]):
**How it works.** The aggregate boundary is enforced at three levels. First, `__slots__` locks the attribute set, and `balance` and `owner_id` are deliberately public-but-owned: only the aggregate's own methods (`deposit`, `withdraw`) mutate them, while the `currency` property is a read-only convenience that delegates to `balance.currency`. Second, the factory classmethod `open` is the sole legitimate way to create a new wallet: the caller supplies the `wallet_id` (so the application layer controls ID generation), `open` validates that `owner_id` is non-blank, initializes the balance with `Money.zero(currency)`, and immediately queues `WalletOpened`. Using a factory rather than calling `__init__` directly ensures the opening event is *never* forgotten, even in a test fixture. Third, the domain events — `WalletOpened`, `FundsDeposited`, `FundsWithdrawn` — are frozen dataclasses. `FundsDeposited` and `FundsWithdrawn` carry a `balance` field (the post-operation balance in minor units), so a subscriber never needs to call back into the aggregate to learn the current state.
+**Build it step by step.** The `Wallet` class has more moving parts than `Money`, so here is the order to assemble it.
+
+Step 1 — Define the three event classes first (`WalletOpened`, `FundsDeposited`, `FundsWithdrawn`), each a `@dataclass(frozen=True)` subclass of `DomainEvent`. They have to exist before the aggregate can reference them. We cover events in depth in the next section but two; for now they are just the records the wallet will emit.
+
+Step 2 — Declare the aggregate. Subclass `AggregateRoot[str]` (the `[str]` says the id is a string), set `__slots__` to lock the attribute names, and write `__init__` to store `owner_id`, `balance`, and `created_at`. Call `super().__init__(id)` first so the base class sets up the id and the internal event buffer.
+
+Step 3 — Add the `currency` read-only property that delegates to `self.balance.currency`. This is a convenience that keeps callers from reaching two levels deep into `wallet.balance.currency`.
+
+Step 4 — Write the `open` factory classmethod. It validates `owner_id`, builds the wallet with a `Money.zero(currency)` balance, and calls `self.raise_event(WalletOpened(...))`. Making `open` a classmethod — rather than expecting callers to use `__init__` plus a manual event — guarantees the opening event is never forgotten.
+
+Step 5 — Write `deposit` and `withdraw`. Each one validates first (currency match, positive amount, and for withdraw, sufficient funds), *then* mutates `self.balance`, *then* raises its event. Order matters: never mutate before every check has passed, or you can leave the wallet in a half-changed state.
+
+Step 6 — Add the private `_assert_currency` helper that both transitions share.
+
+!!! note "raise_event is not raising an exception"
+ Despite the name, `raise_event` does not throw anything. It *appends* an event to an internal buffer on the aggregate (`AggregateRoot._pending_events`). Nothing is published at that moment. A later step — the application service, after a successful save — drains the buffer with `clear_events()` and hands the events to the event bus. Think of `raise_event` as "make a note that this happened", not "abort".
+
+**Run it.** Like `Money`, the `Wallet` aggregate is pure Python — no database needed. From `uv run python`:
+
+```python
+>>> from lumen.models.entities.v1.wallet_entity import Wallet
+>>> from lumen.models.entities.v1.money import Money
+>>> from lumen.interfaces.enums.v1.currency import Currency
+>>> w = Wallet.open("wlt-1", "owner-1", Currency.EUR)
+>>> w.deposit(Money(1000, Currency.EUR))
+>>> w.withdraw(Money(400, Currency.EUR))
+>>> str(w.balance)
+'6.00 EUR'
+>>> [e.event_type for e in w.pending_events()]
+['WalletOpened', 'FundsDeposited', 'FundsWithdrawn']
+>>> w.withdraw(Money(9999, Currency.EUR))
+Traceback (most recent call last):
+ ...
+pyfly.domain.exceptions.BusinessRuleViolation: cannot withdraw 99.99 EUR; balance is 6.00 EUR
+```
+
+Notice the three events sitting in the buffer after the successful operations, and notice that the overdraft attempt raised *before* touching the balance — `pending_events()` still shows three, not four. Lumen's test suite asserts exactly this:
+
+```
+uv run --extra dev pytest tests/test_wallet_aggregate.py -q
+```
+
+```
+...... [100%]
+6 passed in 0.0Xs
+```
+
+**What just happened.** The wallet now owns its rules. There is no way to overdraw it, no way to feed it the wrong currency, and no way to change its state without leaving an event behind that records what happened. The service layer no longer has to remember any of that.
+
The diagram below shows the complete picture: state, invariants, and the events the wallet emits.
::: figure art/figures/06-aggregate.svg | Figure 6.1 — The Wallet aggregate: state, invariants, and the events it emits.
@@ -287,6 +388,34 @@ All three are enforced inside the aggregate methods. The framework exception for
`BusinessRuleViolation` extends `pyfly.kernel.BusinessException`, so the RFC 7807 problem-details mapper from Chapter 4 translates it automatically into an HTTP 422 response — no extra handler required.
+!!! note "What RFC 7807 means here"
+ RFC 7807 is the web standard for "problem details" — a small, predictable JSON shape (`type`, `title`, `status`, `detail`, plus your own fields) that an API returns when something goes wrong. PyFly's mapper turns any `BusinessException` into one of these automatically, so the `rule` slug you set on `BusinessRuleViolation` ends up in the response body where a client can read it without parsing English prose.
+
+**See the invariant hold.** The promise of an invariant is that a *failed* operation leaves the model exactly as it was. You can prove that from `uv run python`:
+
+```python
+>>> from lumen.models.entities.v1.wallet_entity import Wallet
+>>> from lumen.models.entities.v1.money import Money
+>>> from lumen.interfaces.enums.v1.currency import Currency
+>>> from pyfly.domain import BusinessRuleViolation
+>>> w = Wallet.open("wlt-1", "owner-1", Currency.EUR)
+>>> w.deposit(Money(500, Currency.EUR))
+>>> w.clear_events() # drain the open + deposit events
+[WalletOpened(...), FundsDeposited(...)]
+>>> try:
+... w.withdraw(Money(501, Currency.EUR))
+... except BusinessRuleViolation as exc:
+... print(exc.rule)
+...
+wallet-insufficient-funds
+>>> str(w.balance) # unchanged — the rule fired before any mutation
+'5.00 EUR'
+>>> w.pending_events() # and no event was queued for the failed attempt
+[]
+```
+
+That is the whole guarantee in three lines: the rule slug is stable and machine-readable, the balance did not move, and no event leaked for an operation that never happened.
+
!!! warning "Keep invariants in the model, not the service"
Moving the overdraft check back into `WalletService` creates two problems. First, any code that calls `repo.save(entity)` directly bypasses the check entirely. Second, you end up duplicating the rule across every path that modifies a wallet — the service, a background job, an admin command. When the rule changes — say, the product team introduces a configurable overdraft buffer — there is exactly one place to update: the aggregate method. That is the whole point.
@@ -407,6 +536,24 @@ def demonstrate_event_fields() -> None:
Notice that `FundsDeposited` carries both `amount` (the transaction) and `balance` (the post-operation balance, in minor units). A subscriber updating a read-model balance needs no callback into the aggregate or the database — everything is in the event. That self-contained design keeps consumers simple and eliminates extra round-trips.
+!!! note "Read-model, in plain language"
+ A **read-model** is a separate, query-optimised copy of data shaped for displaying — a dashboard total, a search index, a cache. Because `FundsDeposited` already carries the post-operation `balance`, a service that maintains such a copy can apply the event blindly without ever loading the wallet again. We build read-models properly in a later chapter; here, just note why putting `balance` in the event pays off.
+
+**Run it.** You can see the three auto-populated fields on any event from `uv run python`:
+
+```python
+>>> from lumen.models.entities.v1.wallet_entity import FundsDeposited
+>>> evt = FundsDeposited(wallet_id="w-1", amount=5000, currency="EUR", balance=15000)
+>>> evt.event_type
+'FundsDeposited'
+>>> evt.event_id # a fresh UUID, set by DomainEvent.__post_init__
+'3fa85f64-5717-4562-b3fc-2c963f66afa6'
+>>> evt.occurred_at # a UTC timestamp, also set automatically
+datetime.datetime(2026, 6, 16, 9, 30, 0, tzinfo=datetime.timezone.utc)
+```
+
+You declared four fields; you got seven, because `DomainEvent` contributes `event_id`, `occurred_at`, and the `event_type` property. That is the whole appeal of subclassing it — every event is self-identifying with zero extra code.
+
The event lifecycle spans two phases. Inside the aggregate: when `wallet.deposit(amount)` succeeds, it calls `self.raise_event(FundsDeposited(...))`, appending the event to a private buffer in `AggregateRoot`. Nothing is published yet. At the service boundary: after the repository saves the aggregate and the transaction commits, the application service drains the buffer and publishes. This *save-first, publish-after* sequence guarantees that an event is never dispatched for a change that failed to persist. Listing 6.6 shows that boundary in full:
::: listing lumen/wallet_application_service.py | Listing 6.6 — Draining domain events after a successful save
@@ -456,6 +603,18 @@ class WalletApplicationService:
**How it works.** `open_wallet` calls `Wallet.open`, which queues a `WalletOpened` event internally; after the `save`, `wallet.clear_events()` returns that one event and `publish` dispatches it. `deposit` follows the same three-step pattern: load, mutate, save — then drain. The `for event in wallet.clear_events()` loop is intentionally explicit rather than hidden inside the repository, because the application service is the right place to decide *when* publishing happens — after the transaction boundary, not before.
+**The publish cycle, step by step.** Every command method in the application service follows the same four-beat rhythm. Learn it once and every future use-case (transfer, refund, freeze) writes itself:
+
+Step 1 — Load (or create). For a new wallet, call the `Wallet.open` factory; for an existing one, `await self._repo.find(wallet_id)`.
+
+Step 2 — Mutate through a behaviour method. Call `wallet.deposit(...)` or `wallet.withdraw(...)`. This is where the invariants run and the events get queued in the aggregate's buffer.
+
+Step 3 — Save. `await self._repo.save(wallet)`. Nothing has been published yet, on purpose — if the save fails, no event escapes.
+
+Step 4 — Drain and publish. `for event in wallet.clear_events(): await self._events.publish(event)`. This runs only after the save succeeds, so an event is never dispatched for a change that did not persist.
+
+**What just happened.** The aggregate decides *what* happened and records it; the application service decides *when* the world hears about it. Keeping those two responsibilities apart is why the wallet stays free of any broker, queue, or transaction code — and why the publish order is "save first, publish after."
+
!!! tip "Event ordering"
`raise_event` appends to the buffer in call order. `clear_events` drains and clears it, returning events in the same order. If a single aggregate method raises multiple events (a batch operation, for example), they arrive at the event bus in the order they were raised — oldest first.
@@ -541,6 +700,35 @@ def to_aggregate(entity: WalletEntity) -> Wallet:
`to_entity` writes `wallet.balance.amount` (an integer) directly into `balance_minor` — no float conversion. `to_aggregate` reconstructs a `Currency` enum from the stored ISO-4217 string via `Currency(entity.currency)`, then builds a `Money` from the raw integer minor-unit value. The `created_at` field is preserved on the round-trip so rehydrated aggregates carry their original timestamp. There is no floating-point boundary crossing anywhere.
+**Build the mapper step by step.** A mapper is just two pure functions. There is no framework magic to wire up; you write them and call them at the right moments.
+
+Step 1 — Write `to_entity(wallet)`. Read each piece of the aggregate and copy it into the flat row: `wallet.id`, `wallet.owner_id`, `wallet.currency.value` (the ISO string, not the enum), `wallet.balance.amount` (the raw integer minor units), and `wallet.created_at`. The `assert wallet.id is not None` makes the precondition explicit — you only persist wallets that already have an id.
+
+Step 2 — Write `to_aggregate(entity)`, the reverse. Rebuild the `Currency` enum from the stored string with `Currency(entity.currency)`, wrap the integer back into a `Money`, and construct a `Wallet`. Passing `created_at=entity.created_at` preserves the original timestamp across the round-trip.
+
+Step 3 — Call them at the boundary, not inside the aggregate. The command handler calls `to_entity` just before `repo.save(...)` and `to_aggregate` just after `repo.find(...)`. The `Wallet` class never imports the row, and the row never imports the `Wallet`.
+
+**Run it.** The round-trip is pure Python — no live database required to prove it preserves every field. From `uv run python`:
+
+```python
+>>> from lumen.models.entities.v1.wallet_entity import Wallet
+>>> from lumen.models.entities.v1.money import Money
+>>> from lumen.interfaces.enums.v1.currency import Currency
+>>> from lumen.core.mappers import wallet_mapper
+>>> w = Wallet.open("wlt-1", "owner-1", Currency.EUR)
+>>> w.deposit(Money(2500, Currency.EUR))
+>>> row = wallet_mapper.to_entity(w) # aggregate -> flat row
+>>> (row.id, row.currency, row.balance_minor)
+('wlt-1', 'EUR', 2500)
+>>> back = wallet_mapper.to_aggregate(row) # flat row -> aggregate
+>>> str(back.balance), back.owner_id
+('25.00 EUR', 'owner-1')
+```
+
+The integer `2500` crosses both directions untouched — no float ever appears at the persistence boundary, which is the whole reason `Money` stores minor units.
+
+**What just happened.** You kept two models that never import each other and bridged them with two tiny functions. A schema change now touches only `WalletEntity`; a rule change touches only `Wallet`. Neither can break the other by accident.
+
The mapper is intentionally narrow. It does not enforce rules — `Wallet.__init__` and the behaviour methods do that. It does not publish events — the application service does that. It only translates shape.
**The repository.** The application service never interacts with `WalletEntity` directly. Instead a command handler calls `wallet_mapper.to_entity(wallet)` before persisting and `wallet_mapper.to_aggregate(entity)` after loading, while the framework `WalletRepository(Repository[WalletEntity, str])` handles all SQL. Chapter 5 covers `Repository` in full; the key point here is that `Wallet` itself never imports SQLAlchemy — the aggregate stays free of persistence concerns across both sides of the mapper boundary.
@@ -610,6 +798,39 @@ def filter_eligible(
**How it works.** `HasPositiveBalance` delegates to `wallet.balance.is_positive` (a property, no parentheses). `IsInCurrency` uses identity comparison (`is`) because `Currency` is a `StrEnum` with singleton members. The `eligible_for_withdrawal` factory combines them with `&`, producing a composite whose `is_satisfied_by` returns `True` only when both checks pass. Because `Specification` implements `__call__`, you pass the composite directly to `filter()` — no lambda wrapper needed.
+**Build a specification step by step.**
+
+Step 1 — Subclass `Specification[Wallet]` and implement the single required method, `is_satisfied_by(self, wallet) -> bool`. That is the entire contract: return `True` or `False`, never raise.
+
+Step 2 — If the rule needs a parameter (like a currency to match), take it in `__init__` and store it, as `IsInCurrency` does. A parameterless rule like `HasPositiveBalance` skips this.
+
+Step 3 — Compose with the Boolean operators. `HasPositiveBalance() & IsInCurrency(currency)` builds a new specification whose `is_satisfied_by` is true only when both halves are. `|` is or, `~` is not.
+
+Step 4 — Use it as a predicate. Because `Specification` implements `__call__`, the composite *is* a callable, so you can hand it straight to Python's built-in `filter()` with no lambda in between.
+
+**Run it.** Specifications are plain objects. Drop the classes from Listing 6.9 into a module (say `src/lumen/domain/specs.py`) and try them from `uv run python`:
+
+```python
+>>> from lumen.models.entities.v1.wallet_entity import Wallet
+>>> from lumen.models.entities.v1.money import Money
+>>> from lumen.interfaces.enums.v1.currency import Currency
+>>> from lumen.domain.specs import eligible_for_withdrawal
+>>> empty = Wallet.open("wlt-1", "owner-1", Currency.EUR)
+>>> funded = Wallet.open("wlt-2", "owner-2", Currency.EUR)
+>>> funded.deposit(Money(1000, Currency.EUR))
+>>> usd = Wallet.open("wlt-3", "owner-3", Currency.USD)
+>>> usd.deposit(Money(1000, Currency.USD))
+>>> spec = eligible_for_withdrawal(Currency.EUR)
+>>> spec(funded), spec(empty), spec(usd)
+(True, False, False)
+>>> [w.id for w in filter(spec, [empty, funded, usd])]
+['wlt-2']
+```
+
+Only the funded EUR wallet satisfies both halves of the composite, so `filter` keeps just that one.
+
+**What just happened.** You expressed a read-only business rule as a named, reusable object instead of an inline `if`. It composes with other rules at runtime, it passes straight into `filter`, and it is trivial to unit-test in isolation — and crucially, it lives *outside* the aggregate, where eligibility checks belong.
+
The key design discipline: a specification is a *predicate*, not a *guard*. It returns `True` or `False` and never raises. Aggregate invariants (overdraft, currency mismatch) belong inside `deposit` and `withdraw` because they must *prevent* a state change. Specifications belong in services and query handlers because they *select* or *classify* — they never mutate.
Specifications are especially useful where rules combine dynamically: an admin search that adds filters based on the operator's role, or a batch job that partitions a list into eligible and ineligible wallets. Each class has exactly one method and no side-effects, making isolated unit tests trivial.
diff --git a/book/manuscript/07-cqrs.md b/book/manuscript/07-cqrs.md
index 8936c73a..0a6452ee 100644
--- a/book/manuscript/07-cqrs.md
+++ b/book/manuscript/07-cqrs.md
@@ -10,6 +10,11 @@ Lumen's wallet is now a first-class citizen of the domain. The `Wallet` aggregat
By the end of this chapter Lumen's controller dispatches commands and queries instead of calling the service directly. `OpenWallet`, `DepositFunds`, and `WithdrawFunds` travel the command path; `GetWallet`, `GetBalance`, `ListWallets`, and `ListRichWallets` travel the query path. The `Wallet` aggregate you built in Chapter 6 remains untouched — CQRS does not replace the domain model; it is the delivery mechanism for instructions to it.
+!!! note "New jargon, in plain terms"
+ A **bus** here is not hardware — it is a single object you hand a message to, and it figures out which handler should run. A **handler** is one small class that does the work for exactly one message type. A **DTO** (data transfer object) is a plain shape — id, owner, balance — that you put on the wire as JSON; it is deliberately separate from your rich domain object. A **projection** is a read-only slice of your data shaped for one specific view. You will meet each of these as we build, one piece at a time, so do not worry if they feel abstract right now.
+
+This chapter is built around PyFly **v26.6.110**, and every listing is taken verbatim from the Lumen sample under `samples/lumen/src/lumen`. We will go gently: build the commands first, then their handlers, then the queries, then wire everything into the controller — running the app and the tests at each milestone so you can see the pieces come alive before the next one is added.
+
---
## Why separate reads from writes
@@ -36,7 +41,12 @@ Before writing a single line of handler code, name your system's intentions. In
A command is a frozen dataclass that inherits from `Command[R]`, where `R` is the type the handler returns. The generic parameter is documentation and a type-checker hint; the bus does not enforce it at runtime.
-Lumen's commands live in three separate files under `lumen/core/services/wallets/`, one per intent. Here is the first:
+!!! note "What is `Command[R]`?"
+ The `[R]` in `Command[R]` is a *generic type parameter* — a placeholder for "whatever this command returns". `OpenWallet(Command[str])` says "sending me gives you back a `str`" (the new wallet id). `DepositFunds(Command[int])` says "sending me gives you back an `int`" (the new balance). Your editor and type checker use this to catch mistakes; at runtime the bus simply returns whatever the handler returned.
+
+Lumen's commands live in three separate files under `lumen/core/services/wallets/`, one per intent. We will build them one at a time.
+
+**Step 1 — Write the `OpenWallet` command.** Create `open_wallet_command.py`. It carries the two facts needed to open a wallet — who owns it and which currency it holds — and a `validate()` hook that rejects a blank owner before the bus ever looks for a handler.
::: listing lumen/core/services/wallets/open_wallet_command.py | Listing 7.1 — OpenWallet: a frozen command with built-in validation
from __future__ import annotations
@@ -62,7 +72,7 @@ class OpenWallet(Command[str]):
return ValidationResult.success()
:::
-And the deposit and withdrawal commands:
+**Step 2 — Write the `DepositFunds` and `WithdrawFunds` commands.** Each carries a `wallet_id` to target and an `amount` in minor units, and validates that the id is present and the amount is positive. They are deliberately near-identical twins — same shape, opposite direction.
::: listing lumen/core/services/wallets/deposit_funds_command.py | Listing 7.2 — DepositFunds: amount in minor units, no currency field
from __future__ import annotations
@@ -128,6 +138,9 @@ Four design choices are baked into every command:
- **Imperative-mood naming**: `DepositFunds`, not `WalletDeposit` or `DepositFundsCommand`. This makes the command log read like a business audit trail — a sequence of things that *happened* — rather than a list of technical operations.
+!!! note "What just happened"
+ You now have three small files, each describing *one thing the system can do*, with no logic beyond a couple of field checks. There are no handlers yet — these commands do nothing on their own. That is the point: a command is an envelope, not the worker who opens it. Next you will write the workers (the handlers) that actually carry out each intent.
+
### Implementing a command handler
A command handler inherits from `CommandHandler[C, R]` and implements exactly one method: `do_handle`. You write the *what*; the bus wraps it with the *how*.
@@ -136,7 +149,10 @@ A command handler inherits from `CommandHandler[C, R]` and implements exactly on
**`@transactional()` turns `do_handle` into a committed unit of work.** Command handlers inject `session_factory: async_sessionmaker[AsyncSession]` and store it as `self._session_factory`. When `@transactional()` runs `do_handle` it opens a fresh session from that factory, swaps it onto the repository for the duration of the call, commits on success, and rolls back on any exception. Without `@transactional()` the framework's shared session only flushes — the write survives within the request but is never committed to the database.
-Here is `OpenWalletHandler`:
+!!! note "Flush vs. commit, in plain terms"
+ A **flush** pushes your pending changes into the database connection so later queries in the *same* session can see them — but they are still inside an open transaction that can be rolled back. A **commit** makes them permanent. Without `@transactional()` your deposit would flush (visible mid-request) but never commit (gone after the request). The decorator is what makes the change stick.
+
+**Step 3 — Write `OpenWalletHandler`.** Now build the worker for the first command. Create `open_wallet_handler.py`, stack `@command_handler` over `@service`, inject the repository, the event publisher, and the session factory, and implement the single `do_handle` method.
::: listing lumen/core/services/wallets/open_wallet_handler.py | Listing 7.4 — OpenWalletHandler: @transactional() unit of work + upsert
from __future__ import annotations
@@ -190,7 +206,7 @@ Walk through `do_handle` step by step. `f"wlt-{uuid4()}"` generates a stable pre
Note the constructor requirement: `super().__init__()` is mandatory on `CommandHandler`. Skip it and the base-class bookkeeping — correlation context, lifecycle hooks — is never initialized. The repository, `EventPublisher`, and `session_factory` are all injected by the DI container from type hints; no factory configuration is needed.
-Here are the deposit and withdrawal handlers:
+**Step 4 — Write the deposit and withdrawal handlers.** These two add one move that `OpenWalletHandler` did not need: they *load* an existing wallet before acting on it. The shape is the same in both, differing only in whether they call `wallet.deposit(...)` or `wallet.withdraw(...)`.
::: listing lumen/core/services/wallets/deposit_funds_handler.py | Listing 7.5 — DepositFundsHandler: find_by_id → to_aggregate → act → upsert
from __future__ import annotations
@@ -290,6 +306,23 @@ class WithdrawFundsHandler(CommandHandler[WithdrawFunds, int]):
Notice what is absent: no try/except blocks, no logging calls, no tracing setup. All of that belongs to the bus pipeline. The handler is a pure expression of business intent.
+!!! note "What just happened"
+ The write side is now complete: three commands and three handlers. Sending `OpenWallet` creates and persists a fresh wallet; sending `DepositFunds` or `WithdrawFunds` loads one, drives its domain behaviour, and saves it. The `@command_handler` + `@service` stack means PyFly discovers and wires these at startup — you never call them directly, and you never register them by hand.
+
+**Run it — confirm the write side works end to end.** The Lumen sample already ships a test that exercises the full command path. From the `samples/lumen` directory, run just that test:
+
+::: listing terminal | Listing 7.4a — Exercise the command path
+uv run --extra dev pytest tests/test_cqrs_flow.py::test_full_wallet_lifecycle -q
+:::
+
+You should see a single passing test:
+
+```
+1 passed in 0.42s
+```
+
+That one test opens a wallet, deposits 1 500 minor units, withdraws 500, and asserts the balance lands at 1 000 — proving `OpenWalletHandler`, `DepositFundsHandler`, and `WithdrawFundsHandler` all commit through the bus. If you see `0 items collected`, you are not in the `samples/lumen` directory; `cd` there first. If you see `no handler found`, double-check that both decorators are present on each handler — that is the single most common cause.
+
### The entity↔aggregate mapper
Command handlers do not interact with the repository through the domain aggregate. They interact through a flat `WalletEntity` row — the persistence shape the framework `Repository[WalletEntity, str]` understands — and use `wallet_mapper` to translate between the two worlds:
@@ -339,7 +372,11 @@ A **query** is a frozen dataclass that inherits from `Query[R]`, where `R` is th
Queries return **read DTOs** rather than domain aggregates. The separation is deliberate. If `GetWalletHandler` returned a `Wallet` aggregate, the API layer would be coupled to every field on the aggregate — a change to the domain model could silently break the API contract. A dedicated `WalletDto` Pydantic model projects exactly the fields the HTTP response needs. Add a field to `Wallet`? The projection changes only if you explicitly include it in the DTO. Remove a field from `Wallet`? The projection compiles until you clean it up.
-::: listing lumen/core/services/wallets/get_wallet_query.py | Listing 7.7 — GetWallet: a frozen query returning WalletDto or None
+The read side mirrors the write side step for step — query message, then query handler — but with two simplifications: no `@transactional()` (nothing to commit) and no event publishing (nothing changed).
+
+**Step 5 — Write the single-lookup queries.** Create `get_wallet_query.py` and `get_balance_query.py`. Both carry only a `wallet_id`; what differs is what they promise to return.
+
+::: listing lumen/core/services/wallets/get_wallet_query.py | Listing 7.7 — GetWallet: a single-lookup query returning a full WalletDto
from __future__ import annotations
from dataclasses import dataclass
@@ -373,7 +410,7 @@ class GetBalance(Query[BalanceDto | None]):
Both queries carry only `wallet_id`. `GetWallet` returns a `WalletDto` — the full representation including `id`, `owner_id`, `currency`, `balance_minor`, `balance`, and `created_at`. `GetBalance` returns a `BalanceDto` — a lighter projection that omits `owner_id` and `created_at`. A balance poll does not need the owner; leaving those fields out saves bandwidth and avoids accidentally exposing account ownership in a response that callers may log. Keeping the two queries separate means you can tune each independently — caching, authorization, or a dedicated read store — without touching the other.
-The query handlers live under the same `wallets/` package as the commands. **The same `@query_handler` + `@service` stacking applies**: `@query_handler` registers the class with the handler registry; `@service` wires it into the DI container. Both decorators are required for the same reasons as on command handlers.
+**Step 6 — Write the single-lookup query handlers.** The query handlers live under the same `wallets/` package as the commands. **The same `@query_handler` + `@service` stacking applies**: `@query_handler` registers the class with the handler registry; `@service` wires it into the DI container. Both decorators are required for the same reasons as on command handlers. Notice how much smaller these are than the command handlers — no session factory, no event publisher, just the repository and a one-line projection.
::: listing lumen/core/services/wallets/get_wallet_handler.py | Listing 7.9 — GetWalletHandler: find_by_id → entity_to_dto → return
from __future__ import annotations
@@ -427,7 +464,10 @@ Both handlers delegate projection to `wallet_mapper` — the single module that
The read side does not stop at single-resource lookups. Production systems need lists with pagination metadata and the ability to filter by runtime predicates. The framework handles both through the `Repository` base class.
-`ListWallets` wraps a `Pageable` (page number, size, sort) and asks the repository for a counted, sorted, limited slice. `ListRichWallets` adds a `min_minor` threshold and runs it through a composable `Specification` — a predicate object that can be combined with `&`, `|`, and `~` before execution.
+!!! note "Pageable and Specification, in plain terms"
+ A **`Pageable`** bundles three things a list endpoint needs: which page you want, how big each page is, and how to sort. A **`Specification`** is a reusable, composable filter — think of it as a `WHERE` clause you can build as an object and combine with `&` (and), `|` (or), and `~` (not) before it ever touches SQL. Both come from the framework's data layer; you do not write the SQL yourself.
+
+**Step 7 — Write the list queries and handlers.** `ListWallets` wraps a `Pageable` (page number, size, sort) and asks the repository for a counted, sorted, limited slice. `ListRichWallets` adds a `min_minor` threshold and runs it through a composable `Specification`. Build the two query messages first, then their handlers.
::: listing lumen/core/services/wallets/list_wallets_query.py | Listing 7.11 — ListWallets: a Pageable-carrying query
from __future__ import annotations
@@ -530,6 +570,35 @@ The return value is whatever `do_handle` returned — a `BalanceDto` or `None`.
!!! note "Queries return None, not exceptions"
Query handlers return `None` when the resource is not found rather than raising `AggregateNotFound`. This is a deliberate convention: a query that finds nothing is not an error — it is an answer. The controller turns a `None` result into a 404 response, keeping the HTTP concern out of the handler.
+!!! note "What just happened"
+ Both sides of CQRS now exist. Three commands and three handlers change state; four queries and four handlers read it. None of them know about HTTP, and none of them are registered by hand — the decorators do that at startup. The only thing missing is the HTTP boundary that turns a web request into a message and a message result into a web response. That is the controller, which you build next.
+
+**Run it — confirm every handler is registered.** Before touching the controller, prove the bus discovered all your handlers. Start the app, then ask the CQRS health indicator how many handlers it found. From the `samples/lumen` directory:
+
+::: listing terminal | Listing 7.14a — Start Lumen
+uv run pyfly run --server uvicorn
+:::
+
+In a second terminal, query the actuator health endpoint. In v26.6.110 the actuator lives on its own management port, **9090** by default — not the app's 8080:
+
+::: listing terminal | Listing 7.14b — Count the registered handlers
+curl -s localhost:9090/actuator/health | python -m json.tool
+:::
+
+Look for the `cqrs_health_indicator` block. With every command and query handler from this chapter in place it reports three command handlers and four query handlers:
+
+```json
+"cqrs_health_indicator": {
+ "status": "UP",
+ "details": {"command_handlers": 3, "query_handlers": 4}
+}
+```
+
+If a count is lower than you expect, a handler is missing one of its two decorators and the registry never mapped it. Stop the server with `Ctrl-C` when you are done.
+
+!!! note "The actuator lives on its own port now"
+ In PyFly v26.6.110 the business API and the actuator run on **separate** ports — Spring-style. Your wallet endpoints listen on `pyfly.server.port` (default **8080**), while actuator endpoints and the admin dashboard listen on `pyfly.management.server.port` (default **9090**), which is open and unauthenticated by default. Lumen keeps the defaults, so health is at `localhost:9090/actuator/health` and the wallet API is at `localhost:8080/api/v1/wallets`. The default actuator HTTP exposure is `health,info`; expose more via `pyfly.management.endpoints.web.exposure.include`. Lock the management port down in production with `pyfly.management.security.enabled: true`, or disable it entirely with `pyfly.management.server.port: -1`.
+
---
## Wiring the bus into the controller
@@ -552,7 +621,7 @@ The framework registers a controller's routes in **alphabetical method-name orde
The collection handlers are named `list_wallets` and `list_rich_wallets`; the single-resource handlers are named `wallet_detail` and `wallet_balance`. Alphabetically, `l` sorts before `w`, so the collection routes (`GET /`, `GET /rich`) are always registered ahead of the parameterised routes (`GET /{wallet_id}`, `GET /{wallet_id}/balance`). If you rename `wallet_detail` to something that sorts before `list_*`, the `/rich` route will silently break.
-Here is the complete controller:
+**Step 8 — Wire the buses into the controller.** Replace the old `WalletApplicationService` dependency with the two buses, then turn each endpoint into a one-liner: build a command or query from the request, dispatch it, return the result. Here is the complete controller.
::: listing lumen/web/controllers/wallet_controller.py | Listing 7.15 — WalletController: DefaultCommandBus + DefaultQueryBus + paged list endpoints
from __future__ import annotations
@@ -692,12 +761,57 @@ The `wallet_detail` and `wallet_balance` methods show the only remaining HTTP co
!!! tip "Let the bus raise"
You do not need to catch `CommandProcessingException` or `QueryProcessingException` in the controller unless you want to customize the error shape. The global exception handler maps `AggregateNotFound` to 404 and `BusinessRuleViolation` to 422 — the same as before. The bus exceptions propagate those originals transparently.
+**Run it — drive the full HTTP path.** The vertical slice is complete: HTTP request → command/query → bus → handler → domain → repository → response. Prove it from the outside. Start the app (`uv run pyfly run --server uvicorn`), then in a second terminal open a wallet:
+
+::: listing terminal | Listing 7.15a — Open a wallet over HTTP
+curl -s -X POST localhost:8080/api/v1/wallets \
+ -H 'content-type: application/json' \
+ -d '{"owner_id":"u-1","currency":"EUR"}'
+:::
+
+The `open_wallet` endpoint dispatches `OpenWallet` and returns the generated id:
+
+```json
+{"wallet_id": "wlt-c5bbb2a7-dd49-4321-932e-e4c6bfa5cc2c"}
+```
+
+Copy that id, deposit into it, then read the balance back:
+
+::: listing terminal | Listing 7.15b — Deposit, then read the balance
+curl -s -X POST localhost:8080/api/v1/wallets/wlt-c5bbb2a7-dd49-4321-932e-e4c6bfa5cc2c/deposit \
+ -H 'content-type: application/json' -d '{"amount":1500}'
+
+curl -s localhost:8080/api/v1/wallets/wlt-c5bbb2a7-dd49-4321-932e-e4c6bfa5cc2c/balance
+:::
+
+The deposit echoes the new balance in minor units; the balance query returns the `BalanceDto`:
+
+```json
+{"wallet_id": "wlt-c5bbb2a7-dd49-4321-932e-e4c6bfa5cc2c", "balance_minor": 1500}
+{"wallet_id": "wlt-c5bbb2a7-dd49-4321-932e-e4c6bfa5cc2c", "balance_minor": 1500, "balance": 15.0}
+```
+
+Finally, confirm the route-ordering decision from earlier pays off — list the wallets and the "rich" subset:
+
+::: listing terminal | Listing 7.15c — Both list routes resolve correctly
+curl -s 'localhost:8080/api/v1/wallets?page=1&size=20'
+curl -s 'localhost:8080/api/v1/wallets/rich?min_minor=1000'
+:::
+
+Both return a `PageDto` envelope (`items`, `total`, `total_pages`, `has_next`, `has_previous`). The `/rich` call resolves to `list_rich_wallets`, *not* to `wallet_detail` looking for a wallet whose id is the literal string `"rich"` — exactly because `list_*` sorts before `wallet_*`. If `/rich` ever returns a 404, that ordering has been broken; revisit the method-name rule above.
+
+!!! warning "Use a real id"
+ The wallet id above is illustrative — yours will differ on every `open_wallet` call. Paste the id returned by your own `POST /api/v1/wallets` into the deposit and balance URLs, or you will get a 404.
+
---
## The handler pipeline
A single `send` or `query` call triggers more than just the handler. Understanding the pipeline tells you where to put each cross-cutting concern — and, just as importantly, where *not* to put it.
+!!! note "What is a 'pipeline'?"
+ A **pipeline** is just a fixed sequence of steps the bus runs around your handler — like an assembly line. Your message enters one end, passes through validation and authorization, gets handled, and (for commands) has its events published, before the result comes back out. You write only the one step in the middle (`do_handle`); the bus owns the rest, identically for every message.
+
The pipeline is defined once, in the bus, and applies uniformly to every handler. You never write pipeline logic inside a handler. The order is strict:
| Step | Where it is defined | Applies to | Failure result |
@@ -810,6 +924,20 @@ Each handler carries the `@command_handler` + `@service` (or `@query_handler` +
Adding a new command now means three things: define a frozen dataclass, implement one `do_handle` decorated with `@command_handler` + `@service` and annotated with `@transactional()`, and add one endpoint that calls `self._commands.send`. The pipeline applies automatically.
+**Run it — the whole chapter, in one command.** From the `samples/lumen` directory, run the CQRS flow tests one last time to confirm every piece you built this chapter still hangs together:
+
+::: listing terminal | Listing 7.17 — Verify the full CQRS slice
+uv run --extra dev pytest tests/test_cqrs_flow.py -q
+:::
+
+All five scenarios pass — the happy-path lifecycle, the not-found query, the rejected overdraw, the rejected non-positive deposit, and the rejected deposit to an unknown wallet:
+
+```
+5 passed in 0.61s
+```
+
+Those last four cases are worth pausing on: each one exercises the *pipeline*, not the handler. The overdraw is refused by the aggregate and surfaces as `CommandProcessingException`; the non-positive deposit never reaches a handler at all because `validate()` rejects it first. You wrote zero error-handling code to get any of that.
+
---
## Try it yourself {.exercises}
diff --git a/book/manuscript/08-eda.md b/book/manuscript/08-eda.md
index a93f508a..cc5077ed 100644
--- a/book/manuscript/08-eda.md
+++ b/book/manuscript/08-eda.md
@@ -12,6 +12,11 @@ The gap matters in practice. Lumen needs a balance read model that stays in sync
This chapter builds the reaction side of Lumen's architecture. You will wire `EventPublisher` into the command handlers, introduce the `publish_domain_events` bridge that drains the aggregate's buffer and forwards each event to the bus, and write a `WalletAuditListener` that subscribes using `@event_listener` and maintains two in-memory projections: an immutable audit trail and a running deposit total. By the end of the chapter the write path and the read infrastructure are fully decoupled — each side evolves without the other noticing.
+We will build this gradually, one small piece at a time. Each feature comes with a numbered walkthrough, the exact command to run, and the output you should expect to see. If you have followed along from Chapter 7 you already have the wallet command handlers and the `Wallet` aggregate in place; this chapter is verified against PyFly v26.6.110 and the Lumen sample under `samples/lumen`.
+
+!!! note "Jargon, in plain language"
+ A handful of terms recur in this chapter. A **domain event** is a small, frozen record of a business fact that already happened — for example "funds were deposited." A **publisher** is the thing that announces such facts; a **listener** (or *subscriber*) is code that reacts to them. A **bus** is the in-between switchboard that carries each announcement from the publisher to every interested listener. A **projection** is a read model that a listener builds up from events — here, an audit trail and a running total. A **port** is an interface (a Python `Protocol`) that your code depends on so the concrete implementation behind it can be swapped without changing callers. Keep these five in mind; the rest of the chapter is mostly about connecting them.
+
---
## Two kinds of events
@@ -65,6 +70,36 @@ pyfly:
Without this line the `EventPublisher` bean is not registered and any handler that declares `events: EventPublisher` in its constructor will fail to start.
+Let us turn that bus on before we use it.
+
+**Step 1 — Open Lumen's `pyfly.yaml`.** Find the top-level `pyfly:` block. You will already see keys such as `app`, `server`, and `data` from the previous chapters.
+
+**Step 2 — Add the `eda` block.** Insert the two lines shown in Listing 8.0 as a child of `pyfly:`, at the same indentation level as `server:` and `data:`. Indentation is significant in YAML, so line them up exactly.
+
+**Step 3 — Save the file.** That is all the configuration the in-memory bus needs — no broker, no connection string, no extra dependency.
+
+!!! note "Run it"
+ Start the application and confirm it boots cleanly with the bus registered:
+
+ ```bash
+ uv run pyfly run --server uvicorn
+ ```
+
+ In the startup log you should see the application come up on the default app port and the management endpoints on the separate management port:
+
+ ```text
+ INFO starting_application name=lumen version=1.0.0
+ INFO uvicorn running on http://127.0.0.1:8080
+ INFO management endpoints on http://127.0.0.1:9090
+ ```
+
+ If instead the process exits with an error mentioning that an `EventPublisher` dependency could not be resolved, the `eda` block is missing or mis-indented — return to Step 2.
+
+!!! note "Where the app and the dashboard live"
+ As of v26.6.110 the application listens on `pyfly.server.port` (default `8080`), while the actuator and admin dashboard run on a **separate** management port, `pyfly.management.server.port` (default `9090`). The management port is open and unauthenticated by default; set `pyfly.management.security.enabled: true` to lock it down, or `pyfly.management.server.port: -1` to disable management endpoints entirely. None of this affects the EDA bus — it is purely in-process — but it is worth knowing which port is which when you start poking at the running app later in the chapter.
+
+**What just happened.** You flipped a single configuration switch and PyFly registered an `EventPublisher` bean for you. From now on any `@service` that asks for `events: EventPublisher` in its constructor receives the in-memory bus automatically. Nothing publishes anything yet — that comes next — but the plumbing is in place.
+
### The EventEnvelope
Every domain event reaches its listeners wrapped in an **`EventEnvelope`**. Think of it as the metadata layer that transforms a bare Python dictionary into a traceable, auditable, first-class fact. It is a frozen dataclass — immutable once created — that pairs the payload with the context every listener needs.
@@ -82,6 +117,8 @@ Three fields deserve particular attention. `event_id` is a stable UUID generated
`event_type` holds the **class name** of the domain event — `"WalletOpened"`, `"FundsDeposited"`, or `"FundsWithdrawn"` — not a dot-separated path. Listeners subscribe by those same class names, so the subscription contract is defined by the domain model, not by string conventions invented outside it.
+**What just happened.** Do not be put off by the six-field table — in everyday code you touch only two of them. When you publish you supply `event_type`, `payload`, and `destination`; the bus fills in `event_id`, `timestamp`, and `headers` for you. When you react, you read `envelope.event_type` to know *what* happened and `envelope.payload` to know the details. The other three fields are there when you need them (idempotency, ordering, tracing) and quietly out of the way when you do not.
+
### The domain events in the Wallet aggregate
The `Wallet` aggregate raises typed, frozen-dataclass domain events. Each event's class name becomes its routing `event_type` on the bus:
@@ -189,7 +226,17 @@ In Chapter 7 the command handlers loaded aggregates, drove domain behaviour, and
The `@transactional()` decorator (from `pyfly.data.relational.sqlalchemy`) opens a dedicated `AsyncSession` from the injected `async_sessionmaker`, binds it to the repository for the call, commits on success, and rolls back on failure. That means the load → mutate → save sequence is one committed unit of work, and no event is published unless the row actually lands in the database.
-Here is the updated `DepositFundsHandler`:
+Here is the change, broken into the four edits you will make to `DepositFundsHandler`.
+
+**Step 1 — Add the publisher to the constructor.** Alongside the existing `repository` parameter, accept `events: EventPublisher` and store it as `self._events`. Type it as the *protocol* `EventPublisher`, never as `InMemoryEventBus` — that is what keeps the handler ignorant of which bus is running.
+
+**Step 2 — Accept the session factory.** Add `session_factory: async_sessionmaker[AsyncSession]` and store it as `self._session_factory`. The `@transactional()` decorator looks for exactly this attribute name to open its unit of work, so the name matters.
+
+**Step 3 — Decorate `do_handle` with `@transactional()`.** This wraps the whole load-mutate-save sequence in one committed transaction.
+
+**Step 4 — Drain and publish after the save.** As the last step inside `do_handle`, after `self._repository.upsert(...)`, call `await publish_domain_events(self._events, wallet.clear_events())`. `wallet.clear_events()` returns the buffered events *and* empties the buffer, so they are never published twice.
+
+Putting those four edits together gives the updated `DepositFundsHandler`:
::: listing lumen/core/services/wallets/deposit_funds_handler.py | Listing 8.3 — DepositFundsHandler: @transactional unit-of-work, then publish
from __future__ import annotations
@@ -240,6 +287,27 @@ class DepositFundsHandler(CommandHandler[DepositFunds, int]):
Three design decisions are worth noting. First, `events: EventPublisher` is typed as the protocol, not as `InMemoryEventBus` — the DI container injects whichever implementation is registered, so the handler never knows or cares which bus is active. Second, the publish call sits *after* `self._repository.upsert(...)` inside the `@transactional()` unit of work: if the save fails the decorator rolls back before `publish_domain_events` is reached, so listeners never see a fact that never persisted. Third, the handler works with the ORM entity directly via `to_aggregate` / `to_entity` mappers — the aggregate is rehydrated from the row, mutated, and mapped back to a row before the upsert. If the publish fails after a successful save you have an at-least-once delivery challenge — Chapter 10 addresses that with transactional outbox patterns. For now, the in-memory bus never fails.
+!!! note "Run it"
+ With the application running (`uv run pyfly run --server uvicorn`), open a wallet and deposit into it from a second terminal:
+
+ ```bash
+ # Open a wallet — returns its id
+ curl -s -X POST http://localhost:8080/api/v1/wallets \
+ -H 'content-type: application/json' \
+ -d '{"owner_id": "u-1", "currency": "EUR"}'
+ # {"wallet_id": "wlt-…"}
+
+ # Deposit 1500 minor units (15.00 EUR) into that wallet
+ curl -s -X POST http://localhost:8080/api/v1/wallets/wlt-…/deposit \
+ -H 'content-type: application/json' \
+ -d '{"amount": 1500}'
+ # {"wallet_id": "wlt-…", "balance": 1500}
+ ```
+
+ The HTTP response confirms the balance, but the more interesting evidence is in the application log: because the deposit published a `FundsDeposited` event and the audit listener (which you will build in the next section) reacts to it, you will see a `wallet_audit_observed` log line for `event_type=FundsDeposited`. No listener yet? Then the publish happens silently — which is exactly the point: the handler does not know whether anyone is listening.
+
+**What just happened.** The command handler now does one extra thing after saving: it drains the events the aggregate buffered and hands them to the bus. The crucial ordering is *save first, publish second*, all inside one transaction. If the database write rolls back, the events are never published, so a listener can never observe a fact that did not actually persist. The handler gained four lines and zero new knowledge — it still has no idea what, if anything, will react.
+
The `OpenWalletHandler` follows the same pattern:
::: listing lumen/core/services/wallets/open_wallet_handler.py | Listing 8.4 — OpenWalletHandler: @transactional, upsert, then publish WalletOpened
@@ -343,6 +411,16 @@ async def on_funds_deposited(envelope: EventEnvelope) -> None:
Lumen's production listener is `WalletAuditListener`. It subscribes to all three wallet domain events and maintains two in-memory projections: an ordered **audit trail** and a **running net-deposit total** per wallet.
+We will assemble it in small pieces. Read the four steps first, then study the full listing below — it is the same code, shown whole.
+
+**Step 1 — Declare a plain `@service` class.** A listener is just a service bean with some state. Give it an `__init__` that initialises the two projections: `self._entries: list[AuditEntry] = []` for the audit trail and `self._running_totals: dict[str, int] = {}` for the per-wallet totals.
+
+**Step 2 — Write the reaction method.** Add an `async def on_wallet_event(self, envelope: EventEnvelope) -> None`. It receives one `EventEnvelope` and nothing else.
+
+**Step 3 — Stamp it with `@event_listener`.** Decorate the method with `@event_listener(event_types=["WalletOpened", "FundsDeposited", "FundsWithdrawn"])`. One method can subscribe to all three class names in a single declaration. This decorator does not subscribe immediately — it *stamps* the method with metadata that `ApplicationContext` finds at startup and uses to auto-subscribe it to the `EventPublisher` bean.
+
+**Step 4 — Project the event.** Inside the method, append an `AuditEntry` for every event, then branch on `envelope.event_type` to adjust the running total: set it to zero on `WalletOpened`, add on `FundsDeposited`, subtract on `FundsWithdrawn`. Expose read accessors (`entries`, `entries_for`, `running_total`) so other code can query the projections.
+
::: listing lumen/core/services/listeners/wallet_audit_listener.py | Listing 8.6 — WalletAuditListener: audit trail + running-total projection
from __future__ import annotations
@@ -435,6 +513,8 @@ Here is what the listener does, step by step.
The method appends an `AuditEntry` for every event, then branches on `event_type` to update the running total. Notice what is absent: no import of the `Wallet` aggregate, no repository call, no knowledge of how the deposit was processed. The projection reacts purely to the published fact.
+**What just happened.** You wrote a self-contained reaction. The `@event_listener` decorator is the entire wiring story — there is no `bus.subscribe(...)` call anywhere in this file. At startup, `ApplicationContext` scans your `@service` beans, finds the stamped `on_wallet_event` method, and subscribes it to the bus for each of the three class names. The listener and the command handlers never reference each other; they are connected only through the events they agree to name.
+
!!! tip "Envelope metadata in projections"
`envelope.timestamp` gives you the authoritative event time — when the fact was recorded, not when the listener ran. Store it in your read model and you get a cheap `occurred_at` column for free, with no clock skew between writer and reader.
@@ -503,6 +583,22 @@ async def test_listener_observes_wallet_events(
The test proves the full chain: `OpenWalletHandler` → `publish_domain_events` → `InMemoryEventBus` → `WalletAuditListener.on_wallet_event` → `audit_listener.entries_for(...)`. No mocks, no fakes — the production code path runs as written.
+!!! note "Run it"
+ Run the event-listener test from the Lumen project root:
+
+ ```bash
+ uv run --extra dev pytest tests/test_event_listener.py -q
+ ```
+
+ You should see the suite pass:
+
+ ```text
+ ... [100%]
+ 3 passed in 0.XXs
+ ```
+
+ The three tests cover the happy path (open, deposit, withdraw, then assert the audit trail and running total), the empty-projection case before any command runs, and the negative case where an overdrawing withdrawal raises and therefore publishes *no* event — so it must not appear in the audit log. If a test fails with a missing-attribute error on `__pyfly_event_patterns__`, the `@event_listener` decorator is not applied to `on_wallet_event`; revisit Step 3 of the previous section.
+
What makes this design compelling is that adding the listener required zero changes to the command handlers, the `Wallet` aggregate, or any repository. `DepositFundsHandler` has no idea a projection exists. Both sides are entirely independent — each is a consequence of the same published fact, connected only by the bus.
---
diff --git a/book/manuscript/09-event-sourcing.md b/book/manuscript/09-event-sourcing.md
index 0dcdf6d8..b07586da 100644
--- a/book/manuscript/09-event-sourcing.md
+++ b/book/manuscript/09-event-sourcing.md
@@ -76,8 +76,13 @@ In Chapter 6, `Wallet` held `_balance: Money` as direct Python state — `deposi
This two-step indirection — apply, then handle — is the core mechanic of event sourcing. It enforces a strict discipline: every state transition is recorded exactly once as an event, and the aggregate's current state is always provable from its history.
+!!! note "Jargon: aggregate, handler, fold"
+ An **aggregate** is a single consistency boundary — one object that owns a set of related state and the rules that keep it valid. `LedgerAccount` is an aggregate: its balance and its overdraft rule live together. A **handler** (sometimes called an *apply-handler*) is the small function that takes one event and updates the aggregate's fields. A **fold** is the functional-programming term for walking a list and accumulating a result one element at a time — replaying a stream of events into a balance is exactly a fold over the event list. You will see "fold" used as a synonym for "the handler runs over each event."
+
**Zero-arg constructor.** `LedgerAccount.__init__` takes no arguments. This is required because `EventSourcedRepository` calls the factory as `LedgerAccount()` and then assigns `.id` before replaying the stream. Never construct a new ledger by passing arguments to `__init__` — call the `open` classmethod instead.
+We will build the aggregate in four moves, then run the unit tests to prove each invariant holds. Read the full listing first, then walk the steps below it.
+
Here are the domain events and the aggregate:
::: listing lumen/models/entities/v1/ledger_account.py | Listing 9.1 — LedgerAccount: an event-sourced aggregate that derives its balance from replay
@@ -240,6 +245,19 @@ The factory method `open` calls `apply(LedgerOpened(...))` rather than setting f
The `version` counter starts at zero and increments after each dispatched event. After `open`, `account.version == 1`; after one credit, `account.version == 2`. You will see this number again when the `EventStore` enforces optimistic concurrency.
+**Building it step by step.** The listing is dense the first time through. Here is the same code as four deliberate moves — the order in which you would actually write it.
+
+**Step 1 — Define the durable facts.** Write the three event dataclasses (`LedgerOpened`, `Credited`, `Debited`) extending `pyfly.eventsourcing.DomainEvent`. Give every field a default value (`account_id: str = ""`, `amount: int = 0`). The defaults are not cosmetic: the repository rebuilds these dataclasses from a stored payload, and a dataclass with required fields could not be reconstructed when an old event predates a newer field.
+
+**Step 2 — Set up the empty aggregate.** Write `__init__` with no parameters. Initialise the fields to neutral defaults (`owner_id = ""`, `balance = Money.zero(Currency.EUR)`) and register one `when()` handler per event class, each as a two-arg lambda delegating to a private method. At this point the aggregate is a blank slate that knows how to react to events but has not seen any.
+
+**Step 3 — Add the factory and the commands.** Write the `open` classmethod and the `credit` / `debit` methods. Each one validates its invariants first (currency match, positive amount, no overdraft), computes the resulting balance, and only then calls `self.apply(SomeEvent(...))`. Validation lives in the command; the handler never validates.
+
+**Step 4 — Write the pure folds.** Write `_on_opened`, `_on_credited`, `_on_debited`. Each reads fields off the event and assigns them to the aggregate — no arithmetic, no validation, no exceptions. Because these same three methods run on both the write path and the replay path, keeping them dumb is what guarantees that a reloaded ledger equals the live one.
+
+!!! tip "Why validation belongs in the command, not the handler"
+ The handler runs again every time the aggregate is loaded from history. If validation lived in the handler, you would be re-checking the overdraft rule against data that already passed it years ago — and worse, a rule that has since *changed* could reject a historical event that was perfectly valid when it happened. Validate once, on the write that produces the event; trust the event forever after.
+
`pending_events()` returns the events queued since the last save. The unit tests drive the aggregate in isolation — no repository needed — which makes invariant verification straightforward:
::: listing tests/test_ledger_event_sourcing.py | Listing 9.2 — Unit tests: aggregate in isolation, commands and invariants
@@ -283,8 +301,25 @@ def test_debit_cannot_overdraw() -> None:
]
:::
+**Run it.** These three tests need no database and no event store — the aggregate stands entirely on its own. Run just this file's unit tests from the Lumen project root:
+
+```bash
+uv run --extra dev pytest tests/test_ledger_event_sourcing.py -q -k "open or credit or debit or currency"
+```
+
+You should see the in-isolation tests pass:
+
+```
+.... [100%]
+4 passed, 7 deselected in 0.05s
+```
+
+The four dots are the four aggregate-only tests (the three shown above plus a currency-mismatch check); the seven deselected tests are the store-backed ones, which we run later. If you see a `TypeError` about the number of arguments, you have almost certainly hit the bound-method trap from the warning above — passing `self._on_opened` directly to `when()` instead of wrapping it in a two-arg lambda.
+
+**What just happened.** You built a domain object that records *what changed* instead of *what is*. `open` emitted a `LedgerOpened` fact and bumped the version to 1. `credit` and `debit` each validated their rule, computed the new balance, and emitted a fact — so a credit followed by a debit left three facts queued and the version at 3. When a rule failed (the overdraft test), the command raised before calling `apply`, so no faulty event ever entered the buffer. The aggregate's in-memory balance and its list of pending events stayed perfectly in step, and nothing touched a database yet.
+
!!! tip "on_{event_type} as an alternative"
- Instead of `when()` lambdas, you can define a method on the aggregate named after the event in snake_case — `on_ledgeropened(self, evt)` is discovered automatically. Use `when()` for concise one-liners and named methods for handlers that need multiple statements or local variables. The dispatch order is: `when()` handler first; then `on_{event_type}` method; then `EventHandlerException` if neither exists.
+ Instead of `when()` lambdas, you can define a method on the aggregate named after the event's `event_type` — which is the event **class name**, so `on_LedgerOpened(self, evt)` (matching the `LedgerOpened` dataclass) is discovered automatically. Use `when()` for concise one-liners and named methods for handlers that need multiple statements or local variables. The dispatch order is: `when()` handler first; then the `on_{event_type}` method; then `EventHandlerException` if neither exists.
!!! spring "Spring parity"
`AggregateRoot` + `apply()` + `when()` is PyFly's equivalent of Axon Framework's `@Aggregate` + `AggregateLifecycle.apply(event)` + `@EventSourcingHandler`. Axon uses annotation-driven handler discovery (`@EventSourcingHandler`); PyFly uses `when()` registration or `on_*` method convention. The replaying mechanic — load events from the store, call the same handlers, rebuild state — is identical in both frameworks.
@@ -327,6 +362,17 @@ from pyfly.eventsourcing.repository import EventSourcedRepository
You subclass `EventSourcedRepository` for two reasons: to pass the concrete factory and snapshot store through a single well-named constructor, and — optionally — to override `_envelope_to_event` so that replayed events are real typed dataclasses rather than the generic attribute-bag the base class produces.
+!!! note "Jargon: envelope and attribute-bag"
+ A `StoredEventEnvelope` is the *wire shape* the store persists: it wraps the event's `payload` (a plain dict) together with bookkeeping fields the store needs — `aggregate_id`, `aggregate_type`, `sequence`, `event_type`, `event_id`, and `occurred_at`. Think of it as the addressed envelope around the letter. An **attribute-bag** is the generic stand-in object the base repository creates on load if you do not override anything: a nameless object with the payload's keys set as attributes. It works — the handlers only read attributes — but it is not your real `Credited` dataclass, so it cannot be type-checked or `isinstance`-tested. The override below trades that anonymity for the real thing.
+
+Build the repository in three small steps.
+
+**Step 1 — Map class names back to dataclasses.** The store records each event's `event_type` as the class name string (`"Credited"`). To rebuild the real dataclass on load, you need a lookup from that string to the class. That is `_EVENT_TYPES` — one entry per event type.
+
+**Step 2 — Subclass and forward the constructor.** `LedgerAccountRepository.__init__` takes the `store` (and an optional `snapshots` store) and forwards everything to `super().__init__`, supplying `factory=LedgerAccount` so the base class knows how to make a blank aggregate.
+
+**Step 3 — Override `_envelope_to_event` for typed replay.** Look the `event_type` up in `_EVENT_TYPES`, filter the stored payload down to fields the dataclass actually declares (using `__dataclass_fields__`), and construct the real event. Fall back to the base class's generic hydration for any event type you do not recognise.
+
::: listing lumen/models/repositories/ledger_repository.py | Listing 9.3 — LedgerAccountRepository: typed replay via _envelope_to_event
from __future__ import annotations
@@ -397,10 +443,32 @@ class LedgerAccountRepository(EventSourcedRepository[LedgerAccount]):
The `_envelope_to_event` override looks up the stored `event_type` string in `_EVENT_TYPES`, uses `__dataclass_fields__` to filter the payload to known fields, and reconstructs the real dataclass. Unknown fields are silently dropped — forward-compatibility in practice: if a future event version adds a field the old handler does not recognise, the ledger keeps replaying instead of crashing. The base-class fallback at the bottom handles any event type the repository does not know about.
+!!! note "Jargon: forward-compatibility"
+ A reader is **forward-compatible** when it can ingest data written by a *newer* version of itself without breaking — it simply ignores parts it does not understand. Dropping unknown payload fields is exactly that: a v2 writer can add a `reference_code` to `Credited`, and a still-running v1 reader keeps folding the event correctly instead of crashing on the surprise field.
+
+**Run it.** A focused test exercises this override directly — it hands the repository a hand-built envelope and asserts it gets back a real `Credited` dataclass:
+
+```bash
+uv run --extra dev pytest tests/test_ledger_event_sourcing.py -q -k typed_replay
+```
+
+```
+. [100%]
+1 passed, 10 deselected in 0.05s
+```
+
+**What just happened.** You wired the persistence boundary without writing a single line of SQL or storage code. The base `EventSourcedRepository` already knows how to drain pending events on `save` and replay them on `load`; your subclass added only two things — a zero-arg factory so it can build a blank ledger, and a typed `_envelope_to_event` so the events it replays are the very same dataclasses the aggregate emitted on the write side. That symmetry is the whole point: write and replay run identical code.
+
---
## Save, load, and the replay proof
+This is the moment the whole chapter has been building toward: proving that a ledger reloaded from nothing but its stored events equals the live ledger that produced them. The test below does it in two halves.
+
+**Step 1 — Write a ledger and persist it.** Open a ledger, credit it, debit it, then call `repo.save(account)`. The repository drains the three pending events into the store and clears the aggregate's buffer.
+
+**Step 2 — Reload from a clean slate and compare.** Make a *brand-new* repository and call `load("acct-1")`. Nothing in this second half shares memory with the first object. The recovered ledger's balance can only be correct if it was recomputed by replaying the stored stream — which is exactly the proof we want.
+
The following test demonstrates the complete save-and-load cycle:
::: listing tests/test_ledger_event_sourcing.py | Listing 9.4 — Headline test: balance survives a reload by replay
@@ -445,6 +513,19 @@ async def test_balance_survives_reload_by_replay(
The test uses *two independent repository instances* sharing the same in-memory store — `repo` for the write, `fresh_repo` for the read. This proves that replay, not in-process object identity, is the source of truth.
+**Run it.** Run the headline test plus the raw-stream inspection test that follows it:
+
+```bash
+uv run --extra dev pytest tests/test_ledger_event_sourcing.py -q -k "reload_by_replay or immutable_event_stream"
+```
+
+```
+.. [100%]
+2 passed, 9 deselected in 0.05s
+```
+
+**What just happened.** You proved event sourcing actually works end to end. The first ledger lived only in memory; after `save`, its facts lived only in the store. A second, unrelated ledger object then rebuilt the exact same 15.00 EUR balance by folding those facts back through the same handlers — no stored balance column anywhere in sight. The version landed on 3 (one event per `LedgerOpened` / `Credited` / `Debited`), and the reconstructed ledger had nothing pending because loading is not the same as changing.
+
The event store also exposes raw envelopes for inspection — useful for audits and tests:
::: listing tests/test_ledger_event_sourcing.py | Listing 9.5 — The store holds the immutable event stream
@@ -481,6 +562,9 @@ Two concurrent requests — a credit from the mobile app and an automated fee de
**Optimistic concurrency** prevents this. Before appending new events, the `EventStore` compares the stream's *current* version against the *expected* version the repository recorded at load time. If they match, the append proceeds and the version advances. If they do not match — because another writer already appended — `ConcurrencyError` is raised and the losing request must retry from a fresh load.
+!!! note "Jargon: optimistic vs pessimistic locking"
+ *Pessimistic* locking assumes conflict is likely, so it grabs a lock up front — no other writer can touch the row until you release it. *Optimistic* concurrency assumes conflict is rare, so it takes no lock at all: it lets both writers proceed and only checks, at save time, whether anyone else changed the stream first. The loser retries. For most ledgers, two simultaneous writers to the *same* account are uncommon, so the optimistic strategy avoids the cost of locking on the overwhelmingly common no-conflict path.
+
The `expected_version` is passed implicitly by the repository: it records the version at which it loaded the aggregate and supplies it to the store on save. You never manage version numbers in application code.
The version progression is deterministic: after a save-and-reload, further writes advance the version without conflict:
@@ -513,6 +597,19 @@ async def test_continues_appending_after_a_reload(
**How it works.** After the first save the stream is at version 2. When loaded, `reloaded.version == 2`. `repo.save(reloaded)` appends with `expected_version=2`; the store advances to 3 and succeeds. The `final` load replays all three events and confirms the correct balance.
+**Run it.**
+
+```bash
+uv run --extra dev pytest tests/test_ledger_event_sourcing.py -q -k continues_appending
+```
+
+```
+. [100%]
+1 passed, 10 deselected in 0.05s
+```
+
+**What just happened.** A reloaded ledger remembered its version, so the next save lined up cleanly behind the events already in the stream — no conflict, sequence numbers in order, balance correct. This is the *happy path* of optimistic concurrency: one writer at a time. The moment two writers race, the second one's `expected_version` would no longer match and the store would raise `ConcurrencyError` instead — which is the case the warning below tells you how to handle.
+
!!! warning "Always handle ConcurrencyError"
When two writers race, the losing save raises `ConcurrencyError`. Your application service must catch it and decide what to do: retry the full load-mutate-save cycle (appropriate for low-contention writes), or surface a 409 Conflict to the caller (appropriate when the caller should re-submit with fresh data). Never silently swallow the error — a swallowed concurrency error leaves the stream in an inconsistent state.
@@ -573,6 +670,19 @@ async def test_snapshot_store_round_trips_the_ledger() -> None:
**How it works.** After the save, the repository checks: does `version 2 // 100 > 0 // 100`? No — the snapshot threshold has not been crossed, so no snapshot is taken. The next `load` performs a full replay of the two events and returns the correct balance. Once a ledger does cross a 100-event boundary, the repository serialises the aggregate's state into a snapshot envelope. The next load finds the snapshot, deserialises directly to that version, and then asks the event store for events with a sequence number greater than the snapshot version — reducing replay cost to the delta only.
+**Run it.**
+
+```bash
+uv run --extra dev pytest tests/test_ledger_event_sourcing.py -q -k snapshot_store_round_trips
+```
+
+```
+. [100%]
+1 passed, 10 deselected in 0.05s
+```
+
+**What just happened.** You wired a snapshot store into the repository and the ledger still reloaded correctly — which is exactly what should happen for a short stream. Because the two events never crossed the 100-event interval, no snapshot was written and the load fell back to a plain full replay. Snapshots are pure optimization: wiring one in costs nothing for short streams and quietly pays off once an account becomes high-frequency. You can prove the correctness of your ledger with the snapshot store both present and absent — the answer is identical.
+
!!! tip "Snapshot interval in production"
A `snapshot_interval` of 100 is the default and a sensible starting point. For high-frequency ledgers you might lower it; for accounts that only change a few times a day, a higher interval reduces snapshot-storage cost. Snapshots are an optimization, not a correctness requirement — removing them leaves the system correct but slower.
@@ -582,22 +692,40 @@ async def test_snapshot_store_round_trips_the_ledger() -> None:
The `pyfly.eventsourcing` module ships in the **base** `pyfly` package — no extra dependency. Enabling it takes two steps: set `pyfly.eventsourcing.enabled: true` in `pyfly.yaml` and annotate the application with `@enable_domain_stack`. PyFly's auto-configuration then registers `event_store` and `snapshot_store` beans automatically.
+!!! note "Jargon: bean and auto-configuration"
+ A **bean** is just an object the framework creates once and hands to anything that asks for it — the same dependency-injection idea you met in Chapter 2. **Auto-configuration** is a class of bean-producing factory methods that PyFly activates *only when a condition is met* — here, the `@conditional_on_property("pyfly.eventsourcing.enabled", having_value="true")` guard. Flip that one config flag on, and the `event_store` and `snapshot_store` beans appear in the container; leave it off, and the event-sourcing machinery stays dormant. You never call the factory yourself.
+
The test suite confirms this directly:
::: listing tests/test_ledger_event_sourcing.py | Listing 9.8 — Auto-configuration registers the event store beans
def test_auto_configuration_registers_event_store_beans() -> None:
"""enable_domain_stack activates this auto-config when
- pyfly.eventsourcing.enabled=true, registering the in-memory
- event/snapshot stores the ledger repository depends on."""
+ pyfly.eventsourcing.enabled=true (set in pyfly.yaml), registering
+ the in-memory event/snapshot stores the ledger repository depends on."""
+ from pyfly.core.config import Config
from pyfly.eventsourcing.auto_configuration import (
EventSourcingAutoConfiguration,
)
- config = EventSourcingAutoConfiguration()
- assert isinstance(config.event_store(), InMemoryEventStore)
- assert isinstance(config.snapshot_store(), InMemorySnapshotStore)
+ auto = EventSourcingAutoConfiguration()
+ cfg = Config() # empty config -> providers default to "memory"
+ assert isinstance(auto.event_store(cfg), InMemoryEventStore)
+ assert isinstance(auto.snapshot_store(cfg), InMemorySnapshotStore)
:::
+**Run it.**
+
+```bash
+uv run --extra dev pytest tests/test_ledger_event_sourcing.py -q -k auto_configuration
+```
+
+```
+. [100%]
+1 passed, 10 deselected in 0.05s
+```
+
+**What just happened.** With the `enabled` flag on, the auto-config produced the two in-memory stores the ledger repository depends on — without you instantiating either. Note that the factory methods take a `Config` argument: that is how they read `pyfly.eventsourcing.store.provider` to decide between the `memory` default and a SQL-backed adapter. Passing an empty `Config()` leaves them on `memory`, which is what the test asserts.
+
In application code, the repository is wired through dependency injection:
```python
@@ -629,14 +757,21 @@ The event store is the system of record, but most application queries — "what
That background process is a **projection**. A projection subscribes to the event stream and updates a read model each time a relevant event arrives. PyFly provides `FunctionProjection` and `ProjectionRunner` in `pyfly.eventsourcing.projection`:
+!!! note "Jargon: read model, projection, write model"
+ The **write model** is the side you have built so far — the aggregate and its event stream, optimised for *recording changes correctly*. A **read model** is a separate, query-shaped copy of the data, optimised for *answering questions fast* (one row per ledger with its current balance, say). A **projection** is the process that keeps a read model in sync by replaying the event stream into it. This separation — one model for writes, another for reads — is the **CQRS** pattern you met in Chapter 7, now backed by an event stream instead of a relational table.
+
- **`FunctionProjection(name, handler_fn)`** — wraps an async function that receives one `StoredEventEnvelope` and updates the read model.
- **`ProjectionRunner(projection, store)`** — drives the projection by iterating the `EventStore` in sequence-number order and calling the handler for each envelope.
+A projection comes together in three pieces. **Step 1** — write the handler: an `async` function that takes one envelope and updates the read model (here a plain `dict`; in production a database table). **Step 2** — wrap it: `FunctionProjection("balance_ledger", handler)` turns the bare function into a named projection. **Step 3** — drive it: `ProjectionRunner(projection, store)` connects the projection to the event store and, when started, feeds it every stored envelope in sequence order.
+
Here is a `BalanceLedgerProjection` that builds a balance read model from the event stream:
::: listing lumen/eventsourcing/balance_projection.py | Listing 9.9 — BalanceLedgerProjection: a read model built from the event stream
from __future__ import annotations
+import asyncio
+
from pyfly.eventsourcing import InMemoryEventStore
from pyfly.eventsourcing.projection import FunctionProjection, ProjectionRunner
@@ -672,13 +807,23 @@ def build_projection(store: InMemoryEventStore) -> ProjectionRunner:
async def demo_projection(store: InMemoryEventStore) -> None:
runner = build_projection(store)
+ # start() launches a background polling task and returns immediately;
+ # the read model is populated asynchronously as the loop drains the
+ # store. Poll until the projection has caught up, then stop the runner.
await runner.start()
+ try:
+ for _ in range(50):
+ if "led-001" in _balance_store:
+ break
+ await asyncio.sleep(0.05)
+ finally:
+ await runner.stop()
balance = _balance_store.get("led-001", {})
print(f"Balance read model: {balance}")
:::
-**How it works.** `FunctionProjection("balance_ledger", _handle_envelope)` wraps the async handler. `ProjectionRunner(projection, store)` links it to the `InMemoryEventStore`. `await runner.start()` iterates every envelope in the store in sequence-number order and calls `_handle_envelope` for each one. After `start()` returns, `_balance_store` reflects the current state of every ledger in the store.
+**How it works.** `FunctionProjection("balance_ledger", _handle_envelope)` wraps the async handler. `ProjectionRunner(projection, store)` links it to the `InMemoryEventStore`. `await runner.start()` launches a background polling task and returns *immediately* — it does not block until the store is drained. The task loops on `store.stream_all(...)`, calling `_handle_envelope` for each new envelope in order and advancing a cursor (`_last_event_id`) so it never re-processes an event. Because population happens asynchronously, the demo polls `_balance_store` until the projection has caught up, then calls `await runner.stop()` to halt the loop before reading the result. Only after the projection has processed the envelopes does `_balance_store` reflect the current state of every ledger in the store.
The projection is intentionally stateless — it reads only `envelope.event_type` and `envelope.payload`. No aggregate is loaded; no repository is called. The read model is cheap to rebuild: stop the runner, clear `_balance_store`, call `start()` again. This rebuild-from-history property is unique to event sourcing — state-storage models have already discarded the history.
@@ -776,16 +921,34 @@ The upcaster runs when the `EventStore` loads an event whose schema version is l
### Multi-tenancy
-When multiple tenants share the same event store, stream IDs must be scoped by tenant. The canonical approach is to prefix every `aggregate_id` with the tenant identifier — `"tenant-A::led-001"` rather than `"led-001"`. `EventSourcedRepository` accepts a `tenant_id` parameter on construction and prepends the prefix to every stream operation transparently:
+When multiple tenants share the same event store, events must be scoped by tenant so one tenant can never read or replay another's stream. PyFly gives you two seams for this; neither lives on `EventSourcedRepository` (its constructor takes only `store`, `factory`, `snapshots`, and `snapshot_interval` — there is no `tenant_id` parameter).
+
+The first seam is on the **envelope itself**. `StoredEventEnvelope` carries a dedicated `tenant_id` field, and `StoredEventEnvelope.of(...)` accepts it as a keyword argument:
```python
-repo_tenant_a = EventSourcedRepository(
- store,
- factory=LedgerAccount,
+envelope = StoredEventEnvelope.of(
+ aggregate_id="led-001",
+ aggregate_type="LedgerAccount",
+ sequence=0,
+ event=Credited(...),
tenant_id="tenant-A",
)
```
+The SQL adapter persists this as a `tenant_id` column on `pyfly_event_store`, so a tenant-aware store can filter every query by it. This keeps the `aggregate_id` clean while still partitioning the log per tenant.
+
+The second seam is a **pattern you implement yourself**: prefix every `aggregate_id` with the tenant identifier — `"tenant-A::led-001"` rather than `"led-001"` — when you call `repo.save` and `repo.load`. A thin tenant-aware wrapper around the repository can apply and strip the prefix so application code never sees it:
+
+```python
+class TenantLedgerRepository:
+ def __init__(self, repo: LedgerAccountRepository, tenant_id: str) -> None:
+ self._repo = repo
+ self._prefix = f"{tenant_id}::"
+
+ async def load(self, account_id: str) -> LedgerAccount | None:
+ return await self._repo.load(self._prefix + account_id)
+```
+
Projections must scope their read models similarly — typically by including `tenant_id` as a column in the read-model table and filtering on it at query time.
!!! note "Choosing event sourcing"
@@ -793,6 +956,23 @@ Projections must scope their read models similarly — typically by including `t
---
+## Run the whole chapter
+
+You ran each piece in isolation as you built it. Now run the complete ledger suite to confirm everything still passes together:
+
+```bash
+uv run --extra dev pytest tests/test_ledger_event_sourcing.py -q
+```
+
+```
+........... [100%]
+11 passed in 0.06s
+```
+
+Eleven dots: the four aggregate-isolation tests, the headline reload-by-replay proof, the raw-stream inspection, the typed-replay override, the post-reload concurrency check, the snapshot round-trip, the unknown-ledger lookup, and the auto-configuration wiring check. With those green, the `LedgerAccount` aggregate and its repository are complete and correct.
+
+---
+
## What you built {.recap}
Lumen's `LedgerAccount` is now a fully event-sourced ledger that coexists with the Chapter 6 state-stored `Wallet`.
diff --git a/book/manuscript/10-messaging.md b/book/manuscript/10-messaging.md
index 0975e0d5..1f70eab2 100644
--- a/book/manuscript/10-messaging.md
+++ b/book/manuscript/10-messaging.md
@@ -12,6 +12,11 @@ This chapter takes Lumen's event-driven foundation across that boundary. You wil
By the end of the chapter Lumen's integration events flow across process boundaries, ready for the Part IV services that will consume them.
+We will build this gradually, one piece at a time. Each feature comes with a numbered walkthrough, the exact command to run, and the output you should expect to see. If you have followed along from Chapter 8 you already have `EventPublisher` wired into the wallet command handlers and the `WalletAuditListener` reacting in-process; this chapter is verified against PyFly v26.6.110 and the Lumen sample under `samples/lumen`. Nothing here requires a running Kafka or RabbitMQ cluster to follow along: PyFly ships an in-memory broker that satisfies the same contract, so you can read, run, and test every listing before you ever touch Docker.
+
+!!! note "Jargon, in plain language"
+ A handful of terms recur in this chapter. A **message broker** is a separate server (Kafka or RabbitMQ) that stores messages and hands them to other processes. A **topic** is a named channel on the broker; publishers write to it and subscribers read from it. A **producer** (or *publisher*) puts messages onto a topic; a **consumer** (or *listener*) pulls them off and reacts. A **consumer group** is a label that lets several copies of the same service share the work, so each message is handled once. A **serialiser** turns a Python object into the raw `bytes` the broker stores; a **deserialiser** turns those bytes back into an object on the other side. A **dead-letter queue** (DLQ) is a holding area for messages that could not be processed. An **adapter** is the concrete broker driver hiding behind the `MessageBrokerPort` interface. Keep these eight in mind; the rest of the chapter is mostly about connecting them.
+
---
## One abstraction, many brokers
@@ -119,9 +124,65 @@ For Lumen, Kafka is the natural fit: wallet events form an ordered stream per wa
## Configuring the adapters
+Wiring a broker into Lumen is a configuration task, not a coding one. You add one extra to the project, add a `pyfly.messaging` block to `pyfly.yaml`, and PyFly does the rest: it constructs the right adapter and registers it under the `MessageBrokerPort` bean so anything that asks for that port gets the running broker injected. We will start with the broker that needs no infrastructure at all, then graduate to Kafka and RabbitMQ.
+
+!!! note "Turn messaging on with one key"
+ In v26.6.110 the messaging subsystem only wires itself up when the
+ `pyfly.messaging.provider` key is **present** in your configuration. No
+ key means no `MessageBrokerPort` bean — a deliberate "off by default"
+ so that an app with no messaging needs pull no broker libraries.
+ Once the key is set, its value (`"memory"`, `"kafka"`, `"rabbitmq"`,
+ or `"auto"`) selects the adapter. The companion keys live under the
+ same block: `pyfly.messaging.kafka.bootstrap-servers` and
+ `pyfly.messaging.rabbitmq.url`.
+
+### Start with the in-memory broker
+
+Lumen's `pyfly.yaml` already runs on the in-memory EDA bus from Chapter 8. To bring the *messaging* abstraction online without standing up Docker, add a single `provider` line.
+
+**Step 1 — Enable the in-memory broker.** Open `pyfly.yaml` and add a `messaging` block under `pyfly`:
+
+```yaml
+pyfly:
+ messaging:
+ provider: "memory"
+```
+
+**Step 2 — Add a listener so there is something to wake up.** Drop the standalone listener from Listing 10.4 (a few pages on) into `src/lumen/messaging/payments_consumer.py`. At startup PyFly discovers the stamped function and subscribes it for you — you write no `subscribe()` call.
+
+!!! tip "Run it"
+ Start the app. The in-memory broker needs no external server, so this
+ works on a laptop with nothing installed:
+
+ ```bash
+ uv run pyfly run
+ ```
+
+ The boot banner reports the framework version and the bound port
+ (`pyfly.server.port`, `8080` by default in v26.6.110):
+
+ ```
+ :: PyFly Framework :: (v26.06.110) (Python 3.13.13)
+ app=lumen version=1.0.0 ... started_in=0.42s port=8080
+ ```
+
+ Nothing else is printed yet — no message has been published. That is
+ expected: the broker is running and the listener is subscribed,
+ waiting. The next sections give it events to carry.
+
+**What just happened.** One YAML line switched the `MessageBrokerPort` bean from "not present" to a working in-memory broker, and the framework auto-subscribed your `@message_listener` to it during startup. No Kafka, no RabbitMQ, no Docker — yet the *exact same code* will run against a real broker once you change that one line to `"kafka"`. That swap-without-recompile property is the whole point of the abstraction.
+
### Kafka
-Add `pyfly[kafka]` to your project and declare the broker in `pyfly.yaml`:
+When you are ready for a real broker, add `pyfly[kafka]` to your project and point the provider at Kafka.
+
+**Step 1 — Install the Kafka extra.** This pulls in `aiokafka`, the async driver PyFly's `KafkaAdapter` wraps:
+
+```bash
+uv add "pyfly[kafka]"
+```
+
+**Step 2 — Declare the broker in `pyfly.yaml`.** Switch the provider and list your brokers:
```yaml
pyfly:
@@ -131,7 +192,7 @@ pyfly:
bootstrap-servers: "kafka-1:9092,kafka-2:9092"
```
-That is all PyFly needs to auto-configure a `KafkaAdapter` and register it as the `MessageBrokerPort` bean. For most services the YAML is sufficient; if you need advanced producer options, construct the adapter manually as a `@bean` inside a `@configuration` class.
+That is all PyFly needs to auto-configure a `KafkaAdapter` and register it as the `MessageBrokerPort` bean. (`bootstrap-servers` is a comma-separated list of `host:port` pairs — the addresses of one or more brokers in the cluster; the client discovers the rest from any one of them.) For most services the YAML is sufficient; if you need advanced producer options, construct the adapter manually as a `@bean` inside a `@configuration` class.
### RabbitMQ
@@ -167,7 +228,7 @@ class BrokerConfig:
### Auto-detection
-When `provider` is `"memory"` (the default) or `"auto"`, PyFly probes installed packages in order:
+When `provider` is `"auto"`, PyFly probes installed packages in order and picks the first broker it finds:
| Priority | Library checked | Adapter selected |
|---|---|---|
@@ -175,7 +236,27 @@ When `provider` is `"memory"` (the default) or `"auto"`, PyFly probes installed
| 2 | `aio_pika` | `RabbitMQAdapter` |
| 3 | *(fallback)* | `InMemoryMessageBroker` |
-Set `provider: "memory"` in `pyfly-test.yaml` and `provider: "kafka"` in `pyfly-prod.yaml`, and every test and production run uses the appropriate adapter without code changes.
+`provider: "memory"` is different from `"auto"`: it *always* selects the in-memory broker regardless of what is installed, which is exactly what you want in tests. An explicit `provider: "kafka"` or `"rabbitmq"` skips probing entirely and demands that adapter's library be present.
+
+The practical pattern is per-environment YAML. Set `provider: "memory"` in `pyfly-test.yaml` and `provider: "kafka"` in `pyfly-prod.yaml`, and every test and production run uses the appropriate adapter without code changes.
+
+!!! tip "Run it"
+ You can confirm which adapter PyFly selected without sending a single
+ message. With messaging enabled, start the app and look for the broker
+ line in the startup log:
+
+ ```bash
+ uv run pyfly run
+ ```
+
+ ```
+ pyfly.messaging provider=memory broker=InMemoryMessageBroker started
+ ```
+
+ Change `provider` to `"kafka"` (with `pyfly[kafka]` installed and a
+ broker reachable) and restart; the same line now reports
+ `broker=KafkaAdapter`. The business code that publishes and consumes
+ did not change — only the YAML did.
---
@@ -296,7 +377,15 @@ When `publish_domain_events` publishes this event, `event_type` is the class nam
### Publishing an integration event directly to the broker
-When a separate service running in a different process needs to receive Lumen's wallet events, the EDA bus must be backed by a real broker adapter. The payload flowing over the wire is the same dict the in-process listeners see. A dedicated `OutboxRelay` (covered in the resilience section) or a broker-backed `EventPublisher` handles the transport:
+When a separate service running in a different process needs to receive Lumen's wallet events, the EDA bus must be backed by a real broker adapter. The payload flowing over the wire is the same dict the in-process listeners see. A dedicated `OutboxRelay` (covered in the resilience section) or a broker-backed `EventPublisher` handles the transport.
+
+It helps to see the publish in its smallest possible form first. The next listing is a plain `async` function — no class, no decorator — that takes a `MessageBrokerPort`, builds the payload, and calls `publish`. Build it in three moves:
+
+**Step 1 — Encode the payload to bytes.** `MessageBrokerPort.publish` only ever sees `bytes`, so the function serialises the event with `json.dumps(...).encode()`. The `.encode()` turns the JSON string into UTF-8 bytes the broker can store verbatim.
+
+**Step 2 — Choose a partition key.** Passing `key=wallet_id.encode()` tells Kafka to route every message for a given wallet to the same partition, which preserves their order. (RabbitMQ ignores the key, so including it is harmless either way.)
+
+**Step 3 — Attach the event-type header.** `headers={"event-type": "FundsDeposited"}` lets a consumer decide whether it cares about this message *before* deserialising the body — cheap routing.
::: listing lumen/messaging/deposit_publisher.py | Listing 10.3 — Publishing a wallet integration event to a Kafka topic
from __future__ import annotations
@@ -338,6 +427,8 @@ async def publish_deposit_event(
`headers={"event-type": "FundsDeposited"}` uses the domain event class name — not a dotted path like `"wallet.fundsdeposited"`. Consumers can inspect the event type without decoding the payload, which is useful for routing and filtering without full deserialisation.
+**What just happened.** You crossed the process boundary. The same `FundsDeposited` fact that `WalletAuditListener` consumed in-process in Chapter 8 is now bytes on a topic, addressable by any service that connects to the broker — and the function that put it there names no broker, only the `MessageBrokerPort` port. Swap the configured adapter and this code is unchanged.
+
!!! warning "Publish after save, not before"
Always drain and publish events *after* `repository.add(wallet)`. If
the save fails, no message reaches the broker and external consumers
@@ -380,6 +471,14 @@ def message_listener(
| `retry_delay` | `float` | `0.0` | Base delay (seconds) between retries — attempt N waits `retry_delay * N`. |
| `dead_letter_topic` | `str \| None` | `None` | When set, a message still failing after `retries` is re-published here. |
+The first listener is a free-standing function — the simplest shape. Build it in three moves:
+
+**Step 1 — Write an async function that takes a `Message`.** Every listener receives one argument: the frozen `Message` envelope (`topic`, `value`, `key`, `headers`). The function must be `async` because the broker awaits it.
+
+**Step 2 — Decorate it with the topic and group.** `@message_listener(topic="wallet.events", group="payments-service")` is the entire subscription. There is no `subscribe()` call to write and no bus to import — the decorator stamps the function with metadata the framework reads at startup.
+
+**Step 3 — Decode inside the handler.** The body checks the `event-type` header, then `json.loads(msg.value)` turns the raw bytes back into a dict. The handler decides what it cares about; here it reacts only to `FundsDeposited`.
+
::: listing lumen/messaging/payments_consumer.py | Listing 10.4 — @message_listener on a standalone function
from __future__ import annotations
@@ -411,9 +510,58 @@ async def on_wallet_event(msg: Message) -> None:
Inside the handler, `msg.headers.get("event-type", "unknown")` inspects the envelope metadata before touching the payload. The header value is the domain event class name — `"FundsDeposited"`, `"WalletOpened"`, or `"FundsWithdrawn"` — matching what Lumen sets on the publisher side.
+!!! tip "Run it"
+ With `provider: "memory"` set (no Docker), this is the full publish →
+ consume round-trip in one place. Save the snippet below as
+ `roundtrip.py` and run it with `uv run python roundtrip.py`:
+
+ ```python
+ import asyncio, json
+ from pyfly.messaging.adapters.memory import InMemoryMessageBroker
+ from lumen.messaging.payments_consumer import on_wallet_event
+
+ async def main() -> None:
+ broker = InMemoryMessageBroker()
+ await broker.subscribe(
+ "wallet.events", on_wallet_event, group="payments-service"
+ )
+ await broker.start()
+ await broker.publish(
+ "wallet.events",
+ json.dumps({
+ "wallet_id": "w-001", "amount": 5000,
+ "currency": "EUR", "balance": 5000,
+ }).encode(),
+ headers={"event-type": "FundsDeposited"},
+ )
+ await asyncio.sleep(0.1) # let the listener run
+ await broker.stop()
+
+ asyncio.run(main())
+ ```
+
+ The listener prints the line it built from the decoded payload:
+
+ ```
+ [Payments] Deposit received: wallet=w-001 amount=5000 EUR
+ ```
+
+ Inside a running app you would *not* write this wiring by hand — the
+ `@message_listener` decorator and the configured broker bean do the
+ `subscribe`/`start`/`stop` for you. This standalone script just makes
+ the round-trip visible in isolation.
+
+**What just happened.** A message you published to `wallet.events` arrived at a function you never explicitly connected to anything. The decorator carried the topic and group; the broker (here in-memory, in production Kafka) did the delivery. That is the consume side of the same abstraction you used to publish — and the function body is broker-agnostic from top to bottom.
+
### Listeners on service classes
-When a listener needs collaborators — a repository, another service — declare it as a method on a `@service` class. PyFly injects the dependencies through the constructor and wires the listener subscription after the bean is initialised:
+When a listener needs collaborators — a repository, another service — declare it as a method on a `@service` class. PyFly injects the dependencies through the constructor and wires the listener subscription after the bean is initialised. The shape changes only slightly from the standalone version:
+
+**Step 1 — Make the class a `@service`.** This registers it in the DI container so the framework can both inject its constructor and discover its listener method.
+
+**Step 2 — Declare collaborators in the constructor.** Here `smtp_client` stands in for an email or push service; the container supplies it. Listing 10.4's free function had nowhere to keep such a dependency — that is the reason to reach for a class.
+
+**Step 3 — Decorate a *method* with `@message_listener`.** The signature gains `self`, but otherwise the decorator and body are identical to the function form. Because the bean is created first, `self._smtp` is ready by the time a message arrives.
::: listing lumen/messaging/notifications_consumer.py | Listing 10.5 — @message_listener on a @service method with dependencies
from __future__ import annotations
@@ -481,6 +629,8 @@ Three formats are worth knowing: JSON for simplicity, Avro for schema-registry-b
### JSON — start here
+*Serialisation* is just the act of turning an in-memory object into a flat sequence of bytes you can store or send, and *deserialisation* is the reverse. The three formats below differ only in how compact those bytes are and how strictly they police the shape of the data.
+
JSON is the right default. It requires no tooling beyond the standard library, every language can parse it, and the payload is readable in broker monitoring UIs. The encoding pattern is two lines:
```python
@@ -507,7 +657,13 @@ JSON's weakness is that the schema is unenforced. If a publisher adds a required
### Avro — schema-registry-backed evolution
-Avro schemas are JSON documents describing the shape of a message. A Schema Registry (Confluent's is the most common, but open-source alternatives exist) stores those schemas and enforces compatibility rules when producers register new versions. The `fastavro` library encodes and decodes the binary payload:
+Avro schemas are JSON documents describing the shape of a message. A Schema Registry (Confluent's is the most common, but open-source alternatives exist) stores those schemas and enforces compatibility rules when producers register new versions. The `fastavro` library encodes and decodes the binary payload. The publish path is the same `broker.publish(...)` you already know; only the encoding step changes:
+
+**Step 1 — Declare the schema once.** `WALLET_DEPOSITED_SCHEMA` lists each field and its Avro type (`string`, `long`). It is a module-level constant so it is written once, not per message.
+
+**Step 2 — Compile it once.** `fastavro.parse_schema(...)` is called at import time and the result cached in `_PARSED`. Parsing on every publish would be wasted work on the hot path.
+
+**Step 3 — Encode and publish.** `fastavro.schemaless_writer` serialises the record into a `BytesIO` buffer; `buf.getvalue()` hands the bytes to `broker.publish` exactly as the JSON path did.
::: listing lumen/messaging/avro_publisher.py | Listing 10.6 — Publishing a wallet event with Avro encoding
from __future__ import annotations
@@ -616,7 +772,13 @@ Without a dead-letter strategy, a failed consumer either drops the message (data
### Decorator-native retry and DLQ
-In PyFly, retry and dead-letter routing are built into `@message_listener` — no try/except scaffolding, no manual publish to the DLQ. Declare `retries` and `dead_letter_topic` directly on the decorator:
+In PyFly, retry and dead-letter routing are built into `@message_listener` — no try/except scaffolding, no manual publish to the DLQ. Declare `retries` and `dead_letter_topic` directly on the decorator. You add resilience by adding *arguments*, not code:
+
+**Step 1 — Start from a normal listener.** The handler body in the next listing is an ordinary consumer that decodes the payload and calls a worker (`_charge`).
+
+**Step 2 — Add `retries` (and optionally `retry_delay`).** `retries=3` tells the framework to re-invoke the handler up to three more times if it raises. `retry_delay=0.5` spaces those attempts out with linear back-off.
+
+**Step 3 — Add `dead_letter_topic`.** When all retries are exhausted, the framework re-publishes the message there instead of letting the exception crash the consumer. You write neither the retry loop nor the DLQ publish.
::: listing lumen/messaging/resilient_consumer.py | Listing 10.7 — Retry and DLQ wired through @message_listener
from __future__ import annotations
@@ -672,6 +834,55 @@ class ResilientWalletConsumer:
The exception is then swallowed so the consumer keeps running — the message is parked, not lost, and the next message on the topic is processed normally.
+!!! tip "Run it"
+ You can watch a poisoned message land in the DLQ without a real broker.
+ At wiring time the framework wraps every listener with
+ `pyfly.messaging.error_handling.wrap_listener` — the same helper does
+ the retrying and dead-lettering. Drive it directly so the flow is
+ visible. Save this as `dlq_demo.py` and run `uv run python dlq_demo.py`:
+
+ ```python
+ import asyncio, json
+ from pyfly.messaging.adapters.memory import InMemoryMessageBroker
+ from pyfly.messaging.error_handling import wrap_listener
+ from pyfly.messaging.types import Message
+
+ async def always_fails(msg: Message) -> None:
+ raise RuntimeError("downstream unavailable")
+
+ async def main() -> None:
+ broker = InMemoryMessageBroker()
+ await broker.start()
+
+ async def show_dlq(msg: Message) -> None:
+ print("DLQ:", msg.headers["x-original-topic"],
+ msg.headers["x-exception"])
+ await broker.subscribe("wallet.events.DLQ", show_dlq)
+
+ handler = wrap_listener(
+ always_fails, broker,
+ retries=2, dead_letter_topic="wallet.events.DLQ",
+ )
+ await handler(Message(
+ topic="wallet.events",
+ value=json.dumps({"wallet_id": "w-001"}).encode(),
+ ))
+ await broker.stop()
+
+ asyncio.run(main())
+ ```
+
+ After two retries the wrapper gives up and re-publishes to the DLQ,
+ where your monitor prints the diagnostic headers:
+
+ ```
+ DLQ: wallet.events RuntimeError
+ ```
+
+ The handler returned normally — the exception was swallowed, not
+ propagated — so in a real app the consumer would simply move on to the
+ next message.
+
### Monitoring the DLQ
Subscribe to the DLQ topic like any other listener to observe and alert on dead-lettered messages:
@@ -722,7 +933,15 @@ A healthy broker is not guaranteed. Network partitions, rolling upgrades, and re
Neither is acceptable. The transactional outbox (Chapter 9) is the atomic solution — the event is captured in the database and a relay publishes it asynchronously, so a broker outage adds only latency, not data loss. Alongside the outbox, **circuit breakers** and **retries** protect the relay and any broker-calling code from cascading failures.
-PyFly's resilience module (`pyfly.resilience`) provides both primitives. The circuit breaker opens after a configurable failure threshold and blocks calls to the broker during a cool-down period, preventing a thundering-herd reconnection storm. The retry decorator handles transient errors with configurable back-off:
+A **circuit breaker** is the electrical metaphor made into code: after too many failures in a row it "trips" and stops letting calls through for a cool-down period, so a struggling broker is not hammered by thousands of doomed reconnection attempts. A **retry** is the complementary tactic — try the same call again a few times, because many failures are momentary.
+
+PyFly's resilience module (`pyfly.resilience`) provides both primitives. The circuit breaker opens after a configurable failure threshold and blocks calls to the broker during a cool-down period, preventing a thundering-herd reconnection storm. The retry decorator handles transient errors with configurable back-off. You apply them as a pair of decorators on the publish method:
+
+**Step 1 — Write the plain publish method.** `forward` does one thing: encode the record and call `self._broker.publish(...)`. No resilience logic lives in the body.
+
+**Step 2 — Wrap it in `@circuit_breaker`.** Pass a shared `CircuitBreaker` instance so the failure count accumulates across calls, not per call. When the broker is down, the breaker trips and fails fast.
+
+**Step 3 — Wrap that in `@retry` on the outside.** Decorator order matters: `@retry` sits above `@circuit_breaker`, so all of one call's retry attempts happen before the breaker registers a single failure. Keep `max_attempts` low and let the breaker absorb sustained outages.
::: listing lumen/messaging/resilient_publisher.py | Listing 10.9 — Resilient broker publishing with retry and circuit breaker
from __future__ import annotations
@@ -829,6 +1048,26 @@ Part IV introduces the `PaymentsService` and `NotificationsService`. Both subscr
## Try it yourself {.exercises}
+!!! note "Run it"
+ Each exercise below ends in a test. Because `provider: "memory"` needs
+ no broker, you can run them with nothing installed beyond the dev
+ extra. From the Lumen project root:
+
+ ```bash
+ uv run --extra dev pytest tests/test_messaging.py -q
+ ```
+
+ A green run looks like:
+
+ ```text
+ ... [100%]
+ 3 passed in 0.XXs
+ ```
+
+ If a test fails with a missing-attribute error such as
+ `__pyfly_message_listener__`, the `@message_listener` decorator is not
+ applied to your handler — recheck Step 2 of "Declarative listeners."
+
1. **Swap the adapter in one line.** Start with `provider: "memory"` in
`pyfly.yaml` and add the `@message_listener` from Listing 10.4. Write
an integration test that publishes a `FundsDeposited` message with
diff --git a/book/manuscript/11-http-clients.md b/book/manuscript/11-http-clients.md
index 63b40660..49be5f85 100644
--- a/book/manuscript/11-http-clients.md
+++ b/book/manuscript/11-http-clients.md
@@ -27,6 +27,24 @@ end of the chapter you will also see how a **BFF (Backend for Frontend)**
tier sits in front of both services and composes their capabilities into
a single, user-journey-focused API.
+!!! note "New jargon, in plain language"
+ A few terms recur throughout this chapter. **Service-to-service call**
+ means one of your services making an HTTP request to another of your
+ services (Wallet calling Payments), as opposed to a request coming
+ from a browser. A **declarative client** is a client you *describe*
+ rather than *implement*: you write the method signatures and let the
+ framework fill in the HTTP plumbing. A **circuit breaker** is a safety
+ switch that stops calling a remote service after it has failed too
+ many times in a row. A **BFF** (Backend for Frontend) is a thin
+ service whose only job is to call other services and reshape their
+ answers for one particular app. We will build each of these one piece
+ at a time.
+
+This chapter is built around `httpx` and the `pyfly.client` package, both
+of which ship with the framework. Everything here runs against PyFly
+v26.6.110. You do not need to install anything new — if you have been
+following along with Lumen, the client tooling is already on your path.
+
---
## Why split (and why it hurts)
@@ -99,7 +117,26 @@ Reserve `@http_client` for internal utilities and test doubles.
The Payments service exposes two endpoints: one to create a payment
instruction and one to retrieve a payment by identifier. Defining the
-client means writing the class:
+client means writing the class. Let us build it one decision at a time.
+
+**Step 1 — Create the file.** Add `src/lumen/sdk/payments_client.py`
+alongside the existing `client.py`. The `sdk` package is where Lumen keeps
+the code that *talks to* services, so this is the natural home for a
+service client.
+
+**Step 2 — Decorate the class.** Put `@service_client(base_url=...)` on a
+plain class. That single decorator is what turns an ordinary class into a
+PyFly-managed HTTP client: it records the base URL, switches on the
+resilience features, and registers the class as a bean so the container
+can inject it later.
+
+**Step 3 — Declare one method per endpoint.** Each method gets a verb
+decorator (`@post`, `@get`, `@patch`, `@delete`) carrying the path. The
+method body is just `...` — an *ellipsis*, Python's literal for "nothing
+here yet." You never write the request code; PyFly writes it for you at
+startup.
+
+The full client looks like this.
::: figure art/figures/11-client.svg | Figure 11.1 — The PyFly declarative client pipeline. You write the interface; HttpClientBeanPostProcessor generates the implementation.
@@ -185,6 +222,42 @@ the dict serialised as the JSON body. Parameters named `body` on
POST/PUT/PATCH methods are always treated as the JSON request body; all other
non-path parameters on GET/DELETE become query-string parameters.
+!!! note "What just happened"
+ You wrote four method *signatures* and zero lines of HTTP code. The
+ `@service_client` decorator tagged the class for the container; the
+ verb decorators tagged each method with a verb and a path. At startup,
+ a behind-the-scenes component called `HttpClientBeanPostProcessor`
+ reads those tags and quietly replaces every `...` stub with a working
+ async method that builds the URL, sends the request, and turns the
+ response back into Python. From the caller's point of view,
+ `await client.get_payment("pay-123")` looks exactly like calling a
+ local method — the network is hidden.
+
+**Run it — confirm the stubs are wired.** Until the application context
+starts, those `...` bodies raise `NotImplementedError` on purpose, so you
+cannot just call the method in a bare script. The honest way to prove the
+client works is a tiny test that starts a context (or wires the
+post-processor) and inspects the generated method. The quickest smoke
+check is to confirm the metadata the decorators stamped on:
+
+```
+uv run python -c "from lumen.sdk.payments_client import PaymentsClient; \
+print(PaymentsClient.__pyfly_http_base_url__); \
+print(PaymentsClient.create_payment.__pyfly_http_method__, \
+PaymentsClient.create_payment.__pyfly_http_path__)"
+```
+
+Expected output:
+
+```
+http://payments-service:8080
+POST /payments
+```
+
+If you see the base URL and `POST /payments`, the decorators applied
+correctly and the post-processor has everything it needs to generate the
+real implementation when the app boots.
+
!!! spring "Spring parity"
`@service_client` with `@get`/`@post`/`@put`/`@delete`/`@patch` is
PyFly's counterpart of Spring Cloud OpenFeign's `@FeignClient` with
@@ -205,10 +278,33 @@ Because `PaymentsClient` is a singleton bean, any `@service` or
container injects it through the same autowiring path used for
repositories and domain services.
+!!! note "Bean and autowiring, briefly"
+ A **bean** is just an object the framework creates and manages for you
+ — you never call its constructor yourself. **Autowiring** is how the
+ container hands a bean to whatever needs it: when a class lists
+ `payments: PaymentsClient` in its `__init__`, PyFly notices the type,
+ finds the matching bean, and passes it in automatically. You declare
+ the dependency by *type*; the container does the lookup.
+
Lumen's Wallet service already applies the `WalletRepository` and `Money`
value object pattern from earlier chapters. When the wallet must call
-Payments to settle a withdrawal, the handler follows that same pattern:
-withdraw through the aggregate, then call the external service:
+Payments to settle a withdrawal, the handler follows that same pattern in
+three steps: load the wallet, withdraw through the aggregate, then call the
+external service.
+
+**Step 1 — Declare the dependency.** Add `payments: PaymentsClient` to the
+handler's constructor and stash it on `self`. That is the only wiring you
+write; the container supplies the live client.
+
+**Step 2 — Do the local work first.** Load the wallet and call
+`wallet.withdraw(...)`, then persist it, so the wallet's own state is
+settled before any network call happens.
+
+**Step 3 — Call the remote service.** `await self._payments.create_payment(...)`
+reads like a local method call. The resilience and HTTP details are
+already baked into the injected client.
+
+Here is the handler.
::: listing lumen/core/services/wallets/settle_transfer_handler.py | Listing 11.2 — CommandHandler injecting PaymentsClient
from __future__ import annotations
@@ -272,6 +368,28 @@ temporarily unavailable, the retry and circuit breaker — described in the
next section — handle recovery transparently, without any code in the
handler.
+**Run it — exercise the handler with a fake client.** Because the handler
+depends on the *type* `PaymentsClient`, you can substitute a stand-in in a
+test without any network. Drop this into `tests/test_settle_transfer.py`
+and run it:
+
+```
+uv run --extra dev pytest tests/test_settle_transfer.py -q
+```
+
+A passing run prints something like:
+
+```
+1 passed in 0.12s
+```
+
+The point of the test is the substitution: you pass a hand-made object in
+place of the real `PaymentsClient`, assert the handler called
+`create_payment` with the expected body, and never open a socket. That is
+the practical payoff of declaring the dependency by type — the handler
+neither knows nor cares whether the client on the other end is real or
+faked.
+
---
## Resilience on the wire
@@ -344,6 +462,60 @@ state transitions `CLOSED → HALF_OPEN` are computed lazily with
the circuit is already open, so re-raising it without recording another
failure prevents the recovery timeout from resetting indefinitely.
+!!! note "Three states, in plain language"
+ Think of the breaker as a light switch with three positions.
+ **Closed** is normal — calls flow through. **Open** means "stop
+ trying" — calls fail instantly without touching the network, which
+ spares your service from waiting on something that is clearly down.
+ **Half-open** is "let me test the water" — after the recovery timeout,
+ the breaker lets exactly one call through; if it works, the switch
+ goes back to closed, and if it fails, it snaps open again.
+
+**Run it — watch a breaker open and recover.** You can drive the breaker
+by hand from a REPL with no real service involved. Start one with
+`uv run python` from `samples/lumen` and try:
+
+```
+uv run python -c "
+import asyncio
+from datetime import timedelta
+from pyfly.client import CircuitBreaker, CircuitState
+from pyfly.kernel.exceptions import CircuitBreakerException
+
+async def boom():
+ raise RuntimeError('payments down')
+
+async def main():
+ cb = CircuitBreaker(failure_threshold=2, recovery_timeout=timedelta(seconds=30))
+ for _ in range(2):
+ try:
+ await cb.call(boom)
+ except RuntimeError:
+ pass
+ print('state after 2 failures:', cb.state.name)
+ try:
+ await cb.call(boom)
+ except CircuitBreakerException:
+ print('open circuit rejected the call without calling boom')
+
+asyncio.run(main())
+"
+```
+
+Expected output:
+
+```
+state after 2 failures: OPEN
+open circuit rejected the call without calling boom
+```
+
+The second line is the whole point: once the circuit is open, the breaker
+raises `CircuitBreakerException` *immediately* instead of running `boom`
+again. Drop `recovery_timeout` to `timedelta(seconds=0)` and re-run — the
+next read of `cb.state` reports `HALF_OPEN` and the third call admits a
+probe (so `boom` runs again) rather than being rejected. That is the
+breaker letting the service prove it has recovered.
+
### Retry policy
Transient failures — a momentary latency spike, a rolling restart, a
@@ -383,6 +555,50 @@ others propagate immediately. This matters: you do not want to retry a
404 (the resource does not exist) or a 422 (the request is semantically
invalid).
+!!! note "Backoff, in plain language"
+ *Backoff* means waiting a little longer before each retry instead of
+ hammering the remote service the instant it fails. *Exponential*
+ backoff doubles the wait each time, so a service that needs a moment
+ to recover gets more breathing room with every attempt while a healthy
+ one is retried almost immediately.
+
+**Run it — see retry recover from a transient error.** Simulate a call
+that fails twice and then succeeds:
+
+```
+uv run python -c "
+import asyncio
+from datetime import timedelta
+from pyfly.client import RetryPolicy
+
+attempts = {'n': 0}
+async def flaky():
+ attempts['n'] += 1
+ if attempts['n'] < 3:
+ raise ConnectionError('reset')
+ return 'ok'
+
+async def main():
+ policy = RetryPolicy(max_attempts=3, base_delay=timedelta(milliseconds=1),
+ retry_on=(ConnectionError,))
+ print('result:', await policy.execute(flaky))
+ print('attempts:', attempts['n'])
+
+asyncio.run(main())
+"
+```
+
+Expected output:
+
+```
+result: ok
+attempts: 3
+```
+
+Three attempts, one success. Change `retry_on` to `(TimeoutError,)` and
+the very first `ConnectionError` propagates instead — proof that only the
+exceptions you list are retried.
+
When `@service_client` enables both features, the post-processor wraps
them in the correct order: circuit breaker *outside*, retry *inside*. A
single logical call attempts up to `max_attempts` retries before the
@@ -393,7 +609,10 @@ immediately, bypassing the retry loop entirely.
When the remote service returns a 4xx or 5xx response, the generated
method raises a typed exception instead of returning the error payload as
-if it were a success. The exception hierarchy lives in `pyfly.client`:
+if it were a success. The exception hierarchy lives in
+`pyfly.client.exceptions` — import the classes you want to catch from
+there (for example,
+`from pyfly.client.exceptions import ServiceNotFoundException`):
| Status | Exception class | `retryable` |
|---|---|---|
@@ -411,6 +630,16 @@ All exceptions extend `ServiceClientException` (itself an
post-processor which exceptions to pass to the retry policy. 4xx
validation errors and 404s are never retried.
+!!! note "What just happened"
+ The three resilience pieces fit together like nested boxes. The
+ **typed exceptions** classify *what kind* of failure occurred — a 404
+ is not retryable, a 503 is. The **retry policy** uses that
+ classification to decide whether to try again. The **circuit breaker**
+ sits outside the retry loop and counts sustained failures so it can
+ stop calling a service that is genuinely down. You did not write any
+ of this glue: `@service_client` assembled it the moment you set
+ `circuit_breaker=True` and `retry=3`.
+
### Configuring defaults in pyfly.yaml
Per-service overrides on `@service_client` always take precedence.
@@ -444,6 +673,41 @@ to `HttpClientBeanPostProcessor`. Any value set directly on
`@service_client(circuit_breaker_failure_threshold=...)` overrides the
default.
+!!! note "Precedence, in plain language"
+ Two layers can set these knobs: the global `pyfly.yaml` defaults and
+ the per-client decorator arguments. The decorator always wins. Think
+ of `pyfly.yaml` as the house style every new client inherits, and the
+ decorator as the place to override that style for one demanding
+ upstream.
+
+**Run it — confirm the config is read.** After adding the block to
+`pyfly.yaml`, read the values back through PyFly's `Config` to be sure the
+keys are spelled correctly (a common cause of "my timeout is being
+ignored" is a typo). Run this from the project root, where `pyfly.yaml`
+lives:
+
+```
+uv run python -c "
+from pyfly.core.config import Config
+cfg = Config.from_sources('.')
+print('timeout:', cfg.get('pyfly.client.timeout'))
+print('cb:', cfg.get('pyfly.client.circuit-breaker'))
+"
+```
+
+Expected output once Listing 11.5 is in place:
+
+```
+timeout: 10
+cb: {'failure-threshold': 5, 'recovery-timeout': 30}
+```
+
+Before you add the block, `timeout` reports `30` — the framework default
+from `pyfly-defaults.yaml` — which confirms the override is what changed
+it. If a key comes back as `None`, check the indentation in `pyfly.yaml`:
+YAML nesting is whitespace-sensitive, and a misaligned `circuit-breaker:`
+silently lands under the wrong parent.
+
!!! tip "Set per-service timeouts low"
The default `timeout: 30` is conservative. In production, each
service should carry a `pyfly.yaml` override tuned to its SLA. A
@@ -464,6 +728,23 @@ treated specially by the post-processor: when a stub method declares
`headers: dict`, the value is forwarded as HTTP request headers, not
serialised as a query string.
+!!! note "JWT, in plain language"
+ A **JWT** (JSON Web Token) is a signed string that travels in the
+ `Authorization` header and proves who the caller is. When Wallet
+ forwards the caller's JWT to Payments, Payments can re-check it and
+ apply its own rules — the identity is carried across the network
+ boundary rather than re-established from scratch.
+
+To forward headers, you add a single optional parameter. There is no new
+decorator and no special configuration:
+
+- **Add `headers: dict | None = None` to the method.** The name `headers`
+ is the magic word — the post-processor recognises it and routes its
+ value to HTTP headers instead of the query string.
+- **Pass a dict at the call site.** The handler supplies
+ `headers={"Authorization": f"Bearer {token}"}`, and PyFly attaches it to
+ the outgoing request.
+
::: listing lumen/sdk/payments_client_auth.py | Listing 11.6 — Forwarding auth headers per-call
from __future__ import annotations
@@ -636,9 +917,22 @@ domain service clients.
### Building the Lumen BFF
The Lumen SDK already ships a `LumenClient` in `lumen/sdk/client.py` that
-wraps a raw `httpx.AsyncClient`. In the BFF tier you use PyFly's
-declarative `@service_client` instead — the interface is identical but
-resilience is built in automatically. Here is the wallet-side client:
+wraps a raw `httpx.AsyncClient` — it takes an `httpx.AsyncClient` in its
+constructor and calls `self._http.get(...)`/`self._http.post(...)` by hand,
+raising on error with `response.raise_for_status()`. That is the
+*imperative* style: useful, explicit, and entirely your responsibility to
+keep resilient. In the BFF tier you use PyFly's declarative
+`@service_client` instead — the calling code looks the same, but the
+circuit breaker and retry are built in automatically.
+
+We will build the BFF in four small pieces, each its own file:
+
+**Step 1 — A `WalletClient`** that knows how to reach the Wallet service.
+**Step 2 — A `PaymentsClient`** with one extra endpoint the BFF needs.
+**Step 3 — A `WalletSummaryService`** that calls both and merges the
+results. **Step 4 — A thin controller** that exposes the merged view.
+
+Start with the wallet-side client.
::: listing lumen_bff/sdk/wallet_client.py | Listing 11.9 — WalletClient for the BFF tier
from __future__ import annotations
@@ -701,7 +995,16 @@ class PaymentsClient:
:::
The BFF service then composes the wallet balance with the pending payments
-list into a single response:
+list into a single response.
+
+!!! note "asyncio.gather, in plain language"
+ `asyncio.gather(a, b)` starts coroutines `a` and `b` at the same time
+ and waits for both to finish, returning their results as a list. For a
+ BFF this means two upstream calls overlap instead of queuing one after
+ the other. Adding `return_exceptions=True` changes one thing: instead
+ of the whole `gather` blowing up when one call fails, the failed call's
+ exception is handed back as that call's *result*, so you can inspect it
+ and still use the successful one.
::: listing lumen_bff/application/bff_service.py | Listing 11.11 — BFF service composing Wallet + Payments
from __future__ import annotations
@@ -814,6 +1117,36 @@ controller → BFF service → declarative clients → remote HTTP. Each layer
is independently testable: the controller with a mock service, the
service with mock clients, and the clients with a mock `HttpClientPort`.
+**Run it — call the composed endpoint.** With the BFF application running
+(`uv run pyfly run --server uvicorn`) and the Wallet and Payments services
+reachable, hit the summary route with a wallet id you have already
+created:
+
+```
+curl -s http://localhost:8080/api/v1/wallets/wal-123/summary
+```
+
+Expected shape (values depend on your data):
+
+```
+{"wallet_id": "wal-123", "balance_minor": 5000, "pending_payments": []}
+```
+
+The single response merges two upstream services. To see the graceful
+degradation in action, stop the Payments service and call again — the
+`balance_minor` still comes back from Wallet, and `pending_payments`
+falls back to `[]` rather than the whole request returning a 500. That is
+`return_exceptions=True` doing its job.
+
+!!! note "Default app port"
+ PyFly serves the application on `pyfly.server.port`, which defaults to
+ `8080` (matching Spring's `server.port`). Override it with the
+ `PYFLY_SERVER_PORT` environment variable or the `pyfly.server.port`
+ config key. Note that the actuator and admin dashboard run on a
+ *separate* management port — `pyfly.management.server.port`, default
+ `9090` — so health and info endpoints never collide with your API
+ routes.
+
!!! note "BFF scope and team ownership"
A BFF is scoped to one frontend or one user journey — not one per
microservice. Lumen might have a `lumen-mobile-bff` and a
@@ -896,11 +1229,15 @@ Three principles carry through the rest of Part IV:
2. **Test the BFF with degraded upstream services.** Write a unit test
for `WalletSummaryService.get_summary` that mocks
`WalletClient.get_wallet` to succeed and
- `PaymentsClient.list_pending` to raise `ServiceUnavailableException`.
+ `PaymentsClient.list_pending` to raise `ServiceUnavailableException`
+ (import it with
+ `from pyfly.client.exceptions import ServiceUnavailableException`).
Assert that the method returns a dict with the correct `balance_minor`
and an empty `pending_payments` list — confirming that the
partial-response fallback works and a single upstream failure does not
- propagate as an exception to the BFF's caller.
+ propagate as an exception to the BFF's caller. Run it with
+ `uv run --extra dev pytest tests/test_wallet_summary.py -q` and look
+ for `1 passed`.
3. **Tune circuit breaker thresholds for a brittle upstream.** Suppose
Payments has a known flakiness window during its nightly batch run:
diff --git a/book/manuscript/12-sagas.md b/book/manuscript/12-sagas.md
index e65c3e56..9df20e2a 100644
--- a/book/manuscript/12-sagas.md
+++ b/book/manuscript/12-sagas.md
@@ -86,11 +86,24 @@ method as a step with its compensation, and declare the dependency
ordering. The engine discovers the class through the DI container, builds
a validated DAG at startup, and drives execution asynchronously.
+!!! note "New term: orchestration"
+ *Orchestration* means one central component — here, PyFly's `SagaEngine` — decides the order in which steps run and what to do when one fails. The alternative, *choreography*, has each service react to events with no central conductor. This chapter uses orchestration because it makes the recovery path explicit and easy to test: the engine owns the rules, your saga class just declares the steps.
+
+We will build the transfer saga in four moves: turn the engine on, declare
+the saga class, look at the DAG the engine builds from it, then call the
+engine from a service. Take them one at a time.
+
### Enabling the engine
The transactional engine is activated by the `@enable_domain_stack`
-starter decorator on your application class, together with a single YAML
-property. In Lumen:
+starter decorator on your application class — and that single decorator is
+all you need. No extra YAML is required. In Lumen:
+
+**Add the starter decorator.** Open your application class and
+stack `@enable_domain_stack` above `@pyfly_application`. A *starter*
+decorator is PyFly's way of switching on a whole feature area (here, the
+transactional engine and its DI wiring) without you registering each
+component by hand — the Spring equivalent is an `@EnableXxx` annotation.
::: listing lumen/app.py | Listing 12.1 — Enabling the transactional engine via the domain stack
from pyfly.core import pyfly_application
@@ -110,7 +123,17 @@ class LumenApplication:
pass
:::
-Add the property in `application.yaml`:
+**Turning it off, or on under a narrower starter.** `@enable_domain_stack`
+already sets `pyfly.transactional.enabled: true` for you, so the engine is
+live as soon as the decorator is on the class. The same property is the
+knob you reach for in two situations:
+
+- **To switch the engine off** under the domain stack, set it to `false` in
+ `application.yaml` — the auto-configuration is gated on the value being
+ exactly `"true"`, so anything else disables it.
+- **To switch it on under a narrower starter** such as `@enable_core_stack`
+ (which does *not* include the transactional engine), add the property
+ yourself:
```yaml
pyfly:
@@ -118,17 +141,41 @@ pyfly:
enabled: true
```
-**How it works:** `@enable_domain_stack` imports
-`TransactionalEngineAutoConfiguration`, guarded by
-`@conditional_on_property("pyfly.transactional.enabled", having_value="true")`.
-When the property is set, the auto-configuration wires every engine
-component — `SagaEngine`, `TccEngine`, `WorkflowEngine`, `SagaRegistry`,
+!!! note "Run it: confirm the engine wired up"
+ Start the app on its default port (`pyfly.server.port` is `8080` in v26.6.110) and watch the startup log:
+
+ ```bash
+ uv run pyfly run
+ ```
+
+ Among the startup lines you should see the transactional components register, for example:
+
+ ```
+ INFO pyfly.starters.domain domain stack enabled: transactional engine active
+ INFO pyfly.transactional registered saga 'money-transfer' (2 steps)
+ INFO pyfly.server Uvicorn running on http://0.0.0.0:8080
+ ```
+
+ If you explicitly set `transactional.enabled: false` (or enable only the core stack without adding the property), the saga line never appears and `SagaEngine.execute(...)` later raises `ValueError: Saga 'money-transfer' is not registered`. Seeing the `registered saga` line is your proof the wiring worked.
+
+**How it works:** `@enable_domain_stack` merges `DOMAIN_STACK_PROPERTIES`
+into the active config, and that dict already contains
+`pyfly.transactional.enabled: "true"` — so the decorator both registers
+*and* activates the engine in one move. The auto-configuration,
+`TransactionalEngineAutoConfiguration`, is guarded by
+`@conditional_on_property("pyfly.transactional.enabled", having_value="true")`;
+because the starter set the value to `"true"`, the condition matches and
+the auto-configuration wires every engine component — `SagaEngine`,
+`TccEngine`, `WorkflowEngine`, `SagaRegistry`,
`InMemoryPersistenceAdapter`, and `LoggerEventsAdapter` — into the DI
container. The `OrchestrationBeanPostProcessor` then scans every bean
produced at startup: any bean carrying `__pyfly_saga__` metadata is
registered into `SagaRegistry` automatically. You never call
`registry.register_from_bean()` in production code.
+!!! note "What just happened"
+ One small change — a single decorator — gave you a fully wired saga engine. `@enable_domain_stack` both declared the components and turned them on (it sets `pyfly.transactional.enabled: true` for you), and a startup bean post-processor found your saga classes and registered them for you. From here on you only write saga classes and call `SagaEngine.execute(...)`; the plumbing is done.
+
### Declaring the transfer saga
Lumen's wallet transfer is a two-step saga: debit the source wallet, then
@@ -136,6 +183,14 @@ credit the destination. If the credit fails — wrong currency or missing
wallet — the engine compensates by re-crediting the source, returning both
balances to their original values.
+!!! note "New term: compensation"
+ A *compensation* (or *compensating transaction*) is the undo for a step. It is not a database rollback — by the time you compensate, the original write has already committed to its own store. Instead it is a *new forward operation* that semantically reverses the effect. The undo for "debit the source" is not `ROLLBACK`; it is "deposit the same amount back into the source". Every step that changes state needs a matching compensation.
+
+Build it in three moves. **Step 1** — declare the class and stack the
+decorators. **Step 2** — write the forward steps and their compensation.
+**Step 3** — wire the parameters with injection markers. The complete file
+is below; we then walk each move.
+
::: listing lumen/core/services/transfers/money_transfer_saga.py | Listing 12.2 — MoneyTransferSaga: debit → credit, with compensation
from __future__ import annotations
@@ -245,6 +300,7 @@ class MoneyTransferSaga:
**How it works — step by step:**
+**Step 1 — the decorator stack.**
`@saga(name=MONEY_TRANSFER_SAGA)` stamps `__pyfly_saga__` on the class
with the saga name. The decorator only attaches metadata — it does not
wrap the class or create a proxy. **The critical requirement** is that
@@ -255,6 +311,10 @@ causes the DI container to instantiate and scan the bean at startup; the
Without `@service`, the class is never scanned and the saga cannot be
executed by name.
+!!! warning "Decorator order is not optional"
+ Read the stack top-to-bottom: `@saga` is *above* `@service`. Swap them — `@service` above `@saga` — and the bean still registers with DI, but the saga metadata is applied to the already-wrapped object, the post-processor never finds it, and `execute("money-transfer")` fails with `ValueError: Saga 'money-transfer' is not registered`. If you hit that error, check the decorator order first.
+
+**Step 2 — the step methods.**
`@saga_step` attaches `__pyfly_saga_step__` metadata directly to the
async method — no wrapper, no proxy — so `inspect.iscoroutinefunction`
keeps returning `True` and the engine correctly `await`s the call. The
@@ -282,6 +342,7 @@ Because saga steps share one `AsyncSession`, `upsert` flushes so each
step sees the previous step's write; the surrounding application boundary
owns the final commit.
+**Step 3 — wire the parameters.**
Parameter injection uses `typing.Annotated` with **marker instances**, not
bare classes:
@@ -302,8 +363,14 @@ back, and upserts — the same load-mutate-save cycle as the forward steps.
Compensations always read from `ctx.step_results` via `FromStep`, never
from the original input.
+!!! note "What just happened"
+ You wrote one class that holds the whole transfer story: a forward step to debit, its compensation to re-credit, and a second forward step to credit. The decorators told the engine *what each method is* (a step, a compensation) and *how they connect* (`compensate=`, `depends_on=`). You did not write any orchestration loop or try/except rollback logic — that is the engine's job. Your code only describes the business operation and its undo.
+
### The step DAG
+!!! note "New term: DAG"
+ A *DAG* — directed acyclic graph — is a set of steps connected by "must-run-before" arrows, with no cycles (no step can, directly or indirectly, depend on itself). The engine reads your `depends_on` declarations, builds this graph, and sorts it into *layers*: everything in layer 0 has no unmet dependencies and runs first; layer 1 runs once layer 0 finishes; and so on. Steps in the same layer are independent, so the engine runs them at the same time. A cycle would make the layering impossible, so the engine rejects it at startup rather than at run time.
+
The two steps form a linear chain:
::: figure art/figures/12-saga.svg | Figure 12.1 — DAG for MoneyTransferSaga: steps run in topological-layer order; independent steps in a layer run with asyncio.gather.
@@ -322,7 +389,14 @@ two checks in the same layer and run them concurrently with
### Executing the saga
-Inject `SagaEngine` from the DI container and call `execute`:
+The saga class only *describes* the operation. To *run* it you need a thin
+service that injects the engine and calls it by name.
+
+**Step 1 — inject `SagaEngine`.** Declare a `@service` whose constructor
+takes a `SagaEngine` parameter; the DI container hands you the
+auto-configured engine. **Step 2 — call `execute`** with the saga name and
+the input payload. **Step 3 — fold the `SagaResult`** into a small,
+JSON-friendly dict for the caller.
::: listing lumen/core/services/transfers/transfer_service.py | Listing 12.3 — Executing the money transfer saga
from __future__ import annotations
@@ -385,6 +459,44 @@ successfully rolled back.
- `result.correlation_id` — UUID to correlate logs and traces across services.
- `result.error` — the exception that stopped the saga, or `None` on success.
+!!! note "Run it: the happy path and the compensated path"
+ Expose `TransferService.transfer` behind an HTTP route (Chapter 11 covered controllers) and exercise both outcomes against the running app on `pyfly.server.port` (`8080`).
+
+ A valid transfer between two existing same-currency wallets returns the completed summary:
+
+ ```bash
+ curl -s -X POST http://localhost:8080/transfers \
+ -d '{"source_wallet_id":"w-1","destination_wallet_id":"w-2","amount":500,"currency":"EUR"}'
+ ```
+
+ ```json
+ {
+ "status": "completed",
+ "correlation_id": "8f3c…",
+ "source_balance": 9500,
+ "destination_balance": 10500
+ }
+ ```
+
+ Now point the transfer at a destination wallet that does not exist. `credit-destination` raises `AggregateNotFound`, the engine compensates `debit-source`, and the response reports exactly that:
+
+ ```bash
+ curl -s -X POST http://localhost:8080/transfers \
+ -d '{"source_wallet_id":"w-1","destination_wallet_id":"does-not-exist","amount":500,"currency":"EUR"}'
+ ```
+
+ ```json
+ {
+ "status": "failed",
+ "correlation_id": "1a2b…",
+ "failed_steps": ["credit-destination"],
+ "compensated_steps": ["debit-source"],
+ "error": "Wallet 'does-not-exist' not found"
+ }
+ ```
+
+ The key observation: re-read `w-1` afterwards and its balance is back to `9500` — `debit-source` was rolled back by `recredit_source`. A failed transfer leaves both wallets exactly as they started.
+
!!! spring "Spring parity"
`@saga` / `@saga_step` mirror `@Saga` / `@SagaStep` in the Java `fireflyframework-transactional-engine` library. The decorator-stack rule (`@saga` on `@service`) mirrors the Java rule that `@Saga` must be on a `@Service`-annotated class so the `WorkflowBeanPostProcessor` can discover it. The parameter-injection markers (`Input()`, `FromStep("id")`) map directly to `@Input` and `@FromStep` in the Java version. The async model differs: Java uses Project Reactor (`Mono`) while PyFly uses native `async/await` with `asyncio.gather` for parallel layers.
@@ -421,6 +533,38 @@ reads the `DebitResult` that `debit_source` stored in the context when it
completed — so you always compensate with the actual committed data, never
an approximation.
+!!! note "Run it: prove compensation in a test"
+ You do not need a running server to verify the unhappy path — a fast unit test against the engine is enough, and it is the kind of test you will write for every saga. Drive `TransferService.transfer` with a destination wallet that does not exist, then assert the compensation ran:
+
+ ```python
+ async def test_failed_transfer_compensates_the_debit(transfer_service):
+ result = await transfer_service.transfer(
+ TransferRequest(
+ source_wallet_id="w-1",
+ destination_wallet_id="does-not-exist",
+ amount=500,
+ currency=Currency.EUR,
+ )
+ )
+ assert result["status"] == "failed"
+ assert result["failed_steps"] == ["credit-destination"]
+ assert result["compensated_steps"] == ["debit-source"]
+ ```
+
+ Run just this test (the `--extra dev` group installs pytest; Chapter 16 covers fixtures in depth):
+
+ ```bash
+ uv run --extra dev pytest -q -k compensates
+ ```
+
+ Expected output:
+
+ ```
+ 1 passed in 0.05s
+ ```
+
+ A green test here is your guarantee that a broken transfer never leaves money missing.
+
### Compensation policies
Five policies govern how the engine runs compensations. Set the global
diff --git a/book/manuscript/13-caching-resilience.md b/book/manuscript/13-caching-resilience.md
index 87288887..f4ea85cc 100644
--- a/book/manuscript/13-caching-resilience.md
+++ b/book/manuscript/13-caching-resilience.md
@@ -38,12 +38,31 @@ in the right order.
By the end of the chapter, every hot path in Lumen will be cached and every
outbound dependency wrapped in a resilience fence.
+!!! note "What you will build, in plain terms"
+ This chapter introduces a lot of vocabulary — *cache*, *token bucket*,
+ *bulkhead*, *circuit breaker*. Do not let the jargon intimidate you. Every
+ one of these is a small, self-contained tool that you bolt onto a function
+ with a single decorator. We will introduce each tool one at a time, build
+ it into Lumen step by step, run it, and watch what changes. By the end you
+ will have a mental checklist: *is this read hot? cache it; is this call
+ going over the network? fence it.* The version of PyFly used throughout is
+ **v26.6.110** — every command and config key below matches that release.
+
---
## Caching the read path
### Why cache wallet reads?
+!!! note "New term: cache"
+ A *cache* is a small, fast holding area where you keep the answer to an
+ expensive question so you can hand it back instantly the next time someone
+ asks. The first time Lumen computes wallet `w-001`'s balance it stores the
+ result in the cache; subsequent reads return that stored copy without
+ re-running the database query. The trade-off — and there is always a
+ trade-off — is that the stored copy can be slightly out of date. The rest
+ of this section is about keeping that staleness inside acceptable bounds.
+
Lumen's most frequent operation is the balance query: "what is wallet
`w-001`'s current balance?" Under normal load that query hits the read
replica. Under heavy load it competes with deposit commands, saga
@@ -91,7 +110,11 @@ with zero cleanup overhead on your side.
### Setting up a cache backend
-For development, a single import is all you need:
+We will wire up two backends: an in-process one for development and a shared
+Redis-backed one for production. Take them one at a time.
+
+**Step 1 — Pick a development backend.** For development, a single import is
+all you need:
::: listing lumen/cache/config_dev.py | Listing 13.1 — InMemoryCache for development
from pyfly.cache.adapters.memory import InMemoryCache
@@ -103,7 +126,16 @@ wallet_cache = InMemoryCache(max_size=1000)
entries, the least-recently-used entry is dropped to make room. Pass `None`
(the default) to leave the cache unbounded and rely entirely on TTLs.
-For production, point `RedisCacheAdapter` at a `redis.asyncio.Redis` client:
+!!! note "New term: LRU and TTL"
+ *LRU* stands for *least-recently-used* — when the cache is full, the entry
+ nobody has touched for the longest is the one evicted to make room. *TTL*
+ stands for *time-to-live* — how long an entry stays valid before it expires
+ on its own. `InMemoryCache` supports both: `max_size` caps how many entries
+ it holds (LRU); each `put` can carry a TTL that ages the entry out.
+
+**Step 2 — Pick a production backend.** For production, point
+`RedisCacheAdapter` at a `redis.asyncio.Redis` client, and wrap it with an
+in-memory fallback so a Redis hiccup never takes Lumen down:
::: listing lumen/cache/config_prod.py | Listing 13.2 — RedisCacheAdapter for production
import redis.asyncio as aioredis
@@ -134,8 +166,37 @@ required. The `@bean` method tells PyFly's DI container to create a
singleton and inject it wherever `CacheAdapter` is declared as a
dependency.
+**What just happened.** You now have one `CacheAdapter` interface and two
+ways to satisfy it. In development you hand the DI container an
+`InMemoryCache`; in production you hand it a `CacheManager` that fronts Redis
+and quietly falls back to memory when Redis is unreachable. Every handler in
+the rest of this chapter asks for `cache: CacheAdapter` in its constructor and
+never knows or cares which one it got — that is the hexagonal payoff.
+
!!! tip "Auto-configuration"
- Add `pyfly.cache.enabled: true` and `pyfly.cache.provider: redis` to `pyfly.yaml` and PyFly will wire `RedisCacheAdapter` + `InMemoryCache` into a `CacheManager` automatically — no `@configuration` class needed.
+ You do not have to write the `@configuration` class at all. Add the
+ following to `pyfly.yaml` and PyFly's `CacheAutoConfiguration` builds a
+ `CacheAdapter` bean for you at startup:
+
+ ```yaml
+ pyfly:
+ cache:
+ enabled: true # required to switch the subsystem on
+ provider: redis # redis | postgres | memory | auto
+ redis:
+ url: redis://localhost:6379/0
+ max-size: 1000 # used by the memory provider
+ ```
+
+ With `provider: redis` (or `auto`, which detects an installed
+ `redis.asyncio`) the auto-config wires a `RedisCacheAdapter` pointed at
+ `pyfly.cache.redis.url`. It registers that single adapter as the
+ `CacheAdapter` bean — it does **not** add the in-memory failover layer.
+ When you want Redis *plus* the transparent in-process fallback shown in
+ Listing 13.2, declare the `CacheManager` yourself in a `@configuration`
+ class as above. The auto-config also backs off entirely if you have
+ already defined your own `CacheAdapter` bean (`@conditional_on_missing_bean`),
+ so the two approaches never collide.
### @cacheable — skip execution on a hit
@@ -145,9 +206,24 @@ the same key it returns the stored value *without executing the function body
at all*.
Lumen's `GetBalanceHandler` is a natural fit: balance reads are frequent,
-cheap to cache, and tolerate a few seconds of staleness. The handler receives
-`CacheAdapter` through its constructor — injected by PyFly — and wraps
-`do_handle` at construction time:
+cheap to cache, and tolerate a few seconds of staleness. We will add caching
+to it in three small moves.
+
+**Step 1 — Accept the cache.** Add a `cache: CacheAdapter` parameter to the
+constructor. PyFly's DI container sees the type and injects whichever backend
+you wired up in the previous section.
+
+**Step 2 — Move the real work into a private method.** Rename the body that
+hits the database to `_fetch`. This is the function the cache will wrap.
+
+**Step 3 — Wrap it at construction time.** Inside `__init__`, set
+`self.do_handle = cacheable(...)(self._fetch)`. We wrap inside `__init__`
+(rather than as a `@cacheable` decorator on the method) for one reason: the
+`backend=cache` argument only exists once `cache` has been injected, and that
+does not happen until `__init__` runs.
+
+The handler receives `CacheAdapter` through its constructor — injected by
+PyFly — and wraps `do_handle` at construction time:
::: listing lumen/core/services/wallets/get_balance_handler.py | Listing 13.3 — @cacheable on GetBalanceHandler
from datetime import timedelta
@@ -227,6 +303,69 @@ cacheable(
)(self._fetch)
```
+#### Run it — prove the second read skips the database
+
+The cleanest way to *see* a cache hit is a unit test that counts how many
+times the repository is called. Use a real `InMemoryCache` (no Redis needed)
+and a tiny stub repository:
+
+::: listing tests/cache/test_get_balance_cache.py | Listing 13.3a — A test that proves the second read is a hit
+from datetime import timedelta
+
+import pytest
+
+from pyfly.cache import cacheable
+from pyfly.cache.adapters.memory import InMemoryCache
+
+
+class _CountingRepo:
+ """Stub repository that records how many times it is queried."""
+
+ def __init__(self) -> None:
+ self.calls = 0
+
+ async def find_by_id(self, wallet_id: str) -> dict:
+ self.calls += 1
+ return {"wallet_id": wallet_id, "balance_minor": 500}
+
+
+@pytest.mark.asyncio
+async def test_second_read_is_a_cache_hit() -> None:
+ repo = _CountingRepo()
+ cache = InMemoryCache(max_size=10)
+
+ fetch = cacheable(
+ backend=cache,
+ key="wallet:balance:{wallet_id}",
+ ttl=timedelta(seconds=5),
+ )(repo.find_by_id)
+
+ first = await fetch("wlt-001") # miss -> runs the repo
+ second = await fetch("wlt-001") # hit -> repo NOT called again
+
+ assert first == second
+ assert repo.calls == 1 # the body ran exactly once
+:::
+
+Run just this test:
+
+```console
+$ uv run --extra dev pytest tests/cache/test_get_balance_cache.py -q
+. [100%]
+1 passed in 0.04s
+```
+
+The single `.` and `1 passed` confirm it: the second call returned the cached
+value and `repo.calls` stayed at `1`, so the database was touched exactly once
+across two reads. That is a cache hit, demonstrated rather than asserted in
+prose.
+
+**What just happened.** You wrapped a plain async function with `cacheable`,
+backed it with an `InMemoryCache`, and confirmed that identical keys
+short-circuit the body. In `GetBalanceHandler` the wrapped function is
+`_fetch` and the backend is the injected `CacheAdapter`, but the mechanics are
+exactly what you just ran.
+
!!! spring "Spring parity"
`@cacheable` mirrors Spring's `@Cacheable`. The `key` template uses Python's `str.format` syntax instead of SpEL, but the semantics — skip-on-hit, store-on-miss, `condition`, `unless` — are identical. `@cache` is a lower-level alias that behaves the same way; use whichever name reads better in your codebase.
@@ -240,8 +379,22 @@ the cache current.
`DepositFundsHandler` is the canonical example. After a deposit succeeds,
the new balance must be visible to the next read without waiting for the TTL
-to expire. Wrapping `do_handle` with `@cache_put` refreshes the cache entry
-atomically with the write:
+to expire. The wiring mirrors what you did for `@cacheable`, with one critical
+detail to watch:
+
+**Step 1 — Accept the cache** in the constructor, exactly as before.
+
+**Step 2 — Move the deposit logic into `_deposit`** and keep its
+`@transactional()` decorator so the write still commits as one unit of work.
+
+**Step 3 — Wrap with `cache_put`, reusing the *same* key shape.** The deposit
+handler must write to the very cache slot the balance reader looks up.
+`@cacheable` uses `"wallet:balance:{query.wallet_id}"`; here the argument is
+named `command`, so the template is `"wallet:balance:{command.wallet_id}"`.
+Different parameter names, but both resolve to `wallet:balance:wlt-001`.
+
+Wrapping `do_handle` with `@cache_put` refreshes the cache entry atomically
+with the write:
::: listing lumen/core/services/wallets/deposit_funds_handler.py | Listing 13.4 — @cache_put refreshes the cache on a deposit
from datetime import timedelta
@@ -395,6 +548,13 @@ A coherent strategy matches each operation to the right decorator:
### Why protection matters
+!!! note "New term: resilience"
+ *Resilience* here means the system keeps serving requests it *can* serve
+ even when a dependency it relies on is slow, overloaded, or down. The tools
+ in this section do not make the downstream faster — they stop one sick
+ dependency from making the whole of Lumen sick. Each tool is, again, a
+ decorator you stack on the function that makes the risky call.
+
Caching makes the happy path fast. Resilience patterns protect Lumen when
the happy path is unavailable. Without protection, a slow `AccountService`
triggers a cascade:
@@ -462,12 +622,72 @@ sees 10 calls per second can absorb a burst of 40 calls immediately
(drawing on saved tokens), then sustains 20 calls per second afterwards.
Fixed-window rate limiters cannot express this nuance.
+#### Run it — watch the bucket run dry
+
+A small script makes the behaviour concrete. Create a limiter with a tiny
+bucket, call past its capacity, and observe the rejection:
+
+::: listing scratch/rate_demo.py | Listing 13.6a — Draining the token bucket on purpose
+import asyncio
+
+from pyfly.kernel.exceptions import RateLimitException
+from pyfly.resilience import RateLimiter, rate_limiter
+
+# 3 tokens, refilling slowly so the burst is what we observe.
+limiter = RateLimiter(max_tokens=3, refill_rate=1.0)
+
+
+@rate_limiter(limiter)
+async def ping(n: int) -> str:
+ return f"ok-{n}"
+
+
+async def main() -> None:
+ for n in range(5):
+ try:
+ print(await ping(n))
+ except RateLimitException:
+ print(f"rejected-{n}")
+
+
+asyncio.run(main())
+:::
+
+Run it directly:
+
+```console
+$ uv run python scratch/rate_demo.py
+ok-0
+ok-1
+ok-2
+rejected-3
+rejected-4
+```
+
+The first three calls each spend a token; the fourth and fifth arrive with an
+empty bucket and are rejected immediately with `RateLimitException` — no
+queuing, no waiting. Slow the loop down (or raise `refill_rate`) and the
+rejections disappear because tokens refill between calls.
+
+**What just happened.** You did not change the function `ping` at all — you
+decorated it. The decorator inserted an `await limiter.acquire()` before every
+call, and `acquire()` raised when the bucket was empty. This is the shape every
+resilience tool in this chapter takes: a decorator that guards the call without
+the function body knowing it exists.
+
Multiple functions sharing one `RateLimiter` instance enforce a *global*
rate across all of them — useful for capping total traffic to a downstream
service regardless of which internal method initiates the call.
### Bulkhead — concurrency isolation
+!!! note "New term: bulkhead"
+ The name comes from shipbuilding: a ship's hull is divided into sealed
+ compartments (*bulkheads*) so that a breach in one does not flood the whole
+ vessel. A software bulkhead caps how many calls to one dependency can run at
+ once, so a flood of slow calls to `AccountService` cannot consume every
+ coroutine and sink unrelated requests.
+
`Bulkhead` is a semaphore: it limits the number of calls *in-flight at the
same time*. Calls beyond `max_concurrent` are rejected immediately with
`BulkheadException`.
@@ -647,6 +867,13 @@ when many instances restart simultaneously.
### @circuit_breaker — fast failure under sustained outage
+!!! note "New term: circuit breaker"
+ Borrowed from electrical wiring: a circuit breaker *trips* (opens) when too
+ much current flows, cutting the circuit before the wiring overheats. A
+ software circuit breaker trips after too many failures, cutting off calls to
+ a failing dependency so you stop hammering it — and so your own callers fail
+ fast instead of waiting on calls that are doomed to error anyway.
+
Retrying a genuinely unavailable service amplifies load at exactly the
moment that service most needs relief. The circuit-breaker pattern solves
this: after a threshold of consecutive failures the circuit **opens** and
@@ -712,6 +939,94 @@ calls fail.
!!! spring "Spring parity"
`@retry` mirrors Spring Retry's `@Retryable` (with `maxAttempts`, `backoff`, `include`). `CircuitBreaker` mirrors Resilience4j's `CircuitBreaker` (failure threshold, recovery timeout, CLOSED/OPEN/HALF_OPEN state machine, half-open probe calls, expected-exception filter). PyFly does not use the Resilience4j Java library — it is a pure-Python re-implementation with the same semantics.
+### Configuring resilience from `pyfly.yaml`
+
+So far you have constructed every `RateLimiter`, `Bulkhead`, and
+`CircuitBreaker` in code. That is perfect for a single gateway, but operations
+teams usually want to tune these thresholds *without a code change* — bump a
+timeout, widen a rate limit — and they want one obvious place to read the
+current settings. PyFly v26.6.110 ships a config-driven **`ResilienceRegistry`**
+for exactly this, giving parity with Resilience4j's named-registry model.
+
+**Step 1 — Declare named instances in `pyfly.yaml`.** Each entry under
+`pyfly.resilience.*` becomes a named instance. Names are yours to choose;
+group them by the downstream they protect:
+
+```yaml
+pyfly:
+ resilience:
+ circuit-breaker:
+ account-api:
+ failure-threshold: 5
+ recovery-timeout: 30s
+ # or switch to windowed-rate mode:
+ # failure-rate-threshold: 0.5
+ # window-size: 10
+ rate-limiter:
+ account-api:
+ max-tokens: 50
+ refill-rate: 20.0
+ bulkhead:
+ account-api:
+ max-concurrent: 8
+ time-limiter:
+ account-api:
+ timeout: 2s
+```
+
+Durations accept friendly suffixes — `30s`, `500ms`, `1m`, `2h` — or a bare
+number read as seconds. Keys use kebab-case (`failure-threshold`); PyFly's
+relaxed binding accepts snake_case too.
+
+**Step 2 — Inject the registry and look instances up by name.** PyFly's
+`ResilienceAutoConfiguration` registers a single `ResilienceRegistry` bean
+built from those keys (it is always on, and returns an empty registry when no
+keys are present). Ask for it in any `@service` constructor:
+
+::: listing lumen/account/gateway_configured.py | Listing 13.12a — Pulling resilience instances from the registry
+from pyfly.container import service
+from pyfly.resilience import (
+ ResilienceRegistry,
+ bulkhead,
+ circuit_breaker,
+ rate_limiter,
+)
+
+
+@service
+class AccountGateway:
+
+ def __init__(self, http_client, registry: ResilienceRegistry) -> None:
+ self._http = http_client
+ # Look up the named instances declared in pyfly.yaml.
+ cb = registry.circuit_breaker("account-api")
+ rl = registry.rate_limiter("account-api")
+ bh = registry.bulkhead("account-api")
+
+ # Wrap the real call with the config-driven instances.
+ guarded = circuit_breaker(cb)(self._raw_get)
+ guarded = bulkhead(bh)(guarded)
+ self.get_account = rate_limiter(rl)(guarded)
+
+ async def _raw_get(self, account_id: str) -> dict:
+ resp = await self._http.get(f"/accounts/{account_id}")
+ return resp.json()
+:::
+
+**What just happened.** The thresholds now live in configuration, not in
+Python literals. A `CircuitBreaker` named `account-api` is materialised once at
+startup and shared by everything that looks it up — so the failure counts and
+OPEN/CLOSED state are *global* across all callers of that name, exactly like a
+shared in-code instance. Looking up an unknown name raises `KeyError` with the
+list of available names, so a typo fails loudly at startup rather than silently
+creating an unprotected path.
+
+!!! tip "Time limiter returns a timedelta"
+ `registry.time_limiter("account-api")` returns the configured **`timedelta`**, not a decorator — feed it straight into `time_limiter(timeout=registry.time_limiter("account-api"))`. The other three accessors (`circuit_breaker`, `rate_limiter`, `bulkhead`) return the instance you pass to the matching decorator.
+
+!!! spring "Spring parity"
+ The `ResilienceRegistry` mirrors Resilience4j's `CircuitBreakerRegistry`, `RateLimiterRegistry`, and `BulkheadRegistry` — named instances declared in configuration and looked up at runtime. Spring Boot's `resilience4j.circuitbreaker.instances..*` becomes `pyfly.resilience.circuit-breaker..*`; the property names line up one-for-one.
+
---
## Composing the layers
@@ -845,6 +1160,59 @@ Note that `@cacheable` sits *above* `@fallback`. That means:
`@fallback`, or use the `unless` predicate:
`unless=lambda r: r.get("status") == "degraded"`.
+#### Run it — make the downstream fail and watch the stack degrade
+
+You do not need a live `AccountService` to verify the stack. Wire the
+resilience layers around a stub HTTP client that always raises, and assert
+that the caller still gets a usable `DEGRADED` response instead of an
+exception:
+
+::: listing tests/resilience/test_gateway_stack.py | Listing 13.13a — The stack degrades instead of throwing
+import pytest
+
+from pyfly.resilience import fallback, retry
+
+DEGRADED = {"status": "degraded", "balance_minor": None}
+
+
+class _BrokenClient:
+ async def get(self, path: str) -> dict:
+ raise IOError("AccountService unreachable")
+
+
+@fallback(fallback_value=DEGRADED, on=(IOError,))
+@retry(max_attempts=2, delay=0.0, exceptions=(IOError,))
+async def get_account(client: _BrokenClient, account_id: str) -> dict:
+ resp = await client.get(f"/accounts/{account_id}")
+ return resp
+
+
+@pytest.mark.asyncio
+async def test_degrades_instead_of_raising() -> None:
+ result = await get_account(_BrokenClient(), "acc-1")
+ assert result == DEGRADED
+:::
+
+Run it:
+
+```console
+$ uv run --extra dev pytest tests/resilience/test_gateway_stack.py -q
+. [100%]
+1 passed in 0.05s
+```
+
+`@retry` tried the call twice, both attempts raised `IOError`, and `@fallback`
+caught the final exception and returned `DEGRADED`. The caller never saw the
+error — exactly the behaviour you want when `AccountService` is having a bad
+day.
+
+**What just happened.** You assembled a slice of the full stack — retry on the
+inside, fallback on the outside — and proved that a hard failure surfaces as a
+degraded-but-valid response. Add `@rate_limiter`, `@bulkhead`,
+`@time_limiter`, and `@circuit_breaker` between them in the order shown above
+and each one folds into the same flow: every exception they raise is caught by
+the outer `@fallback`, so the caller always receives a response it can use.
+
---
## What you built {.recap}
@@ -890,6 +1258,11 @@ Concretely, you learned:
arguments — and opens the circuit after a failure threshold, short-
circuiting subsequent calls during the recovery window so the downstream
has time to recover.
+- **`ResilienceRegistry`** (PyFly v26.6.110) materialises named
+ `CircuitBreaker`, `RateLimiter`, `Bulkhead`, and time-limiter instances from
+ `pyfly.resilience.*` config keys, so operations can tune thresholds in
+ `pyfly.yaml` and inject the registry to look instances up by name — Spring
+ Boot's `resilience4j.*.instances..*` parity.
- **Decorator order** matters: fallback outermost, then rate limiter,
bulkhead, time limiter, circuit breaker, and retry innermost — with caching
above the fallback to cache even degraded responses.
@@ -905,6 +1278,8 @@ production.
**Exercise 1 — Conditional caching.** The `GetBalance` handler is called far more often for active wallets than for test wallets. Add `condition=lambda query: not query.wallet_id.startswith("test-")` to the `cacheable(...)` call inside `GetBalanceHandler.__init__` and verify with a unit test using `InMemoryCache` that queries for test wallet ids always reach the repository.
-**Exercise 2 — Circuit breaker with rate-based threshold.** Replace the consecutive-count circuit breaker in `AccountGateway` with a rate-based one: open the circuit when more than 60% of the last 20 calls fail. Construct `CircuitBreaker(failure_rate_threshold=0.6, window_size=20, recovery_timeout=60.0, expected=(IOError, TimeoutError))` and write a test that fires 12 failing calls followed by 8 successful ones, asserting that the circuit opens after the 13th failure (crossing 60% of 20).
+**Exercise 2 — Circuit breaker with rate-based threshold.** Replace the consecutive-count circuit breaker in `AccountGateway` with a rate-based one: open the circuit when at least 60% of the last 20 calls fail. Construct `CircuitBreaker(failure_rate_threshold=0.6, window_size=20, recovery_timeout=60.0, expected=(IOError, TimeoutError))`. Two subtleties drive the test design. First, in rate mode the breaker stays not-tripped until the window is *full* — it requires a complete 20-call window before judging the rate — so a burst of failures alone never opens it. Second, the breaker only re-evaluates its trip condition on a *failure* (a success never opens it), so the call that crosses the threshold must itself be a failing call. Write a test that fires 8 succeeding calls followed by 12 failing ones (20 calls total = one full window, ending on a failure). Assert that the circuit stays `CLOSED` through call 19 (the window is still partial), then `OPENS` on the 20th call, when the window fills and the failure rate reaches exactly 12 / 20 = 0.60.
**Exercise 3 — Evict by prefix.** Lumen sometimes needs to invalidate all cache entries for a given wallet owner (GDPR deletion). Add a `purge_owner(owner_id: str)` method to a wallet admin service that calls `backend.evict_by_prefix(f"wallet:balance:{owner_id}:")` directly (without a decorator), and write a test that pre-populates three wallet keys for one owner and one for another, calls `purge_owner`, and asserts that only the target owner's entries are gone.
+
+**Exercise 4 — Config-driven resilience.** Move `AccountGateway`'s hard-coded thresholds into `pyfly.yaml` under `pyfly.resilience.circuit-breaker.account-api`, `pyfly.resilience.rate-limiter.account-api`, and `pyfly.resilience.bulkhead.account-api`. Inject `ResilienceRegistry` into the gateway, look the three instances up by name, and write a test that asserts the materialised `CircuitBreaker.failure_threshold` matches the value you set in config. Note that `ResilienceRegistry.from_config(...)` expects a pyfly `Config`, not a plain dict — it calls `config.get_section("pyfly.resilience.circuit-breaker")` internally. Build one in the test from a nested dict, e.g. `Config({"pyfly": {"resilience": {"circuit-breaker": {"account-api": {"failure-threshold": 5}}}}})` (import `from pyfly.core.config import Config`), then pass that `Config` to `from_config`. Confirm that looking up a misspelled name raises `KeyError` with the list of available names.
diff --git a/book/manuscript/14-security.md b/book/manuscript/14-security.md
index a805ef2c..a46973cd 100644
--- a/book/manuscript/14-security.md
+++ b/book/manuscript/14-security.md
@@ -16,6 +16,15 @@ This chapter locks Lumen down. You will:
If you have worked with Spring Security before, the shape will feel familiar: configure a filter chain, annotate individual methods, and swap the user-detail source for an IDP. PyFly calls those pieces `SecurityMiddleware + HttpSecurity`, `@secure`, and `IdpAdapter`, but the concepts map one-to-one.
+This chapter is written as a guided tutorial. We build the security layer one piece at a time — issue a token, validate it, guard a handler, hash a password, store a session, federate to an IDP — and after each piece you will find a **Run it** checkpoint with the exact command to type and the output you should expect. If you have never wired authentication into a web service before, that is fine: each new term is glossed in plain language the first time it appears, and you can follow along by editing the Lumen sample as you read.
+
+!!! note "Version"
+ The listings and config keys in this chapter target PyFly **v26.6.110**.
+ If you are on an earlier release, a few property names differ — most notably
+ the application port is now `pyfly.server.port` (Spring's `server.port`),
+ and the actuator and admin dashboard live on a separate management port,
+ `pyfly.management.server.port` (default `9090`).
+
::: figure art/figures/14-security.svg | Figure 14.1 — Lumen's security layers. A JWT filter populates the SecurityContext; HttpSecurity enforces URL-level rules; @secure enforces handler-level rules; the IDP port delegates identity to an external provider.
---
@@ -26,7 +35,7 @@ If you have worked with Spring Security before, the shape will feel familiar: co
Lumen is a stateless API. HTTP sessions would require sticky routing or a shared session store on every replica. JWT tokens let each service validate credentials independently — no shared state, no coordination, horizontal scaling by default.
-A **JWT** is a signed JSON payload. Lumen's auth service issues a token on login; every subsequent request carries that token in the `Authorization` header; `SecurityMiddleware` validates the signature and unpacks the token into a `SecurityContext` that the rest of the request can read.
+A **JWT** (JSON Web Token, pronounced "jot") is a signed JSON payload. Think of it as a tamper-evident badge: the server stamps a small JSON document — *who you are*, *what roles you hold*, *when it expires* — and signs it with a secret key. The badge travels with every request. Because the signature can only be produced by someone holding the secret, the server can trust the badge without looking anything up in a database. Lumen's auth service issues a token on login; every subsequent request carries that token in the `Authorization` header; `SecurityMiddleware` validates the signature and unpacks the token into a `SecurityContext` that the rest of the request can read.
### JWTService
@@ -101,6 +110,43 @@ def _permissions_for(role: str) -> list[str]:
**How it works.** `login` fetches the user record and calls `BcryptPasswordEncoder.verify` to compare the supplied password against the stored hash. On success it calls `jwt.encode`, which auto-appends an `exp` claim `expiration_seconds` seconds from now (default `3600` — one hour). You never import `datetime`: the service computes the Unix-timestamp expiry as `int(time.time()) + expiration_seconds`. The caller receives a compact, self-contained token string.
+Walking through the `login` method one step at a time:
+
+**Step 1 — Look up the user.** `find_by_username` returns the stored user record, or `None` if no such username exists. We will treat both "no such user" and "wrong password" as the same failure so an attacker cannot tell which usernames are registered.
+
+**Step 2 — Verify the password.** `self._encoder.verify(password, user.password_hash)` re-hashes the supplied password with the salt baked into the stored hash and compares the two in constant time. If the user was not found, or the passwords do not match, raise `UnauthorizedException` — PyFly renders this as a `401` with the machine-readable code `INVALID_CREDENTIALS`.
+
+**Step 3 — Build the claims.** On success, assemble the JSON payload that will become the token's body: `sub` (the subject — the user's id), `roles`, and the `permissions` that role grants.
+
+**Step 4 — Sign and return.** `self._jwt.encode({...})` signs the payload with the configured secret, stamps the mandatory `exp` claim, and returns the compact token string. That string is what the client stores and replays on every later request.
+
+!!! note "Jargon: claim"
+ A *claim* is just one key/value statement inside the token's JSON body —
+ `"sub": "42"` claims the subject is user 42. The token carries a bag of
+ claims; the framework copies the security-relevant ones (`sub`, `roles`,
+ `permissions`) into the `SecurityContext`.
+
+!!! tip "Run it — issue a token in the REPL"
+ You do not need a running server to see `JWTService` work. With Lumen's
+ virtual environment active, open a Python REPL and sign a payload:
+
+ ```python
+ >>> from pyfly.security import JWTService
+ >>> jwt = JWTService(secret="dev-secret-change-me", algorithm="HS256")
+ >>> token = jwt.encode({"sub": "42", "roles": ["USER"]})
+ >>> token[:20] # a compact "header.payload.signature" string
+ 'eyJhbGciOiJIUzI1NiIs'
+ >>> ctx = jwt.to_security_context(token)
+ >>> ctx.user_id, ctx.roles
+ ('42', ['USER'])
+ ```
+
+ The token round-trips: `encode` added the `exp` claim for you, and
+ `to_security_context` validated the signature and unpacked the claims into a
+ `SecurityContext`. Try tampering with a character in the middle of the
+ string and calling `jwt.decode(token)` again — you will get a
+ `SecurityException`, because the signature no longer matches the payload.
+
### The SecurityContext
**`SecurityContext`** is a frozen dataclass that carries authentication and authorisation data for a single request. The middleware creates it from the validated token; your handlers receive it as an injected parameter.
@@ -160,6 +206,15 @@ def build_app(context):
**How it works.** `exclude_paths` lists the paths where no token is expected. Login and register cannot require authentication because the token does not exist yet; docs paths are excluded so the API explorer works without credentials. Every other path goes through token validation.
+!!! note "Jargon: middleware"
+ *Middleware* is code that wraps every request, running before the route
+ handler on the way in and after it on the way out. `SecurityMiddleware`
+ uses the "in" pass to read the token and stash a `SecurityContext` on
+ `request.state` so handlers downstream can read it without re-parsing the
+ header.
+
+**What just happened.** You now have the two halves of authentication wired up. `AuthService.login` *mints* a token after checking the password; `SecurityMiddleware` *reads* that token on every later request and turns it into a `SecurityContext`. Crucially, the middleware is permissive — it never returns a `401`. A request with a bad or missing token simply arrives anonymous, and the decision to allow or reject it is deferred to the next two layers you will build: `HttpSecurity` (broad, URL-level) and `@secure` (precise, per-handler). Separating *who you are* (authentication) from *what you may do* (authorization) is what keeps each layer small and testable.
+
### URL-level rules with HttpSecurity
`@secure` guards individual handler methods. **`HttpSecurity`** guards whole URL subtrees at the filter layer — before the route dispatcher runs. The two are complementary: `HttpSecurity` provides fast, broad policy at the edge; `@secure` adds fine-grained, per-handler enforcement behind it.
@@ -173,7 +228,7 @@ from pyfly.security.http_security import HttpSecurity
class SecurityConfig:
@bean
- def http_security_filter(self):
+ def http_security(self) -> HttpSecurity:
hs = HttpSecurity()
hs.authorize_requests() \
.request_matchers("/idp/admin/**").has_role("ADMIN") \
@@ -183,13 +238,56 @@ class SecurityConfig:
"/idp/login", "/idp/refresh",
).permit_all() \
.any_request().permit_all()
- return hs.build()
+ return hs
:::
:::
**How it works.** Rules are evaluated in declaration order — first match wins. The `HttpSecurityFilter` runs at `HIGHEST_PRECEDENCE + 350`, after authentication filters have populated `request.state.security_context`, so every role and permission check has a fully hydrated context to inspect. The terminal methods — `has_role`, `has_any_role`, `has_permission`, `authenticated`, `permit_all`, and `deny_all` — cover every common policy; unsatisfied rules return RFC 7807 problem-detail JSON (`application/problem+json`) with the appropriate HTTP status.
+Read the DSL chain top to bottom — that is exactly the order the filter evaluates it:
+
+**Step 1 — Open the rule list.** `hs.authorize_requests()` starts the fluent builder. Every `.request_matchers(...)` call that follows registers one rule.
+
+**Step 2 — Lock down the admin subtree.** `.request_matchers("/idp/admin/**").has_role("ADMIN")` requires the `ADMIN` role for anything under `/idp/admin`. The `**` glob matches any depth of path segments.
+
+**Step 3 — Require login for wallets.** `.request_matchers("/api/v1/wallets/**").authenticated()` accepts any logged-in caller, regardless of role, for the wallet tree. Finer per-handler rules come later via `@secure`.
+
+**Step 4 — Allow the public paths.** `.request_matchers("/health", "/docs", ...).permit_all()` lets health checks, the docs explorer, and the IDP login/refresh endpoints through with no token.
+
+**Step 5 — Set the default.** `.any_request().permit_all()` is the catch-all for paths no earlier rule matched. Flip it to `.deny_all()` once every route is explicitly accounted for — "deny by default" is the safer production posture.
+
+**Step 6 — Return the builder.** Return the configured `HttpSecurity` itself — do **not** call `hs.build()` here. Because `SecurityConfig` is a `@configuration` class, auto-configuration's `HttpSecurityFilterAutoConfiguration` (active whenever an `HttpSecurity` bean is present) picks up the `HttpSecurity` bean, calls `.build()` for you, and registers the resulting `HttpSecurityFilter` on the chain.
+
+!!! tip "Run it — see the gate accept and reject"
+ Start the app with `uv run pyfly run` (it serves on `pyfly.server.port`,
+ default `8080`). In another terminal, hit a guarded path without a token:
+
+ ```bash
+ curl -i http://localhost:8080/api/v1/wallets
+ ```
+
+ Expected — the gate rejects the anonymous request with an RFC 7807 body:
+
+ ```text
+ HTTP/1.1 401 Unauthorized
+ content-type: application/problem+json
+
+ {"type":"about:blank","title":"Unauthorized","status":401,
+ "detail":"Authentication is required to access this resource.",
+ "instance":"/api/v1/wallets"}
+ ```
+
+ Now replay it with a token (use the `$TOKEN` you minted in the REPL above,
+ or one from `/idp/login`):
+
+ ```bash
+ curl -i -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/v1/wallets
+ ```
+
+ Expected — `HTTP/1.1 200 OK` and a JSON page of wallets. The same URL,
+ two outcomes, decided entirely by the token: that is the gate doing its job.
+
!!! note "Two-layer defense"
`HttpSecurity` provides fast URL-level policy before routes are even
dispatched — good for blanket rules like "everything under `/api/v1/wallets`
@@ -197,7 +295,7 @@ class SecurityConfig:
the second, finer-grained layer. Use both together for defense in depth.
!!! spring "Spring parity"
- `HttpSecurity` mirrors Spring Security's `HttpSecurity.authorizeHttpRequests()` chain. `request_matchers` corresponds to `requestMatchers`, `authenticated()` to `.authenticated()`, `has_role` to `hasRole`, and `build()` triggers registration of the underlying filter just as `build()` finalises the Spring filter chain. The fnmatch glob patterns (`/api/admin/**`) behave identically to Spring's Ant-style path matching.
+ `HttpSecurity` mirrors Spring Security's `HttpSecurity.authorizeHttpRequests()` chain. `request_matchers` corresponds to `requestMatchers`, `authenticated()` to `.authenticated()`, `has_role` to `hasRole`, and the `build()` that auto-configuration calls on your `HttpSecurity` bean finalises the underlying filter just as `build()` finalises the Spring filter chain. The fnmatch glob patterns (`/api/admin/**`) behave identically to Spring's Ant-style path matching.
---
@@ -214,9 +312,9 @@ pyfly:
algorithm: HS256
filter:
enabled: true
- exclude-patterns: >-
- /docs,/openapi.json,/actuator/health,
- /api/auth/login,/api/auth/register
+ exclude-patterns: >-
+ /docs,/openapi.json,
+ /api/auth/login,/api/auth/register
password:
bcrypt-rounds: 12
@@ -231,11 +329,51 @@ pyfly:
| `pyfly.security.jwt.exclude-patterns` | *(absent)* | Comma-separated paths to skip |
| `pyfly.security.password.bcrypt-rounds` | `12` | Bcrypt cost factor |
+Note where each key lives: `filter.enabled` is nested under `jwt.filter`, but `exclude-patterns` sits one level up, directly under `jwt` — that is the key the auto-configuration reads (`pyfly.security.jwt.exclude-patterns`). There is no `/actuator/health` in the exclude list any more: as of v26.6.110 the actuator and admin dashboard run on a **separate management port** (`pyfly.management.server.port`, default `9090`), so they never pass through the application's JWT filter at all.
+
!!! warning "Production secret"
Never commit the real JWT secret to source control. Use `${JWT_SECRET}` and
inject the value from an environment variable or a secrets manager at
deploy time.
+!!! warning "The management port is open by default"
+ For Spring parity, the management server (`/actuator/*` and the admin
+ dashboard, default port `9090`) is **unauthenticated by default** — it does
+ not share the application's security gate. In any non-local deployment,
+ secure it explicitly:
+
+ ```yaml
+ pyfly:
+ management:
+ security:
+ enabled: true # apply the security gate to the management port
+ ```
+
+ Setting `pyfly.management.server.port: -1` disables the management endpoints
+ entirely. The default actuator HTTP exposure is just `health,info`; widen it
+ with `pyfly.management.endpoints.web.exposure.include`.
+
+!!! tip "Run it — confirm auto-wiring on startup"
+ With the keys above in `pyfly.yaml`, start the app and watch the boot log:
+
+ ```bash
+ uv run pyfly run
+ ```
+
+ Expected — you will see the app bind to `:8080` and the management server to
+ `:9090`, and the security beans appear with no `@configuration` code of your
+ own. A quick proof that the encoder bean exists:
+
+ ```bash
+ curl -s http://localhost:8080/api/auth/login \
+ -d '{"username":"alice","password":"hunter2"}' \
+ -H 'content-type: application/json'
+ ```
+
+ Expected — a JSON body containing an `access_token` (or a `401` with
+ `INVALID_CREDENTIALS` if the credentials are wrong). Either way, the
+ `JWTService` and `BcryptPasswordEncoder` beans were wired automatically.
+
---
## Authorization with @secure
@@ -457,6 +595,43 @@ alphabetically before `wallet_balance` / `wallet_detail`, so the framework
registers the literal `""` and `/rich` routes first — ensuring Starlette
resolves `/api/v1/wallets/rich` as a fixed segment rather than as a wallet id.
+To add `@secure` to one handler, the recipe is always the same three steps:
+
+**Step 1 — Add the parameter.** Give the method a `security_context: SecurityContext` keyword parameter. (For the `GET` list handlers that already have defaulted query params, default it to `None` so the parameter order stays valid: `security_context: SecurityContext = None`.)
+
+**Step 2 — Stack the decorator.** Put `@secure(...)` *above* `@get_mapping` / `@post_mapping`. Order matters: the authorization check must run before the route binding does.
+
+**Step 3 — Choose the minimal guard.** Pick the least-privilege rule that still lets the right users through — `roles=["USER", "ADMIN"]` for ordinary reads, an extra `permissions=["wallet:deposit"]` for money-moving writes, `roles=["ADMIN"]` for the full detail view.
+
+!!! tip "Run it — watch a 403 for the wrong role"
+ `wallet_detail` is `ADMIN`-only. Call it with a `USER` token (the
+ authentication succeeds, but authorization fails):
+
+ ```bash
+ curl -i -H "Authorization: Bearer $USER_TOKEN" \
+ http://localhost:8080/api/v1/wallets/abc-123
+ ```
+
+ Expected — the request clears the gate (it *is* authenticated) but
+ `@secure(roles=["ADMIN"])` rejects it. The exception handler renders a
+ problem body that includes the machine-readable `code`:
+
+ ```text
+ HTTP/1.1 403 Forbidden
+ content-type: application/problem+json
+
+ {"type":"about:blank","title":"Forbidden","status":403,
+ "detail":"Insufficient roles: requires one of ['ADMIN']",
+ "code":"FORBIDDEN"}
+ ```
+
+ Note the difference from the gate's `401` earlier: a missing or invalid
+ token at the gate gives `401` ("I don't know who you are"), while a valid
+ token without the required role gives `403 FORBIDDEN` ("I know who you are,
+ and you may not do this"). The same `USER` token *would* succeed against
+ `GET /api/v1/wallets/abc-123/balance`, which is guarded with
+ `roles=["USER", "ADMIN"]`.
+
!!! note "Amounts in minor units"
`DepositRequest.amount` is an `int` in **minor units** (cents). €10.50 is
`1050`. This convention avoids floating-point rounding errors throughout
@@ -766,6 +941,155 @@ class SessionConfig:
---
+## Validating tokens from an external IdP (OAuth2 resource server)
+
+So far Lumen has *minted its own tokens* with `JWTService` and a shared HMAC
+secret. That is perfect for a self-contained service. But in most real-world
+deployments, the tokens are issued by a dedicated identity provider — Keycloak, Microsoft
+Entra ID (formerly Azure AD), or AWS Cognito — and your service's only job is to
+**validate** them. This is the **OAuth2 resource server** role, and as of
+v26.6.110 PyFly gives it to you with config alone: no code, and the same one
+configuration works across all three providers.
+
+!!! note "Jargon: resource server"
+ In OAuth2 terms, the IdP that issues tokens is the *authorization server*;
+ your API, which holds the data callers want and checks their tokens, is the
+ *resource server*. Lumen is a resource server. It never sees the user's
+ password — it only verifies the badge the IdP already signed.
+
+The difference from `JWTService` is the **signing scheme**. Your own tokens are
+signed with a symmetric secret (`HS256`) — the same key both signs and verifies,
+so only services that hold the secret can validate. IdP tokens are signed
+*asymmetrically* (`RS256`): the IdP keeps a private key and publishes the
+matching public keys at a **JWKS** endpoint (JSON Web Key Set). Your resource
+server downloads those public keys, caches them, and uses them to verify every
+token's signature — it never needs the IdP's secret at all.
+
+### Turning it on
+
+`JWKSTokenValidator` does the work, and `OAuth2ResourceServerAutoConfiguration`
+wires it from `pyfly.security.oauth2.resource-server.*`. Here is the full
+Keycloak setup:
+
+::: listing lumen/resources/pyfly.yaml | Listing 14.11 — Multi-IdP OAuth2 resource server (Keycloak)
+pyfly:
+ security:
+ oauth2:
+ resource-server:
+ enabled: true
+ # Either point at the JWKS endpoint directly...
+ jwks-uri: "https://keycloak.example.com/realms/lumen/protocol/openid-connect/certs"
+ # ...or give an issuer-uri and let OIDC discovery find jwks-uri + issuer:
+ # issuer-uri: "https://keycloak.example.com/realms/lumen"
+ issuer: "https://keycloak.example.com/realms/lumen"
+ audiences: "lumen-backend"
+ validate-audience: true
+ algorithms: "RS256"
+ clock-skew-seconds: 60
+ exclude-patterns: "/idp/login,/idp/refresh,/docs,/openapi.json"
+
+:::
+:::
+
+Step by step:
+
+**Step 1 — Enable it.** `enabled: true` activates `OAuth2ResourceServerAutoConfiguration` (PyJWT must be installed). That registers a `JWKSTokenValidator` bean and the bearer-token filter on the application's chain.
+
+**Step 2 — Point at the keys.** Set `jwks-uri` directly, or set `issuer-uri` and let PyFly fetch `/.well-known/openid-configuration` to discover both the `jwks-uri` and the authoritative `issuer` — exactly like Spring's `issuer-uri`.
+
+**Step 3 — Pin the audience and issuer.** `audiences` lists the values the token's `aud` claim must match (any one). `issuer` (when set) is checked against the token's `iss`. Together they ensure a token minted for a *different* application or realm cannot be replayed against Lumen.
+
+**Step 4 — Leave the defaults alone for claim mapping.** You did not configure where roles live, yet it just works for Keycloak, Entra, and Cognito. That is the job of `ClaimMappings`, covered next.
+
+### How claims become a SecurityContext
+
+Every IdP puts roles and scopes in different places. Keycloak nests realm roles under `realm_access.roles` and per-client roles under `resource_access..roles`; Entra uses a flat `roles` array (or `groups`); Cognito uses `cognito:groups`. `ClaimMappings` reconciles them with a small path language, so `has_role(...)` and `has_permission(...)` work the same regardless of provider.
+
+| Mapping field | Default search order | Becomes |
+|---|---|---|
+| `principal_claims` | `oid`, `sub` | `SecurityContext.user_id` |
+| `authority_claims` | `roles`, `scopes`, `authorities`, `realm_access.roles`, `resource_access.*.roles`, `groups`, `cognito:groups` | `SecurityContext.roles` |
+| `scope_claims` | `scp`, `scope` (space-split) | `SecurityContext.permissions` |
+| `attribute_claims` | *(none)* | `SecurityContext.attributes` |
+
+Two rules make the defaults span every provider:
+
+- **Dotted paths** descend into nested objects: `realm_access.roles` reads `payload["realm_access"]["roles"]`.
+- A single-level **`*` wildcard** iterates every key at that level: `resource_access.*.roles` collects the `roles` array from *every* client entry under `resource_access`. Path segments split on `.` only, so a colon-bearing claim name like `cognito:groups` is matched verbatim.
+
+Roles are collected across *all* matching paths and de-duplicated, so a Keycloak token contributes both its realm roles and its client roles into one flat `roles` list.
+
+!!! note "Jargon: JWKS and kid"
+ A *JWKS* is the IdP's public-key directory. Each key carries a `kid` (key
+ id); each token's header names the `kid` it was signed with. The validator
+ looks up that exact key, caches the set (default 300s), and rotates
+ automatically when the IdP publishes new keys — no redeploy needed.
+
+If the built-in defaults do not match your IdP, override only what differs:
+
+::: listing lumen/resources/pyfly.yaml | Listing 14.12 — Tuning claim mapping for Entra ID and Cognito
+pyfly:
+ security:
+ oauth2:
+ resource-server:
+ enabled: true
+ # Microsoft Entra ID (v2.0):
+ issuer-uri: "https://login.microsoftonline.com//v2.0"
+ audiences: "api://lumen-backend"
+ principal-claim-names: "oid,sub" # Entra's stable user id first
+ authorities-claim-names: "roles,groups"
+ scope-claim-names: "scp" # Entra delegated scopes
+ attribute-claims: "tid,preferred_username"
+ # AWS Cognito access tokens carry no 'aud' — disable audience checks:
+ # validate-audience: false
+ # authorities-claim-names: "cognito:groups"
+
+:::
+:::
+
+**Step 5 (when needed) — Cognito has no `aud`.** Cognito *access* tokens carry `client_id` instead of `aud`, so set `validate-audience: false` for them; the signature, `iss`, and `exp` checks still apply.
+
+!!! tip "Run it — accept a real IdP token, reject a forged one"
+ With the resource server enabled, replay a token your IdP issued against a
+ guarded route:
+
+ ```bash
+ curl -i -H "Authorization: Bearer $KEYCLOAK_TOKEN" \
+ http://localhost:8080/api/v1/wallets
+ ```
+
+ Expected — `HTTP/1.1 200 OK`. The filter fetched the JWKS, matched the
+ token's `kid`, verified the `RS256` signature, the `iss`, the `aud`, and the
+ `exp` (with 60s of clock-skew tolerance), then built a `SecurityContext`
+ from the token's claims.
+
+ Now flip one character in the token and retry. Expected — `HTTP/1.1 401`
+ (or an anonymous context that the gate then rejects), because the signature
+ no longer matches any published key. You did not write or deploy a single
+ line of validation code to get either outcome.
+
+**What just happened.** You added a production-grade, multi-IdP token validator with configuration only. `JWKSTokenValidator` verifies the signature against the IdP's published keys (so the secret never leaves the IdP), checks `iss` / `aud` / `exp`, and maps provider-specific claims into the same `SecurityContext` the rest of the chapter already uses. Your `@secure` decorators and `HttpSecurity` rules do not change at all — they read `roles` and `permissions` exactly as before, whether the token came from Lumen's own `JWTService` or from Keycloak.
+
+!!! warning "error mode: anonymous vs 401"
+ By default (`authenticate-error-mode: anonymous`) a *present but invalid*
+ token yields an anonymous context and the request continues to the
+ `HttpSecurity` gate, which decides. Set `authenticate-error-mode: "401"` to
+ reject an invalid token right at the filter with
+ `WWW-Authenticate: Bearer error="invalid_token"` (RFC 6750). A *missing*
+ token always falls through to the gate either way.
+
+!!! spring "Spring parity"
+ This is PyFly's `spring-boot-starter-oauth2-resource-server`. The
+ `resource-server.issuer-uri` / `jwks-uri` keys mirror
+ `spring.security.oauth2.resourceserver.jwt.*`; OIDC discovery, the accepted
+ `audiences` list, configurable `algorithms`, and the 60-second clock-skew
+ default all match Spring Security's `JwtDecoder` and `JwtTimestampValidator`.
+ `ClaimMappings` is the equivalent of a custom
+ `JwtAuthenticationConverter` / `JwtGrantedAuthoritiesConverter`, but
+ expressed declaratively in YAML.
+
+---
+
## External identity (IDP)
### The problem with managing identity in-house
@@ -835,7 +1159,7 @@ Key DTOs:
### Keycloak adapter
-::: listing lumen/config/idp_config.py | Listing 14.11 — Wiring the Keycloak adapter
+::: listing lumen/config/idp_config.py | Listing 14.13 — Wiring the Keycloak adapter
from pyfly.container import bean, configuration
from pyfly.idp import IdpAdapter, KeycloakIdpAdapter
@@ -860,7 +1184,7 @@ class IdpConfig:
### Using the IDP in a service
-::: listing lumen/core/services/auth/idp_auth_service.py | Listing 14.12 — Using IdpAdapter in the auth service
+::: listing lumen/core/services/auth/idp_auth_service.py | Listing 14.14 — Using IdpAdapter in the auth service
from pyfly.container import service
from pyfly.idp import IdpAdapter, IdpUser, LoginRequest
from pyfly.kernel.exceptions import UnauthorizedException
@@ -926,7 +1250,7 @@ class IdpAuthService:
Enable the IDP subsystem in `pyfly.yaml` and PyFly wires the adapter and a ready-made REST controller automatically:
-::: listing lumen/resources/pyfly.yaml | Listing 14.13 — IDP auto-configuration
+::: listing lumen/resources/pyfly.yaml | Listing 14.15 — IDP auto-configuration
pyfly:
idp:
enabled: true
@@ -981,7 +1305,7 @@ When Starlette is present, `IdpAutoConfiguration` also registers an `IdpControll
The listing below shows the complete wiring: IDP adapter, JWT filter, URL-level rules, and a Redis session store for the admin dashboard.
-::: listing lumen/config/security_full.py | Listing 14.14 — Full security configuration
+::: listing lumen/config/security_full.py | Listing 14.16 — Full security configuration
from pyfly.container import bean, configuration
from pyfly.idp import IdpAdapter, KeycloakIdpAdapter
from pyfly.security.http_security import HttpSecurity
@@ -1000,7 +1324,7 @@ class LumenSecurityConfig:
)
@bean
- def http_security_filter(self):
+ def http_security(self) -> HttpSecurity:
hs = HttpSecurity()
hs.authorize_requests() \
.request_matchers(
@@ -1014,7 +1338,7 @@ class LumenSecurityConfig:
"/api/v1/wallets/**"
).authenticated() \
.any_request().permit_all()
- return hs.build()
+ return hs
:::
:::
@@ -1042,10 +1366,12 @@ This chapter opened Part V by closing Lumen's open front door. You:
(paged list), `list_rich_wallets` (filtered list), `wallet_balance`, and
`wallet_detail` — each carry the minimal guard: USER+ADMIN for most,
`wallet:deposit` permission for mutations, ADMIN-only for the full detail
- view. Authorization failures raise `SecurityException` (401, code
- `AUTH_REQUIRED`) for unauthenticated callers and `ForbiddenException` (403,
- code `FORBIDDEN`) for authenticated callers who lack the required role or
- permission.
+ view. When `@secure` rejects a call it raises `SecurityException` (code
+ `AUTH_REQUIRED`) for an unauthenticated caller or `ForbiddenException` (code
+ `FORBIDDEN`) for an authenticated caller who lacks the required role or
+ permission — both render as HTTP `403` through the exception handler. The
+ broader `HttpSecurity` gate, sitting in front of those handlers, is what
+ returns the bare `401` for a missing or invalid token.
- Hashed passwords with **`BcryptPasswordEncoder`**, the default adapter for the
`PasswordEncoder` protocol. The cost factor is tunable; the stored hash is
self-describing; verification is timing-safe.
@@ -1054,10 +1380,23 @@ This chapter opened Part V by closing Lumen's open front door. You:
no dependencies; in production, `RedisSessionStore` serialises to JSON and
lets Redis manage TTL. The `SessionFilter` rolls the cookie TTL on every
request and deletes it on invalidation.
+- Validated tokens issued by an external IdP with the config-driven
+ **OAuth2 resource server** (`JWKSTokenValidator`). One block of
+ `pyfly.security.oauth2.resource-server.*` config accepts Keycloak, Microsoft
+ Entra ID, and AWS Cognito tokens out of the box: it verifies the `RS256`
+ signature against the IdP's JWKS keys, checks `iss` / `aud` / `exp` with a
+ 60-second clock-skew, and maps each provider's roles, scopes, and principal
+ into the same `SecurityContext` via `ClaimMappings` — so `@secure` and
+ `HttpSecurity` stay unchanged.
- Delegated identity to an external provider via the **`IdpAdapter`** port and
the **`KeycloakIdpAdapter`** implementation. The auto-configured
`IdpController` exposes login, refresh, logout, introspect, and admin user
management under `/idp` with no extra code.
+- Learned that the actuator and admin dashboard run on a **separate management
+ port** (`pyfly.management.server.port`, default `9090`) that is
+ **unauthenticated by default** for Spring parity, and that you secure it with
+ `pyfly.management.security.enabled: true` (or disable it entirely with
+ port `-1`).
---
diff --git a/book/manuscript/15-observability.md b/book/manuscript/15-observability.md
index bf04c45a..4d16a3ec 100644
--- a/book/manuscript/15-observability.md
+++ b/book/manuscript/15-observability.md
@@ -18,6 +18,17 @@ This chapter adds eyes and ears to Lumen. The three pillars of observability ans
On top of those pillars sits the **Actuator** — production management endpoints that expose health, bean wiring, environment, and live logger levels — and the **Admin Dashboard**, an embedded browser UI that ties everything together in a single pane of glass.
+!!! note "New in v26.6.110"
+ Two changes in this release shape how you reach everything in this chapter.
+ First, the Actuator and Admin Dashboard now listen on a **separate
+ management port** — `9090` by default — rather than the application port
+ `8080`. Second, that management port is **open and unauthenticated by
+ default** (Spring Boot's `management.server.port` model), so you can curl
+ `http://localhost:9090/actuator/health` immediately, and you lock it down
+ with `pyfly.management.security.enabled: true` when you ship. We will point
+ out the right port at each step. If you have read older drafts that used
+ `http://localhost:8080/actuator/...`, swap the port to `9090`.
+
Finally, you will see how **Aspect-Oriented Programming** (AOP) applies logging and metrics to every service method declaratively, without touching the methods themselves.
By the end of the chapter Lumen will produce structured JSON logs with correlation IDs and automatic PII masking, emit Prometheus metrics scraped by any standard collector, propagate OpenTelemetry trace spans across service boundaries, answer Kubernetes liveness and readiness probes, and display all of the above in a zero-configuration dashboard reachable at `/admin`.
@@ -40,7 +51,18 @@ Searching for `ord-123` in Elasticsearch works — until the format changes. And
### get_logger
-PyFly exposes a single factory function that returns a structured logger backed by `structlog` (when the `observability` extra is installed) or a zero-dependency stdlib shim otherwise. Both accept the same call signature:
+PyFly exposes a single factory function that returns a structured logger backed by `structlog` (when the `observability` extra is installed) or a zero-dependency stdlib shim otherwise. Both accept the same call signature.
+
+!!! note "Jargon: factory function"
+ A *factory function* is just a function whose job is to build and hand back
+ a configured object. `get_logger("lumen.wallet")` does the wiring for you —
+ you never construct a logger by hand. The string you pass (`"lumen.wallet"`)
+ is the *logger name*; it is conventionally the dotted module path, and it is
+ what level overrides like `lumen.wallet: DEBUG` target.
+
+Let us build a tiny example you can run, then graduate to the real wallet code. Follow these steps.
+
+**Step 1 — Create a throwaway demo module.** Inside your Lumen project, create `src/lumen/logging_demo.py` with the contents of the listing below. (This is a scratch file for learning; delete it afterwards — the real logging lives inside the handlers later in the chapter.)
::: listing lumen/logging_demo.py | Listing 15.1 — Structured logger usage
from pyfly.logging import get_logger
@@ -56,6 +78,12 @@ logger.error(
)
:::
+**Step 2 — Run it.** Execute the module directly:
+
+```bash
+uv run python -m lumen.logging_demo
+```
+
In development with `format: console` the output reads naturally:
```
@@ -64,6 +92,8 @@ In development with `format: console` the output reads naturally:
10:30:02 [error ] deposit_rejected wallet_id=wlt-001 reason=insufficient_funds
```
+Notice the shape: the *first* argument (`"wallet_opened"`) is the **event name**, not a sentence, and everything after it is a `key=value` pair. There is no string formatting, no f-string, no `%s`. That is the whole point of structured logging — the event name stays stable while the fields carry the variable data.
+
In production with `format: json` every line is a self-contained JSON object:
```json
@@ -89,6 +119,14 @@ that prefix. `sqlalchemy.engine: WARNING` silences query logs without touching
your code. An environment variable `PYFLY_LOGGING_LEVEL_ROOT=WARNING` overrides
the config key, which is useful for staging builds.
+**What just happened.** You called one function, `get_logger`, and got a logger
+that takes structured `key=value` fields. The `format` setting decides how those
+fields render: `console` for humans at your terminal, `json` for machines in
+production. You did not write any handler, formatter, or appender code — PyFly
+installed those on the root logger at startup. Flip `format: console` to
+`format: json` in `pyfly.yaml` and re-run the demo to see the same three events
+emitted as one JSON object per line, ready for a log aggregator to ingest.
+
!!! tip "Why not stdlib `logging` directly?"
`logging.getLogger("x").info("event", wallet_id="wlt-001")` raises
`TypeError` — the stdlib rejects keyword arguments. `get_logger` guarantees
@@ -125,7 +163,21 @@ Every `logger.*` call inside `handle_deposit` — including calls deep in downst
### PII redaction
-**PII redaction** is enabled by default. Before any log record reaches an output handler, PyFly scans the rendered message for emails, credit-card numbers, IBANs, SSNs, JWTs, bearer tokens, and URL credentials. Detected patterns are replaced with ``, ``, and so on.
+**PII** stands for *personally identifiable information* — emails, card numbers, national-ID numbers, and the like. **PII redaction** is enabled by default. Before any log record reaches an output handler, PyFly scans the rendered message for emails, credit-card numbers, IBANs, SSNs, JWTs, bearer tokens, and URL credentials. Detected patterns are replaced with ``, ``, and so on.
+
+You can see this for yourself in a few seconds. Add one line to the demo from Step 1:
+
+```python
+logger.info("contact_logged", email="alice@example.com")
+```
+
+Run `uv run python -m lumen.logging_demo` again. The output shows the value already masked — you never had to opt in:
+
+```
+10:30:03 [info ] contact_logged email=
+```
+
+That redaction pass runs for *every* logger in the process, including ones inside third-party libraries, which is why it catches leaks you did not write.
The regex engine ships with every install. The Presidio-backed NER engine — which also catches free-text names and addresses — is available via the `[pii]` extra and activates automatically when installed:
@@ -184,7 +236,7 @@ PyFly writes to `./logs/lumen.log` and rotates at 50 MB, keeping 14 rotated file
### The MetricsRegistry
-**`MetricsRegistry`** is a thin wrapper around `prometheus_client` that guarantees each metric name is registered only once. Duplicate calls to `counter()` or `histogram()` with the same name return the existing metric rather than raising a `ValueError`. Inject it from the DI container (auto-configured when `prometheus_client` is installed) or create it manually:
+A **metric** is a number you sample over time: a count of deposits, a latency in seconds, a memory figure. **Prometheus** is the de-facto open-source metrics database; it *scrapes* (periodically reads) an HTTP endpoint your app exposes and stores the numbers. **`MetricsRegistry`** is PyFly's small front door to that world: a thin wrapper around the `prometheus_client` library that guarantees each metric name is registered only once. Duplicate calls to `counter()` or `histogram()` with the same name return the existing metric rather than raising a `ValueError`. Inject it from the DI container (auto-configured when `prometheus_client` is installed) or create it manually:
::: listing lumen/observability/metrics.py | Listing 15.3 — Creating metrics
from pyfly.observability import MetricsRegistry
@@ -215,7 +267,22 @@ deposit_duration = registry.histogram(
### @timed — automatic duration histogram
-**`@timed`** records how long an async or sync function takes to run, using a labeled histogram. It works on any callable and automatically adds `class`, `method`, and `exception` labels:
+**`@timed`** records how long an async or sync function takes to run, using a labeled histogram. It works on any callable and automatically adds `class`, `method`, and `exception` labels.
+
+!!! note "Jargon: counter vs histogram"
+ A **counter** only goes up — it answers "how many?" (deposits served,
+ errors raised). A **histogram** buckets observed *values* — it answers "how
+ long?" or "how big?" and lets Prometheus compute percentiles (p95 latency).
+ Rule of thumb: count events with a counter; measure durations and sizes with
+ a histogram.
+
+Now let us wire the first real metric into Lumen. Here is the deposit handler you built in earlier chapters — the only change is the decorator on `do_handle`.
+
+**Step 1 — Import the metrics helpers.** At the top of `src/lumen/core/services/wallets/deposit_funds_handler.py`, add `MetricsRegistry` and `timed` to the `pyfly.observability` import.
+
+**Step 2 — Create a module-level registry.** Add `registry = MetricsRegistry()` above the class. Because the registry deduplicates by name, sharing one per module is safe.
+
+**Step 3 — Decorate `do_handle`.** Put `@timed(...)` *above* `@transactional()` so the timer wraps the whole transactional unit of work.
::: listing lumen/core/services/wallets/deposit_funds_handler.py | Listing 15.4 — @timed on DepositFundsHandler
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
@@ -269,6 +336,47 @@ The decorator captures `start = time.perf_counter()`, calls the function, and ob
Histogram names follow Micrometer dot.case convention: `"lumen.deposit.duration"` becomes `lumen_deposit_duration_seconds` in Prometheus, with a `_seconds` suffix added if absent.
+**Step 4 — Expose the Prometheus endpoint.** By default the actuator web-exposes
+only `health` and `info` (see "The management port" below). Add `prometheus` to
+the exposure list in `pyfly.yaml` so the scrape endpoint appears:
+
+```yaml
+pyfly:
+ management:
+ endpoints:
+ web:
+ exposure:
+ include: "health,info,prometheus"
+```
+
+**Step 5 — Run it and see the metric appear.** Start Lumen, drive one deposit through the API, then scrape the management port.
+
+```bash
+# Terminal 1 — start the app (business API on 8080, management on 9090)
+uv run pyfly run --server uvicorn
+
+# Terminal 2 — open a wallet, then deposit into it
+WALLET=$(curl -s -X POST localhost:8080/api/v1/wallets \
+ -H 'Content-Type: application/json' \
+ -d '{"owner_id":"usr-42","currency":"EUR"}' \
+ | python -c "import sys,json;print(json.load(sys.stdin)['wallet_id'])")
+curl -s -X POST localhost:8080/api/v1/wallets/$WALLET/deposit \
+ -H 'Content-Type: application/json' -d '{"amount":1350}'
+
+# Now scrape the metric — note the MANAGEMENT port 9090, not 8080
+curl -s localhost:9090/actuator/prometheus | grep lumen_deposit_duration
+```
+
+You should see histogram lines like these (your numbers will differ):
+
+```
+lumen_deposit_duration_seconds_bucket{class="DepositFundsHandler",method="do_handle",exception="none",le="0.05"} 1.0
+lumen_deposit_duration_seconds_count{class="DepositFundsHandler",method="do_handle",exception="none"} 1.0
+lumen_deposit_duration_seconds_sum{class="DepositFundsHandler",method="do_handle",exception="none"} 0.013
+```
+
+The `_count` line confirms one observation; the `_sum` line is the total seconds spent. If `grep` finds nothing, you have not driven a deposit yet — the metric is created lazily on first call.
+
### @counted — automatic invocation counter
**`@counted`** increments a counter on every function call. Lumen's `GetBalanceHandler` is a natural fit — every balance read increments the counter, tagged by outcome:
@@ -355,6 +463,14 @@ class WithdrawFundsHandler(CommandHandler[WithdrawFunds, int]):
`amount` is an `int` in minor units (e.g. 1050 = €10.50) — the `Money` value object enforces the type. Each invocation produces both a histogram observation and a counter increment.
+**What just happened.** You added cross-cutting measurement to three handlers
+by changing nothing but the decorator stack. `@timed` answers "how long did it
+take?", `@counted` answers "how often, and did it succeed?", and stacking them
+gives you both for free. The handler bodies — the actual business logic — never
+mention metrics. After running a few deposits and withdrawals you can scrape
+`localhost:9090/actuator/prometheus` again and watch `lumen_withdrawals_total`
+and `lumen_balance_reads_total` climb.
+
### Prometheus scrape endpoint
The actuator (covered in the next section) exposes the metrics registry for scraping. When the actuator is enabled and `prometheus_client` is installed, two endpoints are mounted automatically with no additional code:
@@ -376,6 +492,14 @@ Point your Prometheus `scrape_configs` at `/actuator/prometheus` and all `Metric
### @span — OpenTelemetry span decorator
+!!! note "Jargon: trace, span, OpenTelemetry"
+ A **span** is one timed, named step of work — "fetch wallet", "persist
+ deposit". A **trace** is the whole tree of spans for a single request, root
+ to leaf. **OpenTelemetry** (often "OTel") is the vendor-neutral standard for
+ producing traces; once your spans speak OTel, any compatible viewer — Jaeger,
+ Tempo, Honeycomb — can display them. PyFly emits OTel spans so you are never
+ locked to one tool.
+
**`@span`** wraps an async or sync function in an OpenTelemetry span. Each span is a timed, named unit of work. Spans nest automatically through OpenTelemetry's context propagation, so a `@span`-decorated function called from inside another `@span`-decorated function produces a parent-child relationship in your trace viewer:
::: listing lumen/wallet/service.py | Listing 15.7 — @span on CQRS handler methods
@@ -433,6 +557,25 @@ pyfly:
endpoint: "http://localhost:4318"
```
+**Run it — see spans without a collector.** Standing up Jaeger or Tempo is
+overkill while you are learning. Set the **console exporter** instead, which
+prints each span to stdout. Lumen ships with `tracing.enabled: false`; flip it on
+and choose `console`:
+
+```yaml
+pyfly:
+ observability:
+ tracing:
+ enabled: true
+ exporter: console
+```
+
+Restart with `uv run pyfly run --server uvicorn`, drive one deposit through the
+API as in the metrics step, and watch the terminal. Each `@span` prints a JSON
+block showing its name, the parent span id, and the elapsed time — the same
+parent-child structure the diagram above sketches, just in text form. Switch back
+to `exporter: otlp` (or remove the override) once you have a real collector.
+
Exporter selection rules:
- `exporter: otlp` — uses OTLP/HTTP; requires `opentelemetry-exporter-otlp`
@@ -533,21 +676,47 @@ The **Actuator** gives Kubernetes and your ops tooling a stable contract: a set
### Enabling the Actuator
-Pass `actuator_enabled=True` to `create_app()`, or set the flag in `pyfly.yaml`:
+The Actuator is **on by default** when a PyFly context is present — you do not
+have to enable it at all to get `/actuator/health` and `/actuator/info`. You only
+touch the flag to turn it *off*, or to be explicit. Pass `actuator_enabled=True`
+to `create_app()`, or set the flag in `pyfly.yaml`:
```yaml
pyfly:
- web:
- actuator:
- enabled: true
+ management:
+ enabled: true # default; the actuator is on unless you set false
app:
name: lumen
version: 1.0.0
description: Lumen wallet service
```
+!!! note "Config key changed"
+ The enable flag is now `pyfly.management.enabled`. The older
+ `pyfly.web.actuator.enabled` still works as a legacy alias, but new code
+ should use the `pyfly.management.*` namespace, which is where the port,
+ security, and endpoint-exposure settings also live.
+
When enabled, `create_app()` automatically scans the DI container for `HealthIndicator` beans, creates a `HealthAggregator`, instantiates all built-in endpoints, and mounts them at `/actuator/*`.
+**Run it — your first health check.** Lumen already enables the actuator, so
+just start the app and curl the health endpoint on the **management port**:
+
+```bash
+uv run pyfly run --server uvicorn
+curl -s localhost:9090/actuator/health
+```
+
+A healthy app returns HTTP 200 with:
+
+```json
+{"status":"UP"}
+```
+
+If you get connection-refused, confirm you used `9090` (management), not `8080`
+(business). The same `/actuator/health` on `8080` returns 404 — the business
+port deliberately does not carry management endpoints.
+
### The management port
By default these `/actuator/*` endpoints — and the `/admin` dashboard from the
@@ -565,6 +734,42 @@ endpoints. A Kubernetes deployment therefore points liveness/readiness probes an
the Prometheus `ServiceMonitor` at port `9090`, and the `Service`/`Ingress` for
user traffic at `8080`.
+!!! warning "The management port is OPEN by default"
+ As of v26.6.110 the management port is **unauthenticated by default** — the
+ `/actuator/*` and `/admin` routes answer any caller that can reach `9090`.
+ This is intentional (Spring Boot's model): the port is meant to be reachable
+ only from inside your cluster, behind network isolation, never exposed on the
+ public internet. If you cannot guarantee that isolation, turn on the app's
+ security filters for the management port too:
+
+ ```yaml
+ pyfly:
+ management:
+ security:
+ enabled: true
+ ```
+
+ With that flag set, the same authentication, role guards, and CSRF rules
+ that protect your business API also gate the management port.
+
+By default the actuator web-exposes only **`health` and `info`** — again matching
+Spring Boot, which keeps potentially sensitive endpoints (`beans`, `env`,
+`threaddump`, `prometheus`) off the wire until you opt in. Widen the set with
+`pyfly.management.endpoints.web.exposure.include`:
+
+```yaml
+pyfly:
+ management:
+ endpoints:
+ web:
+ exposure:
+ include: "health,info,metrics,prometheus,loggers" # or "*" for all
+```
+
+So the Prometheus scrape and runtime-logger steps later in this chapter assume
+you have added `prometheus` and `loggers` to this list. The `*` shortcut exposes
+everything and is convenient in development.
+
### Built-in endpoints
| Endpoint | Method | Description |
@@ -639,7 +844,15 @@ class DatabaseHealthIndicator:
`HealthStatus.status` accepts four values: `"UP"`, `"DOWN"`, `"OUT_OF_SERVICE"`, or `"UNKNOWN"`. The aggregator applies a severity ordering (`DOWN > OUT_OF_SERVICE > UP > UNKNOWN`) and returns the worst-case status across all indicators. If any indicator's `health()` method raises, that indicator is treated as `"DOWN"` with `details={"error": "check failed"}`; the exception is logged but does not crash the health endpoint.
-A healthy response looks like:
+**Run it — watch a custom indicator surface.** Drop the listing above into
+`src/lumen/health/indicators.py`, restart Lumen, and ask for the detailed health
+report (the `?show-details` form, or simply scrape it from the management port):
+
+```bash
+curl -s localhost:9090/actuator/health
+```
+
+A healthy response now includes your component by name:
```json
{
@@ -657,25 +870,46 @@ A healthy response looks like:
}
```
+You wrote no registration code: the `@component` stereotype plus the
+`async def health()` method is the entire contract. At startup the actuator
+scanned the container, found anything that looks like a health indicator, and
+folded it into the aggregator.
+
+!!! note "Building probes by hand — `app.state.pyfly_health_aggregator`"
+ New in v26.6.110, the live `HealthAggregator` is reachable at
+ `app.state.pyfly_health_aggregator` on the Starlette app object. This is the
+ *same* aggregator the `/actuator/health` route uses, whether the actuator
+ runs on the main app or on the separate management port. If you ever need a
+ bespoke readiness gate — say, a custom ASGI route that returns 503 until a
+ one-time warm-up completes — you can read this aggregator directly or
+ register extra indicators on it after `create_app()`, instead of going
+ through HTTP. It is exposed only by the Starlette adapter.
+
### Changing log levels at runtime
-The loggers endpoint lets you inspect and change log levels without restarting Lumen — invaluable when a production incident needs DEBUG output for exactly one package:
+The loggers endpoint lets you inspect and change log levels without restarting Lumen — invaluable when a production incident needs DEBUG output for exactly one package. First add `loggers` to the exposure list (`pyfly.management.endpoints.web.exposure.include: "health,info,loggers"`), then drive it from the **management port** `9090`:
```bash
# List all loggers with configured and effective levels
-curl http://localhost:8080/actuator/loggers
+curl http://localhost:9090/actuator/loggers
# Enable DEBUG for the wallet module — takes effect immediately
-curl -X POST http://localhost:8080/actuator/loggers/lumen.wallet \
+curl -X POST http://localhost:9090/actuator/loggers/lumen.wallet \
-H "Content-Type: application/json" \
-d '{"configuredLevel": "DEBUG"}'
# Reset to inherit from parent
-curl -X POST http://localhost:8080/actuator/loggers/lumen.wallet \
+curl -X POST http://localhost:9090/actuator/loggers/lumen.wallet \
-H "Content-Type: application/json" \
-d '{"configuredLevel": null}'
```
+**What just happened.** You changed a logger's level on a *running* process. The
+POST took effect immediately — no restart, no redeploy. In a real incident you
+would flip exactly one package to DEBUG, capture the noisy output you need, then
+POST `null` to put it back the way it was, all without disturbing the rest of the
+service.
+
The endpoint uses Spring Boot's level vocabulary (`OFF`, `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`) and is drop-in compatible with Spring Boot Actuator tooling.
### Custom actuator endpoint
@@ -713,19 +947,19 @@ class GitInfoEndpoint:
### Kubernetes probe configuration
-Point your pod spec at the dedicated liveness and readiness sub-paths so Kubernetes can make independent restart and traffic decisions:
+Point your pod spec at the dedicated liveness and readiness sub-paths so Kubernetes can make independent restart and traffic decisions. Because the actuator lives on the management port, the probes target **`9090`**, while your `Service` routes user traffic to `8080`:
```yaml
livenessProbe:
httpGet:
path: /actuator/health/liveness
- port: 8080
+ port: 9090
initialDelaySeconds: 10
periodSeconds: 30
readinessProbe:
httpGet:
path: /actuator/health/readiness
- port: 8080
+ port: 9090
initialDelaySeconds: 5
periodSeconds: 10
```
@@ -763,6 +997,42 @@ pyfly:
The dashboard auto-discovers beans, health indicators, loggers, scheduled tasks, HTTP mappings, caches, CQRS handlers, sagas, and metrics from the running `ApplicationContext`. It presents them in **15 built-in views** with real-time Server-Sent Event (SSE) updates — no WebSocket, no polling loop in your code.
+!!! note "Where to find it: the management port"
+ Like the actuator, the dashboard is served on the **management port**. With
+ Lumen's defaults that is `http://localhost:9090/admin`, not `8080/admin`.
+ Set `pyfly.management.server.port` equal to `pyfly.server.port` if you would
+ rather serve the dashboard on the same port as your API. And remember: that
+ port is open by default — gate it with `pyfly.management.security.enabled` or
+ the dashboard's own `require_auth` (shown under "Security") before exposing it
+ anywhere untrusted.
+
+**Run it — open the dashboard.** Enable it in `pyfly.yaml`, start Lumen, and open
+the URL in a browser:
+
+```yaml
+pyfly:
+ admin:
+ enabled: true
+ title: "Lumen Admin"
+```
+
+```bash
+uv run pyfly run --server uvicorn
+# then visit http://localhost:9090/admin
+```
+
+You should see the Overview view populate within a second or two: app name and
+uptime, a green health badge, and bean counts grouped by stereotype. Drive a few
+deposits through `localhost:8080` and watch the Health and Metrics panels update
+live — the page never reloads, because the data arrives over SSE.
+
+!!! note "Jargon: SSE (Server-Sent Events)"
+ SSE is a one-way streaming channel: the browser opens a single long-lived
+ HTTP connection and the server *pushes* events down it as they happen. It is
+ simpler than a WebSocket (which is two-way) and is exactly the right tool for
+ a dashboard that only needs to *receive* updates. You write no polling loop;
+ the framework handles the stream.
+
### Built-in views
**Dashboard section:**
@@ -934,7 +1204,23 @@ PyFly's AOP module ships five advice types:
### @aspect — declaring an aspect
-**`@aspect`** marks a class as a PyFly aspect. The class is automatically registered in the DI container as a singleton and receives injected dependencies via `__init__`. No explicit base class is required:
+!!! note "Jargon: aspect, advice, pointcut, weaving"
+ Four words travel together in AOP. An **aspect** is the class that bundles a
+ cross-cutting concern. **Advice** is a single piece of behaviour inside it
+ (the body of `@before`, `@around`, and so on). A **pointcut** is the pattern
+ string — like `"service.*.*"` — that decides *which* methods the advice
+ applies to. **Weaving** is the act of stitching the advice into those methods
+ at startup. You write aspects; PyFly does the weaving.
+
+**`@aspect`** marks a class as a PyFly aspect. The class is automatically registered in the DI container as a singleton and receives injected dependencies via `__init__`. No explicit base class is required.
+
+Build the logging aspect in three moves.
+
+**Step 1 — Declare the class.** Create `src/lumen/aspects/logging_aspect.py`, mark the class `@aspect`, and give it a module-level `logger`.
+
+**Step 2 — Add advice methods.** Each method is decorated with one advice type (`@before`, `@after_returning`, `@after_throwing`) and a pointcut string. The `jp: JoinPoint` argument carries the intercepted call's details.
+
+**Step 3 — Set ordering.** `@order(-50)` makes this aspect run earlier than higher-numbered ones — useful when you want logging to bracket the metrics aspect you write next.
::: listing lumen/aspects/logging_aspect.py | Listing 15.12 — A logging aspect
from pyfly.aop import aspect, before, after_returning, after_throwing, JoinPoint
@@ -1035,6 +1321,15 @@ In production you never call `weave_bean()` manually. `AopAutoConfiguration` reg
The result is zero-configuration AOP: define aspects, define services, start the application — the weaver wires them together.
+**What just happened.** You wrote two aspects — one for logging, one for metrics —
+and never edited a single handler. At startup, `AspectBeanPostProcessor` matched
+their pointcuts against your service beans and wove the advice into the matching
+methods in place. From now on, every `@service` method emits entry/exit logs and a
+duration histogram automatically. Add a new handler tomorrow and it inherits the
+same observability the moment its pointcut matches — nothing to remember, nothing
+to copy-paste. That is the payoff of AOP: the cross-cutting behaviour lives in one
+place, and the business code stays clean.
+
### JoinPoint reference
Every advice handler receives a `JoinPoint` dataclass:
@@ -1121,6 +1416,28 @@ class DepositFundsHandler(CommandHandler[DepositFunds, int]):
Seven lines of decorators and one `get_logger` call — and Lumen's deposit path is fully observable.
+**Run it — confirm nothing broke.** Observability decorators wrap behaviour
+around your handlers; they must not change the result those handlers return. Run
+the existing Lumen suite to prove the deposit path still behaves:
+
+```bash
+uv run --extra dev pytest -q
+```
+
+Every test should stay green:
+
+```
+......................................... [100%]
+41 passed in 0.3s
+```
+
+Then do one full manual lap with the app running: drive a deposit on `8080`,
+confirm `/actuator/health` is `UP` on `9090`, scrape `/actuator/prometheus` and
+see `lumen_wallet_deposits_total` increment, and open `http://localhost:9090/admin`
+to watch the same event flow through the live Metrics and Log Viewer panels. All
+three pillars — logs, metrics, traces — now describe a single deposit, joined by
+one `trace_id`.
+
---
## What you built {.recap}
diff --git a/book/manuscript/16-testing.md b/book/manuscript/16-testing.md
index 0f66115f..5f1cfaaf 100644
--- a/book/manuscript/16-testing.md
+++ b/book/manuscript/16-testing.md
@@ -28,13 +28,42 @@ testpaths = ["tests"]
pythonpath = ["src"]
```
+A quick gloss before we start, since three terms recur in this chapter. A
+**fixture** is a reusable piece of test setup — pytest builds it once, hands it to
+your test, and tears it down afterward. A **conftest.py** is a special file pytest
+discovers automatically; any fixtures you declare there become available to every
+test in the package without an import. And **`pytest-asyncio` auto mode** simply
+means you can write `async def test_...` and pytest will `await` it for you — no
+per-test decorator required. Each of these appears again with a concrete example
+below; this is just the map.
+
Install dev dependencies and run the suite:
```bash
uv run --extra dev pytest -q
```
-The bare `uv sync` (without `--extra dev`) omits the dev group, so pytest is not installed. Always include `--extra dev` when running tests.
+The bare `uv sync` (without `--extra dev`) omits the dev group, so pytest is not
+installed. Always include `--extra dev` when running tests.
+
+**Run it.** From the `samples/lumen` directory, run the whole suite once now so you
+have a baseline before changing anything:
+
+```bash
+uv run --extra dev pytest -q
+```
+
+You should see a row of dots — one per test — followed by a summary line:
+
+```text
+......................................... [100%]
+41 passed in 0.28s
+```
+
+Forty-one passing tests, under a third of a second, no Docker and no external
+process. That speed is the whole point of the pyramid: the fast base catches most
+regressions before the slower integration layers ever run. If you instead see
+`No module named pytest`, you forgot `--extra dev` — re-run with it.
---
@@ -46,6 +75,37 @@ The domain model — `Money` and `Wallet` — has no framework dependencies. It
`Money` is a frozen dataclass. Every operation either succeeds and returns a new `Money` instance, or raises `BusinessRuleViolation`. Each violation carries a `.rule` string that names the violated invariant — useful for asserting the exact rule in tests.
+A quick gloss on two terms. A **value object** is an object defined entirely by its
+values — two `Money(1050, EUR)` instances are equal because their fields are equal,
+not because they are the same object in memory. A **frozen dataclass** is Python's
+way of making such an object immutable: once constructed, you cannot reassign its
+fields. Together they make `Money` safe to pass around freely — no caller can
+mutate it behind your back, so it never needs defensive copying.
+
+Let us build the test file one assertion-group at a time. Each step below maps to
+one `def test_...` function in the listing that follows.
+
+**Step 1 — equality is structural.** `test_value_equality_is_structural` asserts
+that two `Money` values with the same amount and currency are equal, and that
+differing in either field makes them unequal. This is the value-object contract.
+
+**Step 2 — immutability is enforced.** `test_money_is_immutable` tries to assign to
+`money.amount` and expects an exception. The frozen dataclass raises
+`FrozenInstanceError`, proving you cannot mutate a value after construction.
+
+**Step 3 — arithmetic returns new values.** `test_add_and_subtract_same_currency`
+checks that `add` and `subtract` produce the expected `Money`, never mutating the
+operands.
+
+**Step 4 — the convenience surface.** `test_zero_factory_and_major_units` covers the
+`Money.zero(currency)` factory, the `major_units` property, and the `__str__`
+formatting.
+
+**Step 5 — invariants reject bad input.** The last two tests assert that mixing
+currencies and passing a non-integer amount each raise `BusinessRuleViolation` with
+a specific `.rule` string — `"money-currency-mismatch"` and
+`"money-amount-integer"`.
+
::: listing tests/test_money.py | Listing 16.1 — Pure unit tests for the Money value object
from __future__ import annotations
@@ -95,6 +155,29 @@ def test_non_integer_amount_is_rejected() -> None:
Every test is synchronous — no `async`, no `await`, no fixtures. Pytest collects the module-level functions automatically. `Currency.EUR` is an enum value, not a plain string, matching the domain model's type contract exactly.
+**Run it.** Run just this file to see the unit base of the pyramid in action:
+
+```bash
+uv run --extra dev pytest tests/test_money.py -q
+```
+
+Expected output:
+
+```text
+...... [100%]
+6 passed in 0.02s
+```
+
+Six tests, twenty milliseconds. No database connected, no event bus started — these
+tests construct a plain object and assert on its behaviour. That is what makes the
+base of the pyramid so wide and so fast.
+
+*What just happened.* You proved the entire `Money` contract — equality,
+immutability, arithmetic, and every invariant — without touching a single piece of
+framework infrastructure. Pure-domain code stays pure-domain testable. When one of
+these fails, you know the bug is in the value object itself, not in wiring, a
+session, or the bus.
+
!!! tip "Minor-unit arithmetic"
`Money` stores amounts in **minor units** (integer cents). `Money(1050,
Currency.EUR)` represents €10.50 — verified by `major_units == 10.5` and
@@ -105,6 +188,35 @@ Every test is synchronous — no `async`, no `await`, no fixtures. Pytest collec
`Wallet` enforces several invariants: the owner must be a non-blank string, deposits must be positive, withdrawals must not overdraw, and amounts must match the wallet's currency. Each violation carries a `.rule` attribute for precise assertion.
+One term first. An **aggregate** (or **aggregate root**) is a cluster of domain
+objects treated as a single unit for consistency — here, the `Wallet` and its
+balance. Every change goes through the aggregate's methods, so the aggregate is the
+one place that guarantees its invariants hold. That makes it the natural unit to
+test: drive it through its public methods and assert the rules never break.
+
+The pattern every aggregate test follows is **arrange, act, assert**. Arrange:
+construct the wallet into a known state. Act: call one method. Assert: check the
+balance, the emitted event, or the raised violation. Watch for it in each test:
+
+**Step 1 — opening emits an event.** `test_open_creates_empty_wallet` opens a wallet
+and asserts the balance is zero and exactly one `WalletOpened` event is queued.
+
+**Step 2 — opening validates its arguments.** `test_open_requires_owner` passes a
+blank owner and expects `BusinessRuleViolation` with rule
+`"wallet-owner-required"`.
+
+**Step 3 — the happy path of deposit then withdraw.**
+`test_deposit_then_withdraw_happy_path` deposits, asserts the balance and the
+`FundsDeposited` event, then withdraws and asserts the balance and the
+`FundsWithdrawn` event. Note the `clear_events()` call in the arrange step — more on
+that just below the listing.
+
+**Step 4 — invariants reject bad operations.** The final three tests prove a
+withdrawal cannot overdraw, a deposit must be positive, and an amount must match the
+wallet's currency. Each asserts the exact `.rule` string, and the overdraw test also
+asserts the balance was left unchanged and no event was raised — proof the invariant
+fired *before* any state changed.
+
::: listing tests/test_wallet_aggregate.py | Listing 16.2 — Unit tests for the Wallet aggregate root
from __future__ import annotations
@@ -185,6 +297,28 @@ def test_currency_mismatch_is_rejected() -> None:
Three details deserve attention. First, `Wallet.open` takes three positional arguments: a pre-generated `wallet_id`, an `owner_id`, and a `Currency` enum value — the aggregate does not generate its own ID. Second, `pending_events()` returns buffered events without draining; `clear_events()` returns and drains. The `test_deposit_then_withdraw_happy_path` test calls `clear_events()` after opening so each assertion sees exactly one event. Third, `FundsDeposited` and `FundsWithdrawn` carry `amount` (the operation amount in minor units) and `balance` (the post-operation running balance) — not `new_balance`. Always verify real event dataclass fields before asserting them.
+**Run it.**
+
+```bash
+uv run --extra dev pytest tests/test_wallet_aggregate.py -q
+```
+
+Expected output:
+
+```text
+...... [100%]
+6 passed in 0.02s
+```
+
+*What just happened.* The trickiest line to read is the assignment
+`[event] = wallet.clear_events()`. That is a list unpacking: it asserts the returned
+list has **exactly one** element and binds it to `event` in a single step. If the
+aggregate had raised zero or two events, the unpacking itself would raise a
+`ValueError` and the test would fail — so the shape of the event stream is checked
+for free. This is why the happy-path test calls `clear_events()` right after opening:
+it drains the `WalletOpened` event so the next unpacking sees only the
+`FundsDeposited` event you are actually asserting on.
+
!!! spring "Spring parity"
Testing a DDD aggregate in isolation is the same discipline in any stack. In
Spring / jMolecules you would call the aggregate's methods directly and
@@ -200,6 +334,47 @@ The CQRS and event-listener tests need real infrastructure: a SQLite-backed `Wal
The key difference from a hand-rolled adapter test is that the `repository` fixture uses the **real framework `WalletRepository`** — the same Spring-Data-style class the application boots — and runs it through the **real `RepositoryBeanPostProcessor`**, which compiles derived-query stubs from method names at startup.
+This file is the heart of the chapter, so we will read it top to bottom as a series
+of small, layered steps. Each fixture builds on the one above it. The thing to keep
+in mind: pytest links fixtures by **name**. When a fixture function declares a
+parameter, pytest looks for a fixture with that name, builds it, and injects it. That
+is how a small graph of independent fixtures composes into a full test stack.
+
+**Step 1 — make the sample importable.** The first few lines push the sample's
+`src/` onto `sys.path` so `import lumen...` resolves. The `pythonpath = ["src"]`
+setting in `pyproject.toml` does the same thing for pytest's own collection; this
+line covers direct imports inside `conftest.py` before pytest's path tweaks apply.
+
+**Step 2 — `session_factory`: a database engine.** This async fixture creates an
+in-memory SQLite engine, runs `Base.metadata.create_all` to build the schema, and
+yields an `async_sessionmaker`. A **session factory** is a callable that hands out
+fresh database sessions; the framework's relational auto-configuration creates one
+exactly like this at startup. The single shared engine keeps the in-memory database
+alive for the whole test — close it and the data vanishes.
+
+**Step 3 — `repository`: the real Spring-Data-style repository.** It constructs the
+framework `WalletRepository`, then calls
+`RepositoryBeanPostProcessor().after_init(repo, "walletRepository")`. A
+**post-processor** is a hook that runs against a freshly created bean — here it reads
+method names like `find_by_owner_id` and compiles them into real queries. Skip this
+call and those methods stay stubs that raise `NotImplementedError`.
+
+**Step 4 — `event_bus`: the in-memory event bus.** A one-line fixture that yields an
+`InMemoryEventBus` — the same publisher the application uses in non-Kafka
+deployments.
+
+**Step 5 — `audit_listener`: a subscriber on that bus.** It creates the
+`WalletAuditListener` and subscribes its handler to the bus, reading the event
+patterns straight off the decorated method's `__pyfly_event_patterns__` attribute —
+exactly what the `ApplicationContext` does when it auto-wires listeners at startup.
+
+**Step 6 — `command_bus` and `query_bus`: the CQRS dispatchers.** Each builds a
+`HandlerRegistry`, registers the real handlers (passing them the `repository`,
+`event_bus`, and `session_factory` they need), and yields a bus. **CQRS** —
+Command/Query Responsibility Segregation — simply means writes go through a command
+bus and reads through a query bus; a **handler** is the function that actually
+processes one command or query.
+
::: listing tests/conftest.py | Listing 16.3 — conftest.py: real framework components wired with no mocks
from __future__ import annotations
@@ -347,6 +522,24 @@ Each fixture is declared with `@pytest_asyncio.fixture` (not the bare `@pytest.f
The `session_factory` fixture is shared. `repository` and `command_bus` both receive it, so the same in-memory SQLite engine backs reads, writes, and the `@transactional` boundary the handlers open. The `audit_listener` and `command_bus` fixtures both receive `event_bus`; pytest instantiates that once per test and shares it between them, so events published by the command handlers are visible to the listener.
+*What just happened.* You wired a complete, production-shaped test stack — engine,
+repository, event bus, listener, and both CQRS buses — entirely from fixtures, with
+no mocks. The two facts that make it work are worth holding onto. First, **fixtures
+compose by name**: `command_bus` asks for `repository`, `event_bus`, and
+`session_factory` simply by naming them as parameters, and pytest threads the graph
+together. Second, **a fixture requested by two others is built once per test**: both
+`repository` and `command_bus` name `session_factory`, so they share one engine —
+the write a command makes is the read a query sees. Get this file right and every
+test in the next four sections is a two-line call.
+
+!!! spring "Spring parity"
+ `conftest.py` is PyFly's `@TestConfiguration` plus the shared
+ `application-test.properties` of a Spring Boot project — a single place that
+ declares the beans every test reuses. A `@pytest_asyncio.fixture` is the rough
+ equivalent of a `@Bean` method in that config: pytest builds it lazily, injects
+ it where its name is requested, and tears it down afterward, just as the Spring
+ test context manages bean lifecycle and injection.
+
!!! tip "No mocks anywhere"
Every component in `conftest.py` is the real production implementation.
`WalletRepository` is the same class the application boots.
@@ -361,6 +554,26 @@ The `session_factory` fixture is shared. `repository` and `command_bus` both rec
With the fixtures from `conftest.py`, exercising the full command/query cycle is a matter of calling `command_bus.send(...)` and `query_bus.query(...)`. No handler is instantiated in the test body — the bus dispatches to the handler already registered in the fixture.
+Notice how short each test body becomes now that the wiring lives in `conftest.py`.
+A test declares the fixtures it needs as parameters, then reads as plain narrative:
+
+**Step 1 — request the buses.** Each test signature lists `command_bus` and/or
+`query_bus`. pytest sees those names, builds the fixture graph from `conftest.py`,
+and injects the ready buses.
+
+**Step 2 — send commands.** `await command_bus.send(OpenWallet(...))` returns the new
+wallet id; subsequent `DepositFunds` and `WithdrawFunds` commands return the running
+balance. You assert on each return value as you go.
+
+**Step 3 — query the read side.** `await query_bus.query(GetWallet(...))` and
+`GetBalance(...)` reload the persisted state and return DTOs (data-transfer objects —
+plain read models). You assert their fields match what the commands wrote.
+
+**Step 4 — prove the error paths.** The remaining tests send a command that must fail
+— an overdraw, a non-positive deposit, an unknown wallet — wrapped in
+`pytest.raises(CommandProcessingException)`. That context manager asserts the block
+raises the named exception; if it does not, the test fails.
+
::: listing tests/test_cqrs_flow.py | Listing 16.4 — End-to-end CQRS tests through the real bus
from __future__ import annotations
@@ -464,6 +677,27 @@ async def test_deposit_to_unknown_wallet_is_rejected(
The error-path tests verify that the bus surfaces domain violations correctly. **`CommandProcessingException`** is the bus's wrapper for any exception raised inside a handler — including `BusinessRuleViolation` from the aggregate. Calling code never sees the raw domain exception; it always sees the bus wrapper.
+**Run it.**
+
+```bash
+uv run --extra dev pytest tests/test_cqrs_flow.py -q
+```
+
+Expected output:
+
+```text
+..... [100%]
+5 passed in 0.05s
+```
+
+*What just happened.* This is the first layer that touches real infrastructure, and
+it still runs in milliseconds. The command went through the real bus, the real
+handler opened a real `@transactional` unit of work on a real SQLite session,
+committed it, and the query read it back — the exact path that runs in production,
+minus the HTTP layer. Because the handler is registered in the fixture rather than
+constructed in the test, you are testing the *dispatch* as well as the logic: if the
+command-to-handler routing broke, these tests would catch it.
+
!!! note "asyncio_mode = \"auto\" and @pytest.mark.asyncio"
With `asyncio_mode = "auto"` every async test is collected and run
automatically. The `@pytest.mark.asyncio` decorator is **not required** but
@@ -478,6 +712,41 @@ The CQRS flow tests prove the full open/deposit/withdraw/query pipeline. The rep
The local fixture `_make_repo` mirrors what the `ApplicationContext` does at startup: construct the repository and run `RepositoryBeanPostProcessor.after_init` to compile the derived-query stubs. Without that call, methods like `find_by_owner_id` would raise `NotImplementedError`.
+Two terms before the listing. A **derived query** is a repository method whose body
+is generated from its *name*: `find_by_owner_id` becomes `WHERE owner_id = :value`,
+no SQL written by hand. A **Specification** is a reusable, composable predicate
+object you pass to a query — `balance_at_least(1000)` is one — for filters too
+dynamic to bake into a method name. **Pagination** wraps both: `Pageable.of(page,
+size, sort)` describes which slice you want, and the query returns a `Page` carrying
+the items plus `total`, `total_pages`, and `has_next`.
+
+This section uses a **file-based** SQLite database (via `tmp_path`) rather than the
+in-memory one, so it can prove a stronger property — durability across a reconnect.
+Here is the shape of each test:
+
+**Step 1 — `sqlite_factory`: a temp-file engine.** The fixture builds a SQLite engine
+backed by a real file under pytest's `tmp_path` (a fresh temp directory per test,
+auto-deleted afterward), creates the schema, and yields both the factory and the URL.
+Yielding the URL is what lets one test reconnect with a brand-new engine.
+
+**Step 2 — CRUD and persistence.**
+`test_upsert_inserts_then_updates_and_persists` upserts a row, upserts it again with
+a new balance to prove update-in-place, commits, reads it back — then disposes the
+engine and reconnects with a *fresh* one to prove the data truly hit disk.
+
+**Step 3 — the unknown-id path.** `test_find_by_id_unknown_returns_none` confirms a
+miss returns `None`, not an error.
+
+**Step 4 — derived query.** `test_derived_find_by_owner_id` inserts wallets for two
+owners and asserts `find_by_owner_id("alice")` returns only Alice's — proof the
+post-processor compiled the method-name convention correctly.
+
+**Step 5 — Specification + pagination.**
+`test_specification_find_rich_paged_and_sorted` and
+`test_find_all_pageable_counts_and_pages` exercise the `find_rich` /
+`find_all_by_spec` predicate path and the `find_all(pageable)` paging path, asserting
+`total`, `total_pages`, `has_next`, and the exact ordering of `page.items`.
+
::: listing tests/test_sql_wallet_repository.py | Listing 16.5 — Repository tests: CRUD, derived query, pagination, Specification
from __future__ import annotations
@@ -664,6 +933,27 @@ async def test_find_all_pageable_counts_and_pages(
Four things to note. First, `_make_repo` calls `RepositoryBeanPostProcessor().after_init(repo, ...)` — without this, `find_by_owner_id` is still a stub and raises `NotImplementedError`. The post-processor compiles the method name into a SQLAlchemy `WHERE owner_id = :owner_id` clause. Second, `upsert` is the repository's insert-or-update; after each batch of upserts, `await session.commit()` flushes to SQLite. Third, `find_rich` takes a minimum balance and a `Pageable`; it delegates to `find_all_by_spec_paged(balance_at_least(min), pageable)`. Fourth, the two-engine pattern in `test_upsert_inserts_then_updates_and_persists` proves true durability: data committed through one engine is readable by a completely fresh engine and session.
+**Run it.**
+
+```bash
+uv run --extra dev pytest tests/test_sql_wallet_repository.py -q
+```
+
+Expected output:
+
+```text
+..... [100%]
+5 passed in 0.06s
+```
+
+*What just happened.* The standout is the two-engine reconnect in the first test.
+Many "persistence" tests pass even when nothing was written to disk, because the same
+session caches the object in memory and hands it back on read. By disposing the
+engine entirely and opening a *second* one against the same file URL, this test
+forces a real round-trip to storage — if `upsert` or `commit` were silently not
+persisting, the reconnect would return `None` and the test would fail. That is the
+difference between testing your code and testing your cache.
+
!!! spring "Spring parity"
This test layer is the Python equivalent of `@DataJpaTest` with an embedded
H2 database in Spring Boot. `@DataJpaTest` loads only the JPA layer (entities,
@@ -684,6 +974,26 @@ Four things to note. First, `_make_repo` calls `RepositoryBeanPostProcessor().af
`WalletAuditListener` listens for domain events published by the command handlers. Testing it end to end — command runs on the bus, handler publishes events, listener receives them — requires all three components to share the same `InMemoryEventBus`. The `conftest.py` fixtures already arrange this: both `command_bus` and `audit_listener` accept an `event_bus` argument, and pytest injects the same instance into both.
+An **event listener** is just a method that the framework subscribes to the bus so it
+runs whenever a matching event is published. Lumen's `WalletAuditListener` keeps an
+in-memory audit log and a running balance per wallet — a tiny **projection** (a read
+model built by folding events). Testing it is the clearest demonstration of the
+shared-fixture trick: because `command_bus` and `audit_listener` name the same
+`event_bus`, an event a command publishes is an event the listener observes, with no
+glue in the test body.
+
+The tests follow one rhythm:
+
+**Step 1 — drive commands.** Open a wallet, deposit, withdraw — all through
+`command_bus`.
+
+**Step 2 — read the projection.** Call `audit_listener.entries_for(wallet_id)` and
+assert the recorded event types, in order, plus the `running_total`.
+
+**Step 3 — assert the negative.** One test deliberately overdraws — a command that
+must fail — and asserts the audit log records nothing from it. A failed operation
+leaves no trace.
+
::: listing tests/test_event_listener.py | Listing 16.6 — Event listener tests: command publishes, listener observes
from __future__ import annotations
@@ -761,11 +1071,34 @@ async def test_event_type_matches_domain_event_class_names(
`test_event_type_matches_domain_event_class_names` proves a domain invariant: a rejected command (overdraw) raises no event. The audit log must never record a side effect from a failed operation.
+**Run it.**
+
+```bash
+uv run --extra dev pytest tests/test_event_listener.py -q
+```
+
+Expected output:
+
+```text
+... [100%]
+3 passed in 0.04s
+```
+
+*What just happened.* No part of the test connected the listener to the bus — the
+`audit_listener` fixture did that in `conftest.py`, subscribing the handler to the
+same `event_bus` the `command_bus` publishes through. So sending a command and then
+reading `entries_for(...)` exercises the real publish/subscribe path end to end. The
+negative test is the subtle one: it proves the audit log is driven by *events*, not
+by *attempts* — a rejected withdrawal raises a `BusinessRuleViolation` before any
+event is emitted, so nothing reaches the listener.
+
!!! tip "event_type is the class name"
PyFly's event publisher sets `event_type` to the domain event class name:
`"WalletOpened"`, `"FundsDeposited"`, `"FundsWithdrawn"`. The
- `@event_listener(pattern)` decorator on `WalletAuditListener.on_wallet_event`
- uses a glob pattern (`"Wallet*"`, `"Funds*"`) to subscribe to all three.
+ `@event_listener(event_types=["WalletOpened", "FundsDeposited", "FundsWithdrawn"])`
+ decorator on `WalletAuditListener.on_wallet_event` names those three types
+ explicitly; the framework stores them on the method as
+ `__pyfly_event_patterns__`, which the `audit_listener` fixture reads to subscribe.
The test asserts the string class names directly.
---
@@ -774,7 +1107,29 @@ async def test_event_type_matches_domain_event_class_names(
The unit tests, CQRS flow tests, and repository tests each wire one layer of the stack. The booted-context integration test wires everything at once: it starts the real `ApplicationContext` — DI component scan, CQRS auto-configuration, relational auto-configuration, `RepositoryBeanPostProcessor`, `@transactional` seam, EDA event bus — then resolves the `DefaultCommandBus` and `DefaultQueryBus` from the context and drives the full wallet lifecycle.
-The database URL is overridden via an environment variable so the test never touches the developer's `lumen.db`.
+The **ApplicationContext** is PyFly's runtime container — the object that scans for
+components, builds beans, runs post-processors, and holds the wired application
+together. Booting it is the most faithful test you can write short of starting an
+HTTP server: every piece of wiring the framework does at startup actually happens.
+
+The database URL is overridden via an environment variable so the test never touches the developer's `lumen.db`. Here is the plan:
+
+**Step 1 — isolate the database.** The `booted_context` fixture uses pytest's
+`monkeypatch` fixture to set `PYFLY_DATA_RELATIONAL_URL` to a temp-file SQLite path
+under `tmp_path`, *before* the app boots. `monkeypatch` is pytest's safe way to set
+an environment variable for the duration of one test and automatically restore it
+afterward — so this test can never clobber your real `lumen.db`.
+
+**Step 2 — boot the real application.** It constructs `PyFlyApplication(LumenApplication,
+config_path=...)` and `await app.startup()`. That single call runs the entire startup
+sequence: component scan, all auto-configurations, the `RepositoryBeanPostProcessor`,
+and the event bus. The fixture yields `app.context` and, in its `finally` block,
+closes the shared session and calls `app.shutdown()`.
+
+**Step 3 — resolve beans and drive the lifecycle.** The test calls
+`ctx.get_bean(DefaultCommandBus)` and `ctx.get_bean(DefaultQueryBus)` — pulling the
+*same* buses the application would use — then runs open → deposit → withdraw → list →
+rich → balance, asserting each result.
::: listing tests/test_app_context_integration.py | Listing 16.7 — Booted-context integration: full DI + persistence composition
from __future__ import annotations
@@ -888,6 +1243,44 @@ async def test_full_lifecycle_through_booted_context(
`test_full_lifecycle_through_booted_context` exercises every query type the application exposes: `GetWallet` (aggregate reload), `ListWallets` (paginated list using `find_all(pageable)`), `ListRichWallets` (Specification predicate using `find_all_by_spec_paged`), and `GetBalance` (projection-backed balance). It proves that the `RepositoryBeanPostProcessor`, the `@transactional` boundary around each command handler, and the DI wiring all compose correctly in a single boot.
+**Run it.**
+
+```bash
+uv run --extra dev pytest tests/test_app_context_integration.py -q
+```
+
+Expected output:
+
+```text
+. [100%]
+1 passed in 0.15s
+```
+
+One test, but the heaviest one in the suite: it actually started the framework. If
+the DI scan missed a bean, an auto-configuration mis-wired, or the `@transactional`
+boundary failed to commit, this is the test that catches it — which is exactly why it
+sits at the peak of the pyramid and why there is only one of it.
+
+*What just happened.* The environment-variable override is the load-bearing trick.
+The framework reads `pyfly.data.relational.url` from config during relational
+auto-configuration, and PyFly maps any config key to a `PYFLY_*` environment variable
+(dots and dashes become underscores, uppercased), so `PYFLY_DATA_RELATIONAL_URL`
+overrides the `url` in `pyfly.yaml`. Setting it with `monkeypatch` *before*
+`app.startup()` is what redirects the whole booted application to a throwaway
+database — and `monkeypatch` undoes the change when the fixture tears down, so no
+other test is affected.
+
+!!! tip "A dedicated test profile (v26.6.110)"
+ Setting one variable is fine for a single override. When a project needs a whole
+ block of test-only settings, PyFly's **profile** mechanism (Spring parity) is
+ cleaner: drop a `pyfly-test.yaml` next to `pyfly.yaml` with your test overrides,
+ then activate it by setting `PYFLY_PROFILES_ACTIVE=test` (or
+ `pyfly.profiles.active: test` in config). On boot, PyFly overlays
+ `pyfly-test.yaml` on top of the base `pyfly.yaml`, so values like the database
+ URL or `ddl-auto` apply only under that profile. Lumen does not need a profile —
+ one env override covers its single test-only setting — but reach for one as the
+ test configuration grows.
+
!!! spring "Spring parity"
This test is the Python equivalent of `@SpringBootTest` with an embedded H2
database. `@SpringBootTest` loads the full application context, including all
@@ -932,11 +1325,26 @@ async def test_wallet_round_trip_against_real_postgres():
Lumen does not use these helpers — SQLite covers the persistence layer without Docker, and the in-memory bus covers event routing. Reach for them when your project has infrastructure that cannot be reproduced without a real daemon.
+**Run it.** You have now walked every layer file by file. Run the whole suite one more
+time to confirm the full pyramid is green together:
+
+```bash
+uv run --extra dev pytest -q
+```
+
+Expected output — the same `41 passed` you started with, now with a mental model of
+exactly what each dot proves:
+
+```text
+......................................... [100%]
+41 passed in 0.28s
+```
+
---
## What you built {.recap}
-Lumen now has 41 passing tests across six files, exercising every layer of the pyramid.
+The six test files this chapter built add up to 26 passing tests, exercising every layer of the pyramid. Together with the saga tests from Chapter 12 and the event-sourcing tests from Chapter 9, Lumen's full suite is **41 passing tests** — the count you saw when you ran `uv run --extra dev pytest -q` at the start.
At the base, `test_money.py` and `test_wallet_aggregate.py` prove the domain model's arithmetic, immutability, and invariant rules. All tests are synchronous, pure Python functions — no fixtures, no DI, no `async`. The `BusinessRuleViolation.rule` attribute makes each assertion specific to the exact violated invariant.
@@ -976,6 +1384,12 @@ Concretely, you learned:
- **`monkeypatch.setenv`** — override configuration before booting the
context in integration tests; the framework reads environment variables
during auto-configuration.
+- **`PYFLY_*` config overrides** — every config key maps to an environment
+ variable (`pyfly.data.relational.url` → `PYFLY_DATA_RELATIONAL_URL`); set it
+ with `monkeypatch.setenv` before booting to redirect the whole application.
+- **Test profile (v26.6.110)** — for a block of test-only settings, add a
+ `pyfly-test.yaml` overlay and activate it with `PYFLY_PROFILES_ACTIVE=test`
+ (Spring `application-test.yaml` parity).
- **Framework helpers** (`PyFlyTestCase`, `mock_bean`, `create_test_container`,
Testcontainers) — available in `pyfly.testing` for projects that need them;
Lumen keeps things simple with real components.
diff --git a/book/manuscript/17-scheduling-notifications.md b/book/manuscript/17-scheduling-notifications.md
index fa72990f..5c16c314 100644
--- a/book/manuscript/17-scheduling-notifications.md
+++ b/book/manuscript/17-scheduling-notifications.md
@@ -21,6 +21,19 @@ Install the two optional extras before you start:
uv add "pyfly[scheduling,notifications]"
```
+!!! note "New term: optional extras"
+ An *extra* is an opt-in slice of a package's dependencies. `pyfly` keeps
+ its core lean and ships heavier capabilities — scheduling, notifications,
+ and the rest — behind named extras so you only install what you use.
+ `pyfly[scheduling,notifications]` pulls in both. The square-bracket syntax
+ is standard Python packaging; `uv add` records it in your `pyproject.toml`
+ so the next `uv sync` reinstalls them. If you later see `ModuleNotFoundError`
+ for `croniter` or a notifications provider, you skipped this line — re-run it.
+
+This chapter targets PyFly **v26.6.110**. Every code listing below matches the
+real Lumen source under `samples/lumen/src/lumen`, and every framework API was
+checked against `pyfly` itself, so what you build here runs unchanged.
+
---
## Scheduled tasks
@@ -40,6 +53,30 @@ arrive from partners; outbound callbacks close the feedback loop.
**`@scheduled`** marks any `async` method on a `@service` bean for periodic execution. It accepts exactly one *trigger*: `fixed_rate`, `fixed_delay`, or `cron`. Providing zero or more than one trigger raises a `ValueError` at decoration time, so mistakes surface at startup rather than silently at three in the morning.
+!!! note "New term: trigger"
+ A *trigger* is the rule that decides *when* a scheduled method runs. You
+ pick exactly one: `cron` (a calendar expression like "every day at 02:00"),
+ `fixed_rate` (a steady interval such as "every 10 seconds"), or `fixed_delay`
+ (a gap measured after each run finishes). One method, one trigger.
+
+Let us build the nightly rollup one decision at a time.
+
+**Step 1 — Create the service file.** In the Lumen tree, add `daily_rollup.py`
+under a `ledger` package. The class is an ordinary `@service` — a plain Python
+class that PyFly registers in its dependency-injection container and constructs
+for you. Because it is a managed bean, you can ask for the `WalletRepository` in
+the constructor and the framework hands it over; you never call `new` yourself.
+
+**Step 2 — Pick the trigger.** This job must run once a night, on the clock, so
+the trigger is `cron`. The expression `"0 2 * * *"` reads field-by-field as
+*minute 0, hour 2, every day-of-month, every month, every day-of-week* — i.e.
+02:00 every day.
+
+**Step 3 — Write the work.** Inside the method, load every wallet, sum the
+persisted `balance_minor` integers, and (for now) log the total. In production
+you would write the snapshot to a reporting table or ship it downstream; logging
+keeps the example focused on the *scheduling*, not the bookkeeping.
+
::: listing lumen/ledger/daily_rollup.py | Listing 17.1 — Nightly wallet balance rollup with @scheduled
from datetime import timedelta
@@ -80,6 +117,46 @@ That is all the wiring Lumen needs. With `pyfly[scheduling]` installed, `Schedul
No `SchedulerManager` required.
+!!! note "New term: auto-configuration"
+ *Auto-configuration* is PyFly noticing what is on your classpath and wiring
+ the matching machinery for you. `SchedulingAutoConfiguration` only activates
+ when `croniter` (pulled in by the `scheduling` extra) is importable — so the
+ scheduler appears the moment you install the extra and stays absent
+ otherwise. This is the same "convention over configuration" idea Spring Boot
+ made famous; you can always override a bean by declaring your own.
+
+**Run it.** Waiting until 02:00 to see your first tick is no fun, so temporarily
+change the trigger to fire every minute — `@scheduled(cron="* * * * *")` — and
+start the app from the `samples/lumen` directory:
+
+```bash
+uv run pyfly run --server uvicorn
+```
+
+At the top of the next minute you should see your rollup line in the logs (an
+empty database simply reports zero wallets):
+
+```text
+[rollup] 0 wallets, total 0.00 (minor units: 0)
+```
+
+Open a wallet and deposit into it (see the curl recipes in Chapter 7), wait for
+the next minute, and the totals move:
+
+```text
+[rollup] 1 wallets, total 15.00 (minor units: 1500)
+```
+
+Stop the app with Ctrl-C and **change the trigger back to `"0 2 * * *"`** before
+committing — the every-minute cron was only a probe.
+
+!!! note "What just happened"
+ You did not start a thread, open an event loop, or register a timer. You
+ wrote one `@service` with one `@scheduled` method, and the framework
+ discovered it at startup, computed the next fire time from the cron
+ expression, slept until then, and ran your coroutine — repeating forever.
+ The scheduler is *declarative*: you state *when*, PyFly handles *how*.
+
### fixed_rate vs. fixed_delay
**`fixed_rate`** measures from the **start** of one execution to the start of the next. **`fixed_delay`** measures from the **end** of one execution to the start of the next. Use `fixed_rate` for heartbeats and metrics where you need a steady cadence regardless of execution time. Use `fixed_delay` when you need a guaranteed breathing gap — for example, when polling an upstream API that rate-limits on request frequency.
@@ -133,6 +210,27 @@ def preview_rollup_schedule(expression: str, n: int = 5) -> list[str]:
return [str(t) for t in cron.next_n_fire_times(n)]
:::
+**Run it.** `CronExpression` needs no running app, so the fastest way to build
+intuition is the REPL. From `samples/lumen`:
+
+```bash
+uv run python -c "from pyfly.scheduling import CronExpression; \
+print(*CronExpression('0 2 * * *').next_n_fire_times(3), sep='\n')"
+```
+
+You should see the next three 02:00 instants, one per line (your dates will
+differ):
+
+```text
+2026-06-16 02:00:00+00:00
+2026-06-17 02:00:00+00:00
+2026-06-18 02:00:00+00:00
+```
+
+Notice the `+00:00` — fire times are UTC unless you pass a `zone` (covered
+next). This is also the cleanest way to sanity-check a user-supplied expression
+before you store it: an invalid string raises `ValueError` immediately.
+
`CronExpression` accepts both the standard 5-field format (`min hour dom month dow`) and the Spring-style 6-field format with seconds first (`sec min hour dom month dow`). The Spring `?` wildcard is normalised to `*` transparently.
| Expression | Fires |
@@ -249,12 +347,29 @@ Under the hood `@async_method` sets `__pyfly_async__ = True` on the function; th
pyfly:
scheduling:
enabled: true # set false to disable all loops
- thread-pool:
- max-workers: 4 # threads for ThreadPoolTaskExecutor
+ executor:
+ type: asyncio # 'asyncio' (default, in-loop) or 'thread'
+ max-workers: 4 # worker threads when type is 'thread'
+ lock:
+ provider: none # none | memory | redis | postgres
```
When `enabled` is `false`, `TaskScheduler` starts no loops and all `@scheduled` methods are silently skipped.
+The `executor.type` chooses how each tick runs. The default `asyncio` runs the
+coroutine on the application event loop — ideal for short, I/O-bound jobs like
+the rollup. Switch to `thread` (a pool of `executor.max-workers` threads) when a
+job does heavy CPU work or calls a blocking library, so it cannot stall the loop.
+
+!!! tip "Choosing a lock provider"
+ `lock.provider` selects the backend behind `@scheduled(lock=...)`, described
+ next: `none` (the default — no coordination), `memory` (mutual exclusion
+ within one process), `redis`, or `postgres` (true cross-instance
+ coordination with no code change). On `redis`/`postgres` PyFly builds the
+ `DistributedLock` bean for you from `pyfly.scheduling.lock.redis.url` or the
+ app's existing `AsyncEngine`; the hand-rolled `@bean` in Listing 17.4 is the
+ do-it-yourself alternative when you need custom semantics.
+
---
## Notifications
@@ -263,6 +378,14 @@ Lumen needs to tell customers that their money has arrived — email for the bal
PyFly's notifications module defines three **port protocols** and three **default services**. Your business logic depends on the protocols; the concrete provider adapters — SMTP, SendGrid, Twilio, Firebase — live behind the port boundary and can be swapped without touching a single line of domain code.
+!!! note "New term: port and adapter"
+ A *port* is an interface your code talks to — here, "something that can send
+ an email". An *adapter* is a concrete implementation of that port —
+ `SmtpEmailProvider`, `SendGridEmailProvider`, and so on. The pattern (also
+ called *hexagonal architecture*) means your deposit logic depends only on the
+ `EmailService` port, never on a specific vendor. Swapping SMTP for SendGrid
+ is a one-line change in a configuration class; the domain code never notices.
+
### The port hierarchy
| Protocol | Service class | Method |
@@ -317,7 +440,19 @@ push = PushMessage(
### Wiring the SMTP provider
-For development and self-hosted deployments, `SmtpEmailProvider` runs `smtplib` from a thread pool so the async event loop is never blocked:
+For development and self-hosted deployments, `SmtpEmailProvider` runs `smtplib` from a thread pool so the async event loop is never blocked.
+
+**Step 1 — Build the provider as a `@bean`.** A `@configuration` class is PyFly's
+place to assemble objects the container cannot construct on its own — here, an
+SMTP client that needs a host, credentials, and TLS settings. Each `@bean`
+method returns one ready-to-use object; the framework caches it and injects it
+wherever the return type is requested.
+
+**Step 2 — Wrap it in `DefaultEmailService`.** The second `@bean` takes the
+provider and returns it as an `EmailService` — the *port* your domain code
+depends on. The declared return type matters: by returning `EmailService`, every
+class that asks for an `EmailService` receives this wrapper, and none of them
+learn that SMTP is behind it.
::: listing lumen/notifications/config.py | Listing 17.6 — SMTP provider wired as a @bean
from pyfly.container import bean, configuration
@@ -359,7 +494,24 @@ class NotificationConfig:
Lumen publishes a `FundsDeposited` domain event every time the `deposit()` command succeeds (see Chapter 8). The right place to trigger the notification is an EDA listener subscribed to that event — not the command handler itself, which keeps the deposit path free of notification concerns.
-`FundsDeposited` carries `wallet_id: str`, `amount: int` (minor units), `currency: str`, and `balance: int` (new balance, minor units). The listener converts `amount` to a display string via `amount / 100`:
+`FundsDeposited` carries `wallet_id: str`, `amount: int` (minor units), `currency: str`, and `balance: int` (new balance, minor units). The listener converts `amount` to a display string via `amount / 100`.
+
+**Step 1 — Subscribe to the event.** Stack `@event_listener(event_types=["FundsDeposited"])`
+on an `async` method of a `@service`. At startup PyFly discovers the stamped
+method and auto-subscribes it to the `EventPublisher` bus — exactly the same
+mechanism `WalletAuditListener` used back in Chapter 8. You never wire a bus by
+hand.
+
+**Step 2 — Read the payload.** The handler receives an `EventEnvelope`. Its
+`payload` is a plain dict of the event's fields, so you pull `wallet_id`,
+`amount`, `currency`, and `balance` out with `.get(...)` and coerce the amounts
+to ints. Because amounts are minor units, dividing by 100 gives the display
+value: `25000` becomes `250.00`.
+
+**Step 3 — Send through the ports.** Inject `EmailService` and `PushService` in
+the constructor and call `.send(...)` on each. Both return a `NotificationResult`
+rather than raising — a flaky provider degrades gracefully instead of crashing
+the listener.
::: listing lumen/wallet/deposit_notification_listener.py | Listing 17.7 — Notifying on FundsDeposited
from pyfly.container import service
@@ -424,6 +576,38 @@ class DepositNotificationListener:
Both calls return a `NotificationResult`; inspect the `status` field to log failures or schedule retries.
+**Run it.** You do not want a real SMTP server while developing, so swap the
+provider for the log-only `DummyEmailProvider`. In your `@configuration` class,
+return a `DummyEmailProvider` (and `DummyPushProvider`) instead of the SMTP one,
+then start the app and trigger a deposit:
+
+```bash
+uv run pyfly run --server uvicorn
+# in a second terminal, open a wallet and deposit (see Chapter 7), e.g.:
+curl -s -X POST localhost:8080/api/v1/wallets//deposit \
+ -H 'content-type: application/json' -d '{"amount":25000}'
+```
+
+The deposit publishes `FundsDeposited`, the listener fires, and the dummy
+providers log the messages they "sent":
+
+```text
+[dummy email] to=['customer@example.com'] subject=Funds received: 250.00 EUR
+[dummy push] tokens=1 title=Funds received
+```
+
+The `DummyEmailProvider` also keeps every message it received in a `.sent` list —
+which is exactly what the test in Exercise 2 asserts against, no SMTP server
+required.
+
+!!! note "What just happened"
+ The deposit command knew nothing about email. It simply did its job and
+ raised a `FundsDeposited` domain event. The notification logic lives in a
+ separate listener that *reacts* to that event, so the deposit path stays
+ clean and you can add, remove, or change notifications without touching the
+ command handler. That separation — publish a fact, let interested parties
+ react — is the whole point of event-driven architecture.
+
!!! spring "Spring parity"
`EmailService` / `SmsService` / `PushService` are the Python
equivalents of Spring's `JavaMailSender` (email) and third-party
@@ -443,6 +627,16 @@ An illustrative payment provider POSTs a `payment_intent.succeeded` event to Lum
PyFly's `pyfly.webhooks` module handles all three steps.
+!!! note "New terms: webhook, HMAC, idempotency"
+ A *webhook* is an HTTP POST that an external system sends *to you* when
+ something happens — the inbound mirror of the outbound callbacks later in
+ this chapter. Because anyone can POST to a public URL, the provider signs
+ each request with a shared secret using *HMAC* (a keyed hash); recomputing
+ the hash over the exact bytes received and comparing proves the payload is
+ genuine and untampered. *Idempotency* means "safe to receive more than
+ once": providers retry on network blips, so you store an idempotency key and
+ ignore a repeat — otherwise one card top-up could credit a wallet twice.
+
### WebhookEvent and AbstractWebhookEventListener
Every inbound event is modelled as a `WebhookEvent` dataclass:
@@ -505,7 +699,16 @@ class PaymentWebhookListener(AbstractWebhookEventListener):
### WebhookProcessor — verify, dedupe, dispatch
-**`WebhookProcessor`** wires together a signature validator, an idempotency store, and a list of listeners:
+**`WebhookProcessor`** wires together a signature validator, an idempotency store, and a list of listeners. Assemble it in a `@configuration` class so it is a
+single shared bean:
+
+- `listeners` is the list of `AbstractWebhookEventListener` subclasses to fan
+ events out to (just `PaymentWebhookListener` for now);
+- `signature_validators` maps each `source` name to the validator that proves its
+ requests are genuine — here an `HmacSignatureValidator` keyed by the webhook
+ secret your provider gave you;
+- an `event_store` (omitted here, so the default in-memory one is used) remembers
+ idempotency keys.
::: listing lumen/webhooks/processor_config.py | Listing 17.9 — Assembling WebhookProcessor
from pyfly.container import bean, configuration
@@ -537,22 +740,34 @@ class WebhookConfig:
### Handling a webhook in an HTTP handler
-Call `processor.process()` from your inbound HTTP handler. Pass the raw request body (unmodified bytes) — the validator computes the HMAC over the exact bytes received:
+Call `processor.process()` from your inbound HTTP handler. Pass the raw request body (unmodified bytes) — the validator computes the HMAC over the exact bytes received.
+
+!!! warning "Read the body as raw bytes, not parsed JSON"
+ The signature is computed over the *exact bytes* the provider sent. If you
+ parse the JSON and re-serialize it, key order or whitespace can shift and the
+ HMAC will no longer match — every legitimate request would be rejected.
+ Always pass `await request.body()` (the untouched bytes) to `process()`, as
+ the handler below does.
::: listing lumen/webhooks/payment_handler.py | Listing 17.10 — Inbound payment-provider webhook endpoint
-from pyfly.container import service
-from pyfly.web import Request, Response, router
+from pyfly.container import rest_controller
+from pyfly.web import post_mapping, request_mapping
from pyfly.webhooks import WebhookProcessor
+from starlette.requests import Request
+from starlette.responses import Response
-@service
+@rest_controller
+@request_mapping("/webhooks")
class PaymentWebhookHandler:
def __init__(self, processor: WebhookProcessor) -> None:
self._processor = processor
- @router.post("/webhooks/payment")
+ @post_mapping("/payment")
async def receive(self, request: Request) -> Response:
+ # Read the untouched bytes — the HMAC is computed over exactly
+ # what the provider sent (see the warning above).
raw_body = await request.body()
headers = {
"X-Signature": request.headers.get(
@@ -569,8 +784,8 @@ class PaymentWebhookHandler:
headers=headers,
)
except ValueError:
- return Response(status=400, body=b"invalid signature")
- return Response(status=200, body=b"ok")
+ return Response(content=b"invalid signature", status_code=400)
+ return Response(content=b"ok", status_code=200)
:::
The `process()` signature accepts `signature_header` and `idempotency_header` keyword arguments to override the default header names (`X-Signature` and `X-Idempotency-Key`).
@@ -583,6 +798,50 @@ The `process()` signature accepts `signature_header` and `idempotency_header` ke
4. If `idempotency_key` is present and already seen, the event is returned but listeners are **not** called.
5. Each listener for the source is called in registration order; if one raises, the error is logged and `on_error` is called before continuing to the next listener.
+**Run it.** Test the endpoint the way a real provider would — by signing the exact
+body. Pick the same secret you put in `HmacSignatureValidator` (`whsec_REPLACE_ME`
+in Listing 17.9), compute the HMAC with `openssl`, and POST it. Start the app
+(`uv run pyfly run --server uvicorn`), then in a second terminal:
+
+::: listing terminal | Listing 17.10a — Sign and POST a webhook
+BODY='{"type":"payment_intent.succeeded","data":{"object":{"amount_received":25000,"currency":"eur","metadata":{"wallet_id":""}}}}'
+SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "whsec_REPLACE_ME" | sed 's/^.* //')
+
+curl -s -X POST localhost:8080/webhooks/payment \
+ -H "X-Webhook-Signature: sha256=$SIG" \
+ -H "X-Idempotency-Key: evt-001" \
+ -H 'content-type: application/json' \
+ -d "$BODY"
+:::
+
+A correctly signed request returns `ok` and credits the wallet (you will see the
+`FundsDeposited` notification logs from earlier fire too):
+
+```text
+ok
+```
+
+Now prove the two guarantees. POST the **same** command again with the same
+`X-Idempotency-Key` — it still returns `ok`, but the wallet is *not* credited a
+second time (the duplicate is dropped before any listener runs). Then tamper with
+one byte of `$BODY` *without* recomputing `$SIG` and POST again — the signature
+no longer matches, so the handler returns:
+
+```text
+invalid signature
+```
+
+That is the verify-dedupe-dispatch pipeline working end to end, and it mirrors
+Exercise 3 almost exactly.
+
+!!! note "What just happened"
+ A stranger on the internet POSTed JSON to your service, and three guards ran
+ before a single line of your business logic: the signature check rejected
+ forgeries, the idempotency store rejected replays, and only then did the
+ typed listener translate the event into a CQRS `DepositFunds` command — so
+ the wallet aggregate still enforced its own invariants. You wrote the
+ `handle()` body; PyFly supplied the gauntlet around it.
+
!!! note "In-memory idempotency store"
The default `InMemoryWebhookEventStore` holds seen keys in a Python
`set`. For production clusters, implement the `WebhookEventStore`
@@ -602,9 +861,36 @@ The `process()` signature accepts `signature_header` and `idempotency_header` ke
When Lumen books a disbursement to a partner bank, that partner expects a `DisbursementSettled` POST to their webhook URL — signed, retried on failure, and auditable. PyFly's `pyfly.callbacks` module handles the outbound side.
+!!! note "New term: outbound callback"
+ A *callback* here is the reverse of the inbound webhook you just built:
+ *Lumen* is now the sender, POSTing an event *to* a partner's URL. The
+ module gives you the same trust and reliability machinery on the way out —
+ it signs each payload (so the partner can verify it), retries transient
+ failures with backoff, and records every attempt so you have an audit trail
+ when a partner asks "did you ever tell us about transaction X?".
+
### Subscriptions and config
-Each partner is modelled as a **`CallbackConfig`** — a tenant-scoped record that holds the webhook secret, event subscriptions, and retry policy:
+Each partner is modelled as a **`CallbackConfig`** — a tenant-scoped record that holds the webhook secret, event subscriptions, and retry policy.
+
+!!! note "New term: tenant"
+ A *tenant* is one isolated customer or organisation inside a shared
+ application — here, `"lumen"`. Callbacks are tenant-scoped so a multi-tenant
+ deployment can hold each tenant's partner URLs, secrets, and retry policy
+ separately and never cross the wires. With a single tenant you simply pass
+ the same `tenant_id` everywhere.
+
+**Step 1 — Describe each subscription.** A `CallbackSubscription` pairs an
+`event_type` with the `target_url` to POST it to. Use the exact event name
+(`"DisbursementSettled"`) to route one event, or `"*"` as a catch-all that
+matches every event for the tenant — handy for an audit endpoint that wants the
+full firehose.
+
+**Step 2 — Wrap them in a `CallbackConfig` and save it.** The config carries the
+shared `secret` (used to sign every payload), the retry policy (`max_attempts`,
+`backoff_ms`), and the list of subscriptions. Persist it through a
+`CallbackConfigRepository` — `InMemoryCallbackConfigRepository` for now, a
+database-backed one in production.
::: listing lumen/callbacks/register_partner.py | Listing 17.11 — Registering a partner callback
from pyfly.callbacks import (
@@ -693,6 +979,69 @@ results = await dispatcher.dispatch(
`dispatch()` returns one `CallbackExecution` record per matching subscription, each with `status`, `attempts`, `response_status`, and `delivered_at`.
+**Run it.** The dispatcher's default HTTP sender does not actually call the
+network — it logs the request it *would* make and returns `200` — which is
+perfect for seeing the wiring without standing up a partner server. Drop this
+into a script (or `uv run python`) from `samples/lumen`:
+
+::: listing lumen/callbacks/try_dispatch.py | Listing 17.12a — Dispatch against the default (log-only) sender
+import asyncio
+
+from pyfly.callbacks import (
+ CallbackConfig,
+ CallbackDispatcher,
+ CallbackSubscription,
+ InMemoryCallbackConfigRepository,
+ InMemoryCallbackExecutionRepository,
+)
+
+
+async def main() -> None:
+ configs = InMemoryCallbackConfigRepository()
+ await configs.save(CallbackConfig(
+ tenant_id="lumen",
+ name="clearance-bank",
+ secret="cb-secret-xyz",
+ subscriptions=[CallbackSubscription(
+ event_type="DisbursementSettled",
+ target_url="https://api.clearancebank.example.com/hooks/lumen",
+ )],
+ ))
+ dispatcher = CallbackDispatcher(
+ configs=configs,
+ executions=InMemoryCallbackExecutionRepository(),
+ )
+ results = await dispatcher.dispatch(
+ "lumen",
+ "DisbursementSettled",
+ {"id": "txn-009", "amount": 50_000, "currency": "EUR"},
+ )
+ for r in results:
+ print(r.status, r.attempts, r.response_status, r.target_url)
+
+
+asyncio.run(main())
+:::
+
+You should see one delivered execution, with the signed request logged just
+above it:
+
+```text
+would POST https://api.clearancebank.example.com/hooks/lumen headers={'X-Pyfly-Signature': 'sha256=...', 'Content-Type': 'application/json'} body={'id': 'txn-009', 'amount': 50000, 'currency': 'EUR'}
+DELIVERED 1 200 https://api.clearancebank.example.com/hooks/lumen
+```
+
+`DELIVERED 1 200` reads as: status `DELIVERED`, succeeded on attempt `1`, HTTP
+`200`. To send for real, pass your own `http=` sender (an `httpx`/`aiohttp` POST)
+to `CallbackDispatcher`; the signing, retry, and audit logic stay identical.
+
+!!! note "What just happened"
+ One `dispatch()` call looked up every subscription the tenant has for that
+ event type, signed the payload, POSTed it, and wrote a `CallbackExecution`
+ record for each — all without your domain service knowing how many partners
+ are listening or how retries work. Adding a partner later is just another
+ saved `CallbackConfig`; the disbursement code never changes.
+
### HMAC signing and retry logic
When `CallbackConfig.secret` is set, `CallbackDispatcher` signs the canonical JSON payload before every POST using HMAC-SHA256:
@@ -748,6 +1097,18 @@ config = CallbackConfig(
Subdomains of allowed domains are also accepted (e.g. `api.clearancebank.example.com`).
+!!! note "New term: SSRF"
+ *Server-Side Request Forgery* is an attack where a malicious value tricks
+ your server into making an HTTP request it should not — for example, a
+ partner URL pointing at `http://169.254.169.254/` (a cloud metadata
+ endpoint) to steal credentials. Because callback URLs can come from
+ partner-supplied config, the `authorized_domains` allowlist closes that door:
+ a host that is not on the list is marked `FAILED` *before* any request
+ leaves the process. To verify, add an `AuthorizedDomain` for one host, then
+ dispatch a subscription whose `target_url` points elsewhere — the returned
+ `CallbackExecution` will read `status=FAILED`, `attempts=0`, and
+ `last_error="Domain not authorized"`, and nothing is sent.
+
!!! spring "Spring parity"
PyFly's `@scheduled` / `CronExpression` / `TaskScheduler` trio
mirrors Spring's `@Scheduled` / `CronExpression` /
@@ -760,6 +1121,26 @@ Subdomains of allowed domains are also accepted (e.g. `api.clearancebank.example
---
+**Run it — confirm the suite is still green.** You added four new integration
+patterns; make sure nothing else regressed. From the `samples/lumen` directory:
+
+```bash
+uv run --extra dev pytest -q
+```
+
+You should see every existing test still pass:
+
+```text
+......................................... [100%]
+41 passed in 0.28s
+```
+
+The three exercises below add scheduling, notification, and webhook tests of
+their own — re-run this command after each to watch the count climb. Remember the
+`--extra dev` flag; the bare `uv sync` omits pytest.
+
+---
+
## What you built {.recap}
You extended Lumen into a connected system that operates independently of incoming requests:
@@ -785,9 +1166,10 @@ You extended Lumen into a connected system that operates independently of incomi
2. **Provider swap.** Replace `SmtpEmailProvider` with a
`DummyEmailProvider` in the test suite. Write a test that deposits
EUR 100 (10 000 minor units) into wallet `w-001` via the deposit
- handler, triggering a `FundsDeposited` event. Assert that
- `DummyEmailProvider.last_message` contains the wallet ID and the
- formatted amount (`100.00 EUR`) in its `body_text`.
+ handler, triggering a `FundsDeposited` event. The provider records
+ every message it received in its `.sent` list, so assert that
+ `provider.sent[-1].body_text` contains the wallet ID and the
+ formatted amount (`100.00 EUR`).
3. **Signature replay attack.** Write a test that calls
`PaymentWebhookHandler.receive()` twice with the same raw body,
diff --git a/book/manuscript/18-production.md b/book/manuscript/18-production.md
index b7bab409..a5971b1b 100644
--- a/book/manuscript/18-production.md
+++ b/book/manuscript/18-production.md
@@ -10,6 +10,23 @@ This final chapter is about the distance between "it works on my laptop" and "it
You will move quickly. Every section picks one topic, shows the minimal working API, and connects it to Lumen. By the end you will have a complete picture of the PyFly ecosystem and a production checklist worth keeping close.
+!!! note "Conventions in this chapter"
+ The listings and config keys here target PyFly **v26.6.110**. Two
+ deployment facts from that release run through the whole "Going to
+ production" section, so it helps to know them up front:
+
+ - The application listens on `pyfly.server.port` (default `8080`), the
+ Spring `server.port` parity key. The old `pyfly.web.port` /
+ `PYFLY_WEB_PORT` keys were removed in v26.6.102.
+ - The Actuator and Admin Dashboard run on a **separate management port**
+ (`pyfly.management.server.port`, default `9090`), open and
+ unauthenticated by default. We cover this in detail when we wire up
+ health probes.
+
+ Each feature below is built the same way: a short "why", the code, then a
+ **Run it** checkpoint that shows the exact command and the output you
+ should see. Type the commands as you go — that is how the ideas stick.
+
---
## Plugins and extension points
@@ -20,6 +37,18 @@ The core framework is intentionally small. Optional features — formatters, aud
PyFly's `pyfly.plugins` module mirrors Spring's plugin registry: you declare an **extension point** (a named slot), **extensions** (concrete contributions), and bundle them into a **plugin** with a lifecycle.
+New jargon, in plain terms: an **extension point** is a labelled hole in your application — "anything that wants to be an audit sink plugs in here." An **extension** is one thing that fills the hole. A **plugin** is the package that ships one or more extensions together and can be started and stopped as a unit. If you have ever defined a Java interface and let callers register implementations of it, you already know the shape — the decorators below just make the wiring declarative.
+
+We will build the smallest useful example: a console audit sink that prints every event it is handed.
+
+**Step 1 — Declare the extension point.** This is the contract. Every audit sink must promise a `record(event)` method. The `id="audit-sinks"` string is the name other code uses to find every sink later.
+
+**Step 2 — Write a plugin that contributes one sink.** The `@plugin` decorator wraps a class with a mandatory `id` and `version`; the inner `@extension` class is the actual contribution. It inherits the extension-point interface (`AuditSink`) so the registry can confirm it honours the contract.
+
+**Step 3 — Give the plugin a lifecycle.** The `start` and `stop` methods are where you open and close resources (a file handle, a network connection). The plugin manager calls them for you.
+
+Here are all three steps in one file.
+
::: listing lumen/plugins/audit.py | Listing 18.1 — Declaring an audit-sink plugin
from pyfly.plugins import (
PluginManager,
@@ -82,6 +111,36 @@ asyncio.run(main())
`PluginManager.add()` inspects the class for nested `@extension_point` declarations, then registers each `@extension` contribution. `start_all()` invokes each plugin's `init` then `start` hooks in dependency order; `stop_all()` reverses the sequence, calling `stop` then `unload`. Circular dependencies raise `PluginResolutionError` before any code runs.
+!!! tip "Run it"
+ Save both listings under `src/lumen/plugins/` and run the runner module
+ directly:
+
+ ```bash
+ uv run python -m lumen.plugins.runner
+ ```
+
+ You should see the lifecycle hooks fire, the single event get recorded,
+ and the clean shutdown:
+
+ ```
+ ConsoleAuditPlugin started
+ [AUDIT] {'action': 'deposit', 'amount_minor': 100}
+ ConsoleAuditPlugin stopped
+ ```
+
+ The order is the whole point: `start` runs before any sink is used, your
+ code iterates the registered sinks, and `stop` runs last. If you add a
+ second plugin later, `start_all()` boots both in dependency order and
+ `stop_all()` shuts them down in reverse — you never manage that ordering
+ by hand.
+
+**What just happened.** You added a capability to the application — audit
+recording — without editing a single line of framework code. The framework
+discovered your plugin, validated that its extension honours the
+`AuditSink` contract, ran its lifecycle, and handed you the registered sinks
+to call. That is the core promise of a plugin system: open for extension,
+closed for modification.
+
| Method | Description |
|---|---|
| `await manager.add(cls)` | Scan and register a plugin class |
@@ -105,8 +164,14 @@ Most real-world services carry logic that belongs to the business, not the code:
PyFly's `pyfly.rule_engine` gives product owners a YAML dial they can turn without touching source code.
+A **rule engine**, in plain terms, is a small interpreter for "if this, then that" statements that live in data rather than code. You feed it a bag of facts (the *context*) and a set of rules; it checks each rule's condition against the facts and, for the ones that match, performs the listed actions — usually writing a flag back into the context. The win is that the *rules* are editable by non-programmers, while the *engine* that runs them is fixed and tested.
+
### Defining rules in YAML
+We will build a fraud-and-limit check in two steps: first write the rules as data, then wire a service that runs them.
+
+**Step 1 — Write the rules as YAML.** Each rule names a `when` condition and a list of `then` actions. Because the rules are plain data, a product owner can review them in a pull request and a config server can hot-swap them at runtime.
+
Rules live in a separate YAML file that any team member can review. The evaluator parses this file once at startup — or on each fetch if you hot-reload from a Config Server (see the next section).
::: listing lumen/rules/transaction_rules.yaml | Listing 18.3 — Fraud and daily-limit rules (amounts in minor units)
@@ -161,7 +226,7 @@ Each rule has a `when` condition and a list of `then` actions. Amounts are alway
Actions are `set` (write to a context path), `increment`, or `log`. Subclass `RuleEvaluator` and override `_execute_action` to add `call`, `calculate`, or any custom verb.
-### Evaluating rules in a service
+**Step 2 — Wire a service that loads and runs the rules.** The service parses the YAML once at construction, then exposes an `assess()` method that builds a context, runs the evaluator, and returns the flags the rules set.
::: listing lumen/rules/risk_service.py | Listing 18.4 — Evaluating rules against a transaction
from pathlib import Path
@@ -201,6 +266,29 @@ class RiskService:
**How it works.** `RuleSetLoader.from_yaml(text)` parses the YAML into an AST. `RuleSetEvaluator.evaluate(ruleset, ctx)` walks every rule in priority order, evaluates the `when` clause, and applies matching `then` actions — mutating `ctx` in place and returning a `list[EvaluationResult]`. The `flags` dict is the authoritative output: a downstream handler rejects, queues, or flags the transaction based on whatever keys are set. `amount` and `daily_total` are in minor units (cents) to match the Lumen domain.
+!!! tip "Run it"
+ Exercise the service from a Python REPL to see the rules fire. A
+ €6,000.00 transfer (`600000` minor units) trips both the high-value and
+ daily-limit thresholds:
+
+ ```bash
+ uv run python -c "
+ from lumen.rules.risk_service import RiskService
+ print(RiskService().assess(amount=600000, daily_total=600000, country='US'))
+ "
+ ```
+
+ Expected output — the flags the matching rules set, and nothing else:
+
+ ```python
+ {'high_value': True, 'limit_exceeded': True}
+ ```
+
+ Now drop the amount to `50000` (€500.00) with a clean country and you get
+ back an empty `{}` — no rule matched, so nothing was flagged. You changed
+ the *outcome* without touching any Python: that is the dial the YAML gives
+ your product owners.
+
::: figure art/figures/18-production.svg | Figure 18.1 — Rule evaluation at the service boundary. YAML rules are parsed once at startup; each transaction passes through the evaluator as a mutable context dict.
!!! tip "Hot-reload rules without redeployment"
@@ -214,6 +302,8 @@ class RiskService:
As Lumen grows to multiple services, each carries its own copy of database URLs, timeouts, and feature flags. The Config Server module removes that duplication: one service owns the truth; every other service fetches on startup.
+A **config server**, in plain terms, is a small HTTP service whose entire job is to hand out configuration. Instead of baking timeouts and URLs into each service's own `pyfly.yaml`, you store them in one place and every service asks for its bundle at boot. Change the value once, restart (or refresh) the consumers, and the whole fleet moves together.
+
### Running the server
Enable the server in `pyfly.yaml`:
@@ -266,6 +356,34 @@ async def seed() -> None:
asyncio.run(seed())
:::
+!!! tip "Run it"
+ With `pyfly.config-server.enabled: true` in `pyfly.yaml`, start the app
+ and curl the bundle you seeded. Remember: the config-server routes are
+ served on the **application** port (`8080`), not the management port.
+
+ ```bash
+ uv run pyfly run
+ # in another terminal:
+ curl http://localhost:8080/wallet/prod
+ ```
+
+ The response is Spring Cloud Config-shaped — your seeded keys arrive
+ inside a `propertySources` array:
+
+ ```json
+ {
+ "name": "wallet",
+ "profiles": ["prod"],
+ "propertySources": [
+ {"name": "wallet-prod", "source": {"db.url": "postgres://db:5432/lumen", "cache.ttl": 30}}
+ ]
+ }
+ ```
+
+ Because the shape matches Spring Cloud Config, an existing Spring Boot
+ service can point its `spring.config.import=configserver:` at this same
+ URL and consume it unchanged.
+
Client services fetch on startup with:
::: listing lumen/config/bootstrap.py | Listing 18.6 — Fetching remote config at startup
@@ -297,6 +415,8 @@ async def load_remote() -> dict:
Lumen's error messages and notifications currently live as Python string literals. When users speak different languages, that approach does not scale.
+**i18n** is shorthand for *internationalisation* (the 18 letters between the "i" and the "n"). In practice it means pulling every user-facing string out of your code into per-language **resource bundles**, then choosing the right bundle at runtime based on the caller's preferred language. Your code refers to a string by a stable key like `wallet.deposit_ok`; the framework looks up the translation.
+
Enable the i18n subsystem with a single flag:
```yaml
@@ -309,6 +429,8 @@ pyfly:
### Writing resource bundles
+**Step 1 — Write one bundle per language.** Files are named `messages_.yaml`. Keys are shared across languages; only the values change. The `{0}`, `{1}` markers are positional placeholders the framework fills in at render time.
+
```yaml
# i18n/messages_en.yaml
wallet:
@@ -325,6 +447,8 @@ wallet:
### Using MessageSource in a service
+**Step 2 — Inject `MessageSource` and resolve the locale from the request.** The service below reads the caller's `Accept-Language` header, picks the matching bundle, and renders the message with the runtime arguments.
+
::: listing lumen/i18n/notification_service.py | Listing 18.7 — Locale-aware notification service
from pyfly.container import service
from pyfly.i18n import AcceptHeaderLocaleResolver, MessageSource
@@ -359,6 +483,37 @@ class NotificationService:
`AcceptHeaderLocaleResolver` parses the `Accept-Language` header and returns the highest-`q` primary subtag. Use `FixedLocaleResolver` for single-language deployments or tests. Auto-configuration registers both when `pyfly.i18n.enabled: true`; inject either `MessageSource` (the port protocol) or the concrete `ResourceBundleMessageSource` — both work.
+!!! tip "Run it"
+ The fastest way to prove the lookup works is a test that resolves the
+ bundle directly — no HTTP server required. Save Listing 18.7a under
+ `tests/`, then run just this test:
+
+ ```bash
+ uv run --extra dev pytest tests/test_messages.py -q
+ ```
+
+ Expected:
+
+ ```
+ 1 passed in 0.05s
+ ```
+
+ Swap `locale="es"` for `locale="en"` and the assertion would need the
+ English string instead — same key, different bundle. That is the whole
+ point of i18n: your code never changes, only the resolved locale does.
+
+::: listing tests/test_messages.py | Listing 18.7a — Asserting a translated message
+from pyfly.i18n.adapters.resource_bundle import ResourceBundleMessageSource
+
+
+def test_deposit_message_in_spanish() -> None:
+ messages = ResourceBundleMessageSource(base_path="i18n/", default_locale="en")
+ text = messages.get_message(
+ "wallet.deposit_ok", args=(100, "w-001"), locale="es"
+ )
+ assert text == "Se depositaron 100 unidades menores en la billetera w-001."
+:::
+
!!! spring "Spring parity"
`MessageSource`, `ResourceBundleMessageSource`,
`AcceptHeaderLocaleResolver`, and `FixedLocaleResolver` are
@@ -372,6 +527,8 @@ class NotificationService:
The Lumen admin dashboard currently polls for balance changes. A WebSocket endpoint eliminates the poll — the server pushes an update the instant a deposit commits.
+A **WebSocket** is a two-way connection that stays open. A normal HTTP request is one-shot: the client asks, the server answers, the line closes. With a WebSocket the line stays up, so the *server* can send data whenever it likes — perfect for live updates. The URL scheme is `ws://` (or `wss://` over TLS) instead of `http://`.
+
::: listing lumen/web/balance_ws_controller.py | Listing 18.8 — Live balance feed via WebSocket
import asyncio
@@ -410,6 +567,29 @@ class BalanceFeedController:
**How it works.** `@websocket_mapping("/balance/{wallet_id}")` mounts the endpoint at `ws:///ws/balance/{wallet_id}`. The full path is the controller's `@request_mapping` base (`/ws`) concatenated with the decorator's path.
+!!! tip "Run it"
+ Start the app, then open the live feed with any WebSocket client. Using
+ `websocat` (`brew install websocat`):
+
+ ```bash
+ uv run pyfly run
+ # in another terminal:
+ websocat ws://localhost:8080/ws/balance/w-001
+ ```
+
+ You should see a JSON frame arrive roughly once a second, pushed by the
+ server without you asking again:
+
+ ```json
+ {"wallet_id": "w-001", "balance_minor": 5000}
+ {"wallet_id": "w-001", "balance_minor": 5000}
+ ```
+
+ Deposit into `w-001` from another terminal and watch the `balance_minor`
+ value jump on the next frame — no polling, no refresh. Press `Ctrl+C` to
+ close; the controller's `on_disconnect` runs and the session is dropped
+ from the broadcast set.
+
`WebSocketSession` exposes the connection lifecycle:
| Method | Description |
@@ -437,6 +617,8 @@ The optional `on_disconnect` method is invoked automatically by the registrar af
Not every feature lives behind an HTTP endpoint. Database seed scripts, one-time data migrations, and scheduled batch jobs are better expressed as CLI commands that run inside the same DI container — sharing services, configuration, and repositories with the main application.
+The key idea here: a **shell command** is just a method that runs from the terminal but still has full access to your application's wired services. You do not write a separate script that re-creates the database connection by hand — the command receives the same `WalletService` your HTTP controllers use, because it lives inside the same DI container.
+
### @shell_component and @shell_method
::: listing lumen/cli/wallet_commands.py | Listing 18.9 — DI-powered shell commands
@@ -487,6 +669,25 @@ python -m lumen wallet balance w-001
python -m lumen # no args → drops into REPL mode
```
+!!! tip "Run it"
+ Deposit 500 minor units into a wallet straight from the command line —
+ the command runs your real `WalletService` against the real database:
+
+ ```bash
+ uv run python -m lumen wallet deposit w-001 --amount 500
+ ```
+
+ Expected output (the return value of your `deposit` method, printed by
+ the shell adapter):
+
+ ```
+ New balance: 500 minor units
+ ```
+
+ Run `uv run python -m lumen wallet balance w-001` and you will see the
+ same `500` reflected back — proof that the command and the HTTP API are
+ talking to the same persistent state, not a throwaway in-memory copy.
+
### CommandLineRunner — one-shot post-startup tasks
For tasks that run once at startup — seeding, warm-up, connection checks — implement **`CommandLineRunner`**:
@@ -511,6 +712,27 @@ class SeedRunner(CommandLineRunner):
Any bean whose class implements `async def run(self, args: list[str]) -> None` structurally satisfies the `CommandLineRunner` protocol. The framework detects it via `isinstance()` (the protocol is `@runtime_checkable`) after `ApplicationReadyEvent` fires, then invokes it with the raw CLI arguments. Use `@order(n)` to control execution order when multiple runners coexist.
+!!! tip "Run it"
+ The runner fires during application startup and receives the process's
+ `sys.argv[1:]`, so launch the app through its CLI entry point with the
+ flag appended:
+
+ ```bash
+ uv run python -m lumen --seed
+ ```
+
+ After the banner and the route table, you will see the runner's
+ confirmation line:
+
+ ```
+ Default wallet ensured.
+ ```
+
+ Boot without `--seed` and the line is absent — the `if "--seed" in args`
+ guard skips the work. That is the difference between a *runner* (runs
+ every boot, you gate it yourself) and a one-off shell command (runs only
+ when you invoke its name).
+
!!! spring "Spring parity"
`@shell_component`, `@shell_method`, `@shell_option`,
`@shell_argument`, and `CommandLineRunner` are direct
@@ -526,13 +748,19 @@ Any bean whose class implements `async def run(self, args: list[str]) -> None` s
When Lumen exposes an HTTP API, downstream services should call it via a generated client — not hand-written `httpx` calls that drift out of sync. PyFly builds and serves an OpenAPI 3.1 spec automatically at `/openapi.json`.
+An **OpenAPI spec** is a machine-readable description of your HTTP API: every path, every parameter, every request and response shape. An **SDK** (software development kit) is the client library a tool generates *from* that spec — typed methods that wrap the HTTP calls for you. The chain is: your controllers → the spec → a generated client. Because each link is mechanical, the client can never silently drift out of sync with the server.
+
`OpenAPIGenerator` assembles the spec from route metadata collected by `ControllerRegistrar`:
- **Info** — populated from `title`, `version`, and `description` passed to `create_app()`.
- **Paths** — one operation per `@get_mapping` / `@post_mapping` etc., with parameters inferred from `PathVar[T]`, `QueryParam[T]`, `Header[T]`, and `Body[BaseModel]` type hints.
- **Schemas** — Pydantic models registered in `components.schemas` via `model_json_schema()` and referenced with `$ref`.
-With the spec available, generate a Python client in one command:
+With the spec available, generate a Python client in two steps — download the spec, then run the generator.
+
+**Step 1 — Download the spec from a running instance.** The spec lives on the application port (`8080`), alongside your business routes.
+
+**Step 2 — Run the OpenAPI generator** to turn that JSON into an installable Python package.
```bash
# Download the spec from a running instance
@@ -577,7 +805,9 @@ class WalletGateway:
### Packaging with Docker
-`pyfly new` generates a `Dockerfile` for every archetype. For a web service it looks like this after production hardening:
+**Containerising**, in plain terms, means freezing your app and everything it needs to run — Python, dependencies, your code, your config — into a single image that runs identically on your laptop, in CI, and in production. A `Dockerfile` is the recipe for building that image.
+
+`pyfly new` generates a `Dockerfile` for every archetype. For a web service it looks like this after production hardening. Read it top to bottom — each line is one step in the build:
```dockerfile
FROM python:3.12-slim
@@ -591,13 +821,35 @@ RUN pip install uv && \
COPY src/ src/
COPY pyfly.yaml .
-EXPOSE 8080
+# 8080 = application traffic; 9090 = the management port (actuator + admin).
+EXPOSE 8080 9090
CMD ["pyfly", "run", "--host", "0.0.0.0", \
"--port", "8080", "--server", "granian", "--workers", "2"]
```
+Walking the recipe: `FROM` picks a small Python base image; `COPY` + `uv sync` install exactly the dependency extras you name (and nothing else); the second `COPY` adds your source and config; `EXPOSE` documents the two ports the container listens on; `CMD` is the command that runs when the container starts. The `--port 8080` flag here sets `pyfly.server.port` for this process — the management port stays at its `9090` default unless you override `pyfly.management.server.port`.
+
Install only the extras your service actually uses — the `full` meta-extra pulls in Kafka, RabbitMQ, and MongoDB drivers even when you need none of them.
+!!! tip "Run it"
+ Build the image and run it, mapping both ports out of the container:
+
+ ```bash
+ docker build -t lumen:local .
+ docker run --rm -p 8080:8080 -p 9090:9090 lumen:local
+ ```
+
+ Then confirm both listeners answer — the business port on `8080` and the
+ management port on `9090`:
+
+ ```bash
+ curl http://localhost:8080/openapi.json # app: returns the spec
+ curl http://localhost:9090/actuator/health # management: {"status":"UP"}
+ ```
+
+ Two ports, one process. That separation is what the rest of this section
+ builds on.
+
### Environment variables and secrets
Never bake secrets into `pyfly.yaml`. PyFly resolves `${ENV_VAR}` placeholders anywhere in configuration:
@@ -654,18 +906,48 @@ pyfly:
graceful-timeout: 30
```
+### The two-port deploy
+
+This is the deployment fact you most need to internalise for v26.6.110. PyFly runs on **two ports**, both inside one process:
+
+- the **application port** — `pyfly.server.port`, default `8080` — serves your business API, your WebSocket feeds, the OpenAPI spec, and the config-server routes;
+- the **management port** — `pyfly.management.server.port`, default `9090` — serves the Actuator (`/actuator/*`) and the Admin Dashboard (`/admin`).
+
+The management port is a second in-process listener, not extra worker processes, so it costs almost nothing. Two tuning options matter at deploy time: set `pyfly.management.server.port` **equal** to `pyfly.server.port` to collapse everything onto one port, or set it to **`-1`** to disable the management web endpoints entirely. The env override is `PYFLY_MANAGEMENT_SERVER_PORT`.
+
+Why split them? Because it lets you expose only `8080` to the internet while keeping health checks, Prometheus scrapes, and the admin console on `9090`, reachable only from inside your cluster.
+
+!!! warning "The management port is OPEN by default"
+ As of v26.6.110 the management port is **unauthenticated by default**
+ (Spring Boot's `management.server.port` model): anything that can reach
+ `9090` can read `/actuator/*` and `/admin`. That is intentional — the
+ port is meant to sit behind network isolation, never on the public
+ internet. If you cannot guarantee that isolation, apply the app's
+ security filters to the management port too:
+
+ ```yaml
+ pyfly:
+ management:
+ security:
+ enabled: true
+ ```
+
+ With that flag set, the same authentication, role guards, and CSRF rules
+ that protect your business API also gate `9090`.
+
### Health endpoints
-PyFly exposes Spring Boot-style actuator endpoints out of the box:
+PyFly exposes Spring Boot-style actuator endpoints out of the box. They live on the **management port** (`9090`):
| Endpoint | Purpose |
|---|---|
| `GET /actuator/health` | Aggregate health (UP / DOWN) |
| `GET /actuator/health/liveness` | Kubernetes liveness probe |
| `GET /actuator/health/readiness` | Kubernetes readiness probe |
-| `GET /actuator/metrics` | Prometheus-compatible metrics |
+| `GET /actuator/metrics` | Per-metric drill-down (e.g. `/actuator/metrics/http.server.requests`) |
+| `GET /actuator/prometheus` | Prometheus scrape endpoint |
-Configure them in `pyfly.yaml`:
+Only `health` and `info` are exposed over HTTP by default (Spring Boot's secure default). To publish metrics and the Prometheus scrape endpoint, add them to the exposure list in `pyfly.yaml`:
```yaml
pyfly:
@@ -673,29 +955,70 @@ pyfly:
endpoints:
web:
exposure:
- include: health,metrics
+ include: health,info,metrics,prometheus
endpoint:
health:
show-details: when-authorized
```
-Then wire your Kubernetes deployment:
+!!! tip "Run it"
+ Hit the probes on the management port — they answer immediately because
+ that port is open by default:
+
+ ```bash
+ curl http://localhost:9090/actuator/health
+ curl http://localhost:9090/actuator/health/readiness
+ ```
+
+ Expected — a JSON status object the orchestrator can parse:
+
+ ```json
+ {"status": "UP"}
+ ```
+
+ A readiness check that fails (a database still warming up, say) returns
+ `{"status": "DOWN"}` with HTTP `503`, which is exactly what Kubernetes
+ needs to hold traffic back until the pod is ready.
+
+Then wire your Kubernetes deployment — note every probe and scrape points at the **management port** `9090`, not `8080`:
```yaml
livenessProbe:
httpGet:
path: /actuator/health/liveness
- port: 8080
+ port: 9090
initialDelaySeconds: 10
periodSeconds: 15
readinessProbe:
httpGet:
path: /actuator/health/readiness
- port: 8080
+ port: 9090
initialDelaySeconds: 5
periodSeconds: 10
```
+!!! spring "Spring parity"
+ The two-port split is a direct port of Spring Boot's
+ `management.server.port`: app traffic on `server.port`, actuator and
+ management UI on a dedicated `management.server.port`. The open-by-default
+ posture, the `-1`-to-disable convention, and `management.security.enabled`
+ to lock it down all mirror Spring Boot's behaviour.
+
+!!! note "Custom probes from the live HealthAggregator"
+ New in v26.6.110, the live `HealthAggregator` is reachable at
+ `app.state.pyfly_health_aggregator` (Starlette adapter only). Register an
+ extra readiness indicator after `create_app()` — for example a check that
+ pings a downstream service — and it shows up on `/actuator/health`
+ regardless of whether the actuator runs on the shared or the separate
+ management port.
+
+**What just happened.** You now have the full shape of a PyFly deployment:
+one container, two ports (`8080` for users, `9090` for ops), secrets injected
+as environment variables, a Granian server tuned with explicit workers, a
+graceful-shutdown window that drains in-flight requests, and Kubernetes
+probes wired to the management port. The checklist below is the same picture
+as a list you can paste into a pull-request template.
+
### The production checklist
- [ ] All secrets are environment variables — none are in `pyfly.yaml`
@@ -705,9 +1028,14 @@ readinessProbe:
explicitly (not left at `1` for multi-core machines).
- [ ] `graceful-timeout` is at least 15 s; Kubernetes
`terminationGracePeriodSeconds` is at least 5 s more.
-- [ ] Liveness and readiness probes are configured and tested.
-- [ ] `/actuator/health` returns UP before traffic is sent.
-- [ ] Prometheus metrics endpoint is scraped by the monitoring stack.
+- [ ] Liveness and readiness probes point at the **management port**
+ (`9090`), not the application port, and are tested.
+- [ ] `/actuator/health` (on `9090`) returns UP before traffic is sent.
+- [ ] The management port is network-isolated, or
+ `pyfly.management.security.enabled: true` is set — it is open by
+ default.
+- [ ] The Prometheus scrape endpoint (`/actuator/prometheus` on `9090`) is
+ added to the exposure list and scraped by the monitoring stack.
- [ ] Structured logging is enabled (`pyfly[observability]`) and
log level is `INFO` in production, not `DEBUG`.
- [ ] OpenTelemetry exporter is pointed at the production collector.
@@ -735,7 +1063,7 @@ Seventeen chapters ago you typed `@pyfly_application` and watched the DI contain
**Chapters 16–17** closed the feedback loop. A structured test suite — unit, integration, and Testcontainers-backed persistence tests — made the platform safe to change. Scheduled tasks, push notifications, webhooks, and callbacks let Lumen reach out to the world on its own schedule.
-**Chapter 18** showed you what lies beyond the core: a plugin system for open extension, a YAML rule engine for business-owned logic, a Config Server for fleet-wide configuration, i18n for global audiences, WebSocket for real-time UX, a Shell module for operational tooling, an OpenAPI spec that generates typed client SDKs automatically, and the production habits that keep all of it running.
+**Chapter 18** showed you what lies beyond the core: a plugin system for open extension, a YAML rule engine for business-owned logic, a Config Server for fleet-wide configuration, i18n for global audiences, WebSocket for real-time UX, a Shell module for operational tooling, an OpenAPI spec that generates typed client SDKs automatically, and the production habits that keep all of it running — packaged as one container that listens on two ports, `8080` for users and `9090` for operations.
PyFly is not magic. Every abstraction in this book has a cost, and you now understand what that cost is: a DI container that starts in milliseconds but requires you to think about bean scopes; an async HTTP server that handles thousands of concurrent connections but requires you to avoid blocking calls; a saga engine that survives partial failures but requires you to write compensating transactions.
diff --git a/pyproject.toml b/pyproject.toml
index 63adea62..e23d62ab 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -7,7 +7,7 @@ name = "pyfly"
# CalVer YY.MM.PATCH — package metadata uses PEP 440 normalized form (26.5.4);
# git tag, GitHub release and human-readable display use leading-zero form
# (v26.05.04) to match the Java/.NET/Go siblings.
-version = "26.6.110"
+version = "26.6.111"
description = "The official Python implementation of the Firefly Framework — DI, CQRS, EDA, hexagonal architecture, and more."
readme = "README.md"
license = "Apache-2.0"
diff --git a/src/pyfly/__init__.py b/src/pyfly/__init__.py
index 127f2b52..82f07d35 100644
--- a/src/pyfly/__init__.py
+++ b/src/pyfly/__init__.py
@@ -13,4 +13,4 @@
# limitations under the License.
"""PyFly — Enterprise Python Framework."""
-__version__ = "26.06.110"
+__version__ = "26.06.111"
diff --git a/src/pyfly/cli/templates/pyfly.yaml.j2 b/src/pyfly/cli/templates/pyfly.yaml.j2
index 7568bc49..c4f67207 100644
--- a/src/pyfly/cli/templates/pyfly.yaml.j2
+++ b/src/pyfly/cli/templates/pyfly.yaml.j2
@@ -8,7 +8,6 @@ pyfly:
{% if has_web or has_fastapi or archetype in ("web-api", "fastapi-api", "web", "hexagonal", "core") %}
web:
- port: 8080
{% if has_fastapi or archetype == "fastapi-api" %}
adapter: fastapi
{% else %}
@@ -19,6 +18,9 @@ pyfly:
{% if has_web or has_fastapi %}
server:
type: "auto"
+ # The application HTTP port (Spring `server.port` parity). The legacy
+ # `pyfly.web.port` was removed in v26.06.102; use `pyfly.server.port`.
+ port: 8080
event-loop: "auto"
workers: 0
{% if has_granian %}