Metadata-Version: 2.4
Name: snakeboot
Version: 0.11.1
Summary: Spring Boot ergonomics for hexagonal Python: @transactional, application events, a component scan, typed configuration with profiles, singleton REST controllers on FastAPI and Spring Data repositories on SQLAlchemy, wired by wireup.
Keywords: spring-boot,hexagonal-architecture,ddd,spring-data,fastapi,sqlalchemy,wireup,dependency-injection,transactional
Author: Wouter Deketelaere
Author-email: Wouter Deketelaere <wouter.deketelaere@kdg.be>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Dist: wireup>=2.13.1
Requires-Dist: pydantic-settings>=2.16.0,<3 ; extra == 'cache'
Requires-Dist: redis>=8.1.0 ; extra == 'cache'
Requires-Dist: pydantic-settings>=2.16.0,<3 ; extra == 'configuration'
Requires-Dist: pydantic-settings>=2.16.0,<3 ; extra == 'data'
Requires-Dist: sqlalchemy>=2.1.8 ; extra == 'data'
Requires-Dist: alembic>=1.20.1 ; extra == 'data'
Requires-Dist: psycopg[binary]>=3.3.8 ; extra == 'data'
Requires-Dist: pydantic-settings>=2.16.0,<3 ; extra == 'oauth2'
Requires-Dist: pyjwt[crypto]>=2.10.1 ; extra == 'oauth2'
Requires-Dist: pydantic-settings>=2.16.0,<3 ; extra == 'rabbitmq'
Requires-Dist: pika>=1.3.2 ; extra == 'rabbitmq'
Requires-Dist: httpx2>=2.16.0 ; extra == 'testing'
Requires-Dist: pgvector>=0.5.1 ; extra == 'vector'
Requires-Dist: pydantic-settings>=2.16.0,<3 ; extra == 'web'
Requires-Dist: fastapi>=0.162.2 ; extra == 'web'
Requires-Dist: uvicorn>=0.54.0 ; extra == 'web'
Requires-Python: >=3.13
Project-URL: Homepage, https://github.com/KdG-OCDI/snakeboot
Project-URL: Repository, https://github.com/KdG-OCDI/snakeboot
Project-URL: Issues, https://github.com/KdG-OCDI/snakeboot/issues
Project-URL: Changelog, https://github.com/KdG-OCDI/snakeboot/blob/main/CHANGELOG.md
Provides-Extra: cache
Provides-Extra: configuration
Provides-Extra: data
Provides-Extra: oauth2
Provides-Extra: rabbitmq
Provides-Extra: testing
Provides-Extra: vector
Provides-Extra: web
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/KdG-OCDI/snakeboot/main/docs/logo.png" alt="snakeboot: a snake coiled into a boot" width="320">
</p>

# snakeboot

Spring Boot ergonomics for hexagonal Python applications, wired by [wireup](https://github.com/maldoinc/wireup),
with FastAPI, SQLAlchemy and Alembic underneath.

snakeboot imitates the basics of Spring Boot, not Spring itself. Each part is a handful of small
classes you can read in an afternoon, and none of them knows anything about your domain.

An application speaks snakeboot, never the frameworks underneath: its entry points, controllers, entities,
repositories, migrations, commands, listeners, configuration and tests import nothing of FastAPI, Starlette,
SQLAlchemy or Alembic. snakeboot binds them, so another framework means another binding, not other applications.

| snakeboot | Spring Boot | Needs |
|---|---|---|
| `@transactional`, `after_commit` | `@Transactional`, `@TransactionalEventListener(AFTER_COMMIT)` | nothing |
| `@application_root`, `ComponentScan` | `@SpringBootApplication`, `@ComponentScan` | nothing |
| `ApplicationEventPublisher`, `@event_listener`, `@transactional_event_listener` | the same names | wireup |
| `@application_module_listener`, the event publication registry | Spring Modulith's `@ApplicationModuleListener`, `EventPublicationRegistry` (a transactional outbox) | wireup; `snakeboot[data]` for the registry |
| `@configuration_properties`, `Section`, `application-<profile>.toml` | `@ConfigurationProperties`, profiles | `snakeboot[configuration]` |
| `ServerProperties`, `DatabaseProperties`, `CacheProperties` | `server.*`, `spring.datasource.*`, `spring.data.redis.*` | `snakeboot[configuration]` |
| `snakeboot.boot`: `run`, `python -m myapp serve` | `SpringApplication.run`, auto-configuration, the embedded server | `snakeboot[web]` |
| `@rest_controller`, `@route.get(status=...)`, `@rest_controller_advice`, `@exception_handler` | `@RestController`, `@GetMapping`, `@ResponseStatus`, `@RestControllerAdvice`, `@ExceptionHandler` | `snakeboot[web]` |
| `Principal`, `BearerAuthentication` | `@AuthenticationPrincipal`, a `SecurityFilterChain` bean | `snakeboot[web]` |
| `@roles_allowed`, `Principal.roles`, `SecurityContext` | `@RolesAllowed`, `hasRole`, `SecurityContextHolder` | `snakeboot[web]` |
| `[cors]`, `CorsProperties` | a `CorsRegistry` | `snakeboot[web]` |
| `/health`, `/health/liveness`, `/health/readiness`, `HealthIndicator` | Actuator's health endpoint and probes, `HealthIndicator` | `snakeboot[web]` |
| `/metrics`, `MeterRegistry` | Actuator's `/actuator/prometheus`, Micrometer | `snakeboot[web]` |
| `TraceContext`, `traceparent`, `[logging] format = "ecs"` | Micrometer Tracing, structured logging | `snakeboot[configuration]` |
| `InvalidRequestError`, `RequestProblem` | `MethodArgumentNotValidException` | `snakeboot[web]` |
| `ServerSentEvents`, `ServerSentEvent` | `SseEmitter`, `ServerSentEvent` | `snakeboot[web]` |
| `@entity`, `Id`, `Column`, `Index`, `CreatedDate`, `LastModifiedDate` | `@Entity`, `@Id`, `@Column`, `@Index`, `@CreatedDate`, `@LastModifiedDate` | `snakeboot[data]` |
| `Version`, `CreatedBy`, `LastModifiedBy`, `OptimisticLockingFailureError` | `@Version`, `@CreatedBy`, `@LastModifiedBy`, `OptimisticLockingFailureException` | `snakeboot[data]` |
| `CrudRepository`, derived queries, `@query`, `@lock`, `PageRequest` | Spring Data's `CrudRepository`, query methods, `@Query`, `@Lock`, `Pageable` | `snakeboot[data]` |
| `migrate`, `make_migration`, `migrations/V1__*.sql` | Flyway | `snakeboot[data]` |
| `Vector` | Spring AI's pgvector store | `snakeboot[data,vector]` |
| `Cache`, `InMemoryCache` | Spring's `Cache`, `RedisCacheManager` | `snakeboot[cache]` for Redis |
| `JwtBearerAuthentication`, `OAuth2Properties` | `spring-boot-starter-oauth2-resource-server` | `snakeboot[oauth2]` |
| `CommandLineRunner`, `CommandLineError` | `CommandLineRunner`, Spring Shell's `@Command` | wireup |
| `Lifecycle`, `ApplicationReadyEvent`, `run_lifecycle` | `SmartLifecycle`, `ApplicationReadyEvent`, an application without the web starter | wireup |
| `@scheduled`, `SchedulingProperties` | `@Scheduled` | `snakeboot[configuration]` |
| `[events]`, `EventsProperties` | `spring.modulith.events.*` | `snakeboot[data]` |
| `@scheduler_lock` | ShedLock's `@SchedulerLock` | `snakeboot[data]` |
| `@rabbit_listener`, `RabbitTemplate`, `RejectAndDontRequeueError` | `@RabbitListener`, `RabbitTemplate`, `AmqpRejectAndDontRequeueException` | `snakeboot[rabbitmq]` |
| `@openapi_definition` | springdoc's `@OpenAPIDefinition` | nothing |
| `TestApplication`, `RecordingTransactionManager`, `declared_classes` | `@SpringBootTest`, `@AutoConfigureTestDatabase`, `TestRestTemplate`, spring-test | `snakeboot[testing]` |

## Install

```bash
uv add "snakeboot[configuration,web,data]"
uv add "snakeboot[configuration,web,data,rabbitmq,oauth2]"   # with RabbitMQ and Keycloak's tokens
```

## A tour

**The application.** A class marked with `@application_root`, like `@SpringBootApplication`, is the application.
Its component scan decides what goes into the container: the package of the class, or the packages `base_packages`
names. The scan skips the server entry points (`wsgi.py`, `asgi.py`) and adds the components snakeboot provides
itself (the event publisher, the lifecycle, the scheduler, `serve`, `run_lifecycle`). `run`, from
`snakeboot.boot`, runs a command, like `SpringApplication.run`: `python -m myapp serve` starts the web server where
`[server]` says, as Spring Boot starts its embedded server, so the application holds no server entry point.
`snakeboot.boot` is the one place that names the frameworks underneath.

```python
# myapp/myapp_application.py
@openapi_definition(title="My service", version="1.0.0")
@application_root(base_packages=("myapp_core",))
class MyApplication: ...


# myapp/__main__.py: python -m myapp serve, python -m myapp migrate, python -m myapp help
from snakeboot.boot import run

run(MyApplication)
```

The application writes no settings and no URLs. `snakeboot.boot` reads `application.toml` in the application package,
builds wireup's container from the component scan, and adds what the tables ask for, like Spring Boot's
conditional auto-configuration: SQLAlchemy and the transaction manager of `@transactional` with `[database]`, Redis
with `[cache]`, RabbitMQ with `[rabbitmq]`. An application without a table imports none of those. The REST API lives
under `/api/` (Swagger UI at `/api/docs`), next to `/health` and `/metrics`.

**Where the files live.** The application package is the package of the class marked with `@application_root`, also
when `base_packages` names others: `myapp` in the example above, not `myapp_core`. It is to snakeboot what the root of
the classpath is to Spring Boot. Python compiles nothing apart, so there is no `src/main/resources`: snakeboot reads
its files as package data, and a source checkout and an installed wheel find them alike.

```text
myapp/                              the application package
├── __main__.py                     run(MyApplication)
├── myapp_application.py            @application_root
├── application.toml                every value the application runs with
├── application-local.toml          what the profile "local" changes
└── games/                          a bounded context
    ├── game_record.py              @entity
    └── migrations/
        └── V1__create_games.sql    next to the entities whose tables it creates
```

| File | Where | Spring Boot |
|---|---|---|
| `application.toml`, `application-<profile>.toml` | in the application package | `src/main/resources/application.yml`, `application-<profile>.yml` |
| `migrations/V<n>__<description>.sql` | next to the module of the entities whose tables they change | `src/main/resources/db/migration/` |
| `static/`, `templates/` | reserved in the application package, for when snakeboot serves pages | `src/main/resources/static/`, `templates/` |

The migrations stay with their entities rather than in one place, so each bounded context keeps its own schema;
`make_migration` writes into that directory, and `--into` chooses one when the entities live in several. Moving the
application class into another package moves where `application.toml` is looked for.

**Typed configuration.** A `Section` (a frozen Pydantic model that refuses unknown keys, the base class of every
configuration model) is bound to one table of `application.toml`, like `@ConfigurationProperties`. A section is a
component of the module that declares it: when the component scan puts that module in the container, the section
comes along, like `@ConfigurationPropertiesScan`, and an adapter asks for it by type.

```python
@configuration_properties("chatbot")
class ChatbotProperties(Section):
    model: str  # no default: the value is in application.toml
    llm: LanguageModelProperties  # a nested Section is the table [chatbot.llm]
```

```toml
[server]
host = "0.0.0.0"            # where `serve` listens: every interface, as in a container
port = 8000
workers = 2                 # processes, each with its own listeners and scheduled methods
debug = false
allowed_hosts = ["*"]       # or "games.example.com", "*.example.com"
log_level = "INFO"

[database]                  # PostgreSQL; the password comes from DATABASE__PASSWORD
host = "db"
port = 5432
name = "tictactoe"
user = "tictactoe"
```

A service that runs on one machine (a demo, a small tool) keeps its database in one SQLite file instead:
`[database] file = "myapp.sqlite3"`, relative to the directory it starts in. A transaction then takes SQLite's write
lock when it begins, so threads that write at once wait for each other; the migrations are SQL in SQLite's dialect.

The values come from three places, a later one overriding an earlier one key by key:

| Source | Holds | Spring Boot |
|---|---|---|
| `application.toml` in the package | every value the application runs with in production | `application.yml` |
| `application-<profile>.toml`, when `SNAKEBOOT_PROFILE` names one | what differs on a developer machine, say | `application-local.yml`, `SPRING_PROFILES_ACTIVE` |
| environment variables `SECTION__KEY__SUBKEY` | secrets and addresses of one deployment | relaxed binding |

Nothing else is read: no `.env` file, no default in code, no command line. The start stops when a model does
not extend `Section`, changes its `model_config` or has a default; when a file or a value is missing; when a key
or a table is unknown (a typo in `application.toml` or in `CHATBOT__LLM__MODLE`). Outside an application,
`load_configuration(ChatbotProperties, package="myapp")` reads the sections it is given.

**Entities and repositories.** An entity is a plain dataclass that a table keeps, like a JPA `@Entity`; a repository is
an interface, a Protocol that extends `CrudRepository`, which snakeboot implements when its module is imported, like
Spring Data. Its methods are derived from their names (`find_by`, `count_by`, `exists_by`, `delete_by`, conditions
joined by `_and_` and `_or_`, keywords such as `less_than_equal`, `in`, `is_null` and `containing`, then `order_by`);
the return annotation says what a method returns. `@query` writes the SQL itself, `@lock` locks the rows read. A name
snakeboot cannot read, a field the entity lacks or a parameter too many stops the start. The implementation is the
component of the interface, so an adapter asks for the interface by type and maps its records to the domain.

```python
@entity("tictactoe_game", indexes=(Index("tictactoe_game_waiting_idx", "status", "join_deadline"),))
@dataclass
class GameRecord:
    game_id: Annotated[UUID, Id()]  # Id(generated=True) for a number the database gives
    status: Annotated[str, Column(length=16)]
    board: list[str]  # list, dict and Any are JSON; Json() makes any field JSON
    join_deadline: datetime | None  # with its time zone; None is an empty column
    updated_at: Annotated[datetime | None, LastModifiedDate()] = None


class GameRecords(CrudRepository[GameRecord, UUID], Protocol):
    @lock(LockMode.PESSIMISTIC_WRITE)
    def find_by_status_and_join_deadline_less_than_equal(self, status: str, deadline: datetime) -> list[GameRecord]: ...

    def find_first_by_order_by_updated_at_desc(self) -> GameRecord | None: ...

    def count_by_status(self, status: str) -> int: ...

    @query("SELECT status, COUNT(*) AS games FROM tictactoe_game GROUP BY status")
    def games_per_status(self) -> list[StatusCount]: ...  # any class made from the columns by name
```

`save` inserts or updates by identifier, like Spring Data's; every call joins the transaction of the running
`@transactional`, or runs in one of its own. A `Version()` field guards against lost updates, like JPA's `@Version`:
saving an entity another transaction changed since it was read raises `OptimisticLockingFailureError` (answer it with
409), and a broken constraint is a `DataIntegrityViolationError`. `CreatedBy()` and `LastModifiedBy()` record who
saved, from the `SecurityContext`, next to `CreatedDate()` and `LastModifiedDate()`.

```python
class GameRecord:
    ...
    updated_by: Annotated[str | None, LastModifiedBy()] = None  # the principal of the call, or None
    version: Annotated[int | None, Version()] = None  # 1 for a new entity, one more per update
```

A repository method whose last parameter is a `PageRequest` returns one page. On PostgreSQL a `Vector(384)` field
(extra `snakeboot[vector]`) holds an embedding for pgvector's similarity search in a `@query`.

**Migrations.** The schema comes from SQL scripts, like Flyway's: `V1__create_tictactoe_game.sql`,
`V2__add_a_winner.sql` in a `migrations` directory next to the entities. `python -m myapp migrate` runs the scripts the
database has not run, in version order, each in a transaction, remembering them with their checksum; a script that
changed after it ran stops it, and on PostgreSQL two processes never migrate at once. `python -m myapp make_migration
"add a winner"` writes the SQL the entities need as the next script, by letting Alembic compare them with the
database. A migration is plain SQL, so it stays valid when the persistence framework changes.

**Transactions.** A use case declares its boundary; snakeboot chooses the technology, SQLAlchemy's session when the
application has `[database]`. A nested `@transactional` call is a savepoint; `after_commit` waits for the outermost
commit and is dropped by a rollback.

```python
@injectable
class CancelRegistrationUseCase:
    @transactional
    def execute(self, request: CancelRegistrationRequestDTO) -> None:
        workshop = self._workshops.get(...)
        workshop.cancel_registration(...)
        self._workshops.save(workshop)
        self._events.publish_all(workshop.pull_events())
```

**Application events.** Listeners react to facts after the commit, so a rolled-back change never
reaches anyone, and a failing listener cannot undo a committed one.

```python
@application_event_listener
class ParticipantNotificationListener:
    def __init__(self, notifications: NotificationPort) -> None:
        self._notifications = notifications

    @transactional_event_listener(WaitlistedParticipantPromoted)
    def notify_promoted(self, event: WaitlistedParticipantPromoted) -> None: ...
```

A `@transactional_event_listener` that fails, or a process that stops before it ran, loses the event. For what must
arrive, an `@application_module_listener` is Spring Modulith's `@ApplicationModuleListener`: it receives the event after
the commit, on a thread of its own, in a transaction of its own, so one module reacts to another without slowing it
down or rolling it back. With `[database]` the publisher's transaction also writes the publication into
`snakeboot_event_publication`, the transactional outbox, and the listener's transaction deletes it. A publication whose
listener failed, or whose process stopped first, is delivered again (after 30 seconds, then longer, ten times at most),
so the event arrives at least once and the listener must bear receiving it twice. What keeps failing waits in the
table, with its last failure, for a person; the gauge `snakeboot_event_publications_incomplete` shows how many wait.
The event is kept as JSON, so it is a dataclass or a Pydantic model; another type stops the start. `make_migration`
writes the table into the application's migrations the first time. The optional table `[events]` sets the timing,
like Spring Modulith's `spring.modulith.events.*`; without it, the values below hold.

```toml
[events]
resubmit_every = 30      # seconds, or an ISO 8601 duration: how often the registry is asked what is due
in_flight = "PT5M"       # longer than the slowest listener: a delivery not done by then was lost
retry_after = 30         # after a failure, times the tries so far: 30 s, 1 min, 1.5 min, ...
max_attempts = 10        # then the publication waits in the table for a person
```

```python
@application_event_listener
class InvoiceOnOrderPlaced:
    @application_module_listener(OrderPlaced)
    def create_invoice(self, event: OrderPlaced) -> None: ...
```

**REST controllers.** Singleton classes with constructor injection. `ControllerScan` finds them in the modules of
the component scan, the same modules that fill the container, and `snakeboot.fastapi_web` publishes their routes.
A controller sees no request: an endpoint takes what the call carries (path and query parameters, a body as a
Pydantic model) and returns the body, whose type is its return annotation; `status=` sets the status of the answer,
like `@ResponseStatus`. A call that does not fit (a missing field, a wrong type) is an `InvalidRequestError`, which
an advice answers like any error, as with Spring's `MethodArgumentNotValidException`. Two endpoints for the same URL,
two answers for one error, or a method that takes `request` stop the start-up.

```python
@rest_controller("/workshops", tags=["workshops"])
class WorkshopRestController:
    def __init__(self, enrollment: EnrollmentFacadePort) -> None:
        self._enrollment = enrollment

    @route.get("/{workshop_id}")
    def get_workshop(self, workshop_id: str) -> WorkshopViewDTO: ...

    @route.post("", status=201)
    def create_workshop(self, body: NewWorkshopDTO) -> WorkshopViewDTO: ...


@rest_controller_advice
class EnrollmentRestErrorAdvice:
    @exception_handler(WorkshopNotFoundError, status=404)
    def answer_not_found(self, error: Exception) -> dict[str, str]:
        return error_answer(error)  # {"code": "workshop_not_found", "detail": "..."}

    @exception_handler(InvalidRequestError, status=422)
    def answer_invalid_request(self, error: Exception) -> dict[str, str]:
        return error_answer(error)  # {"code": "invalid_request", "detail": "body.title: Field required"}
```

**Server-sent events.** An endpoint that returns `ServerSentEvents` streams, like one that returns Spring's
`SseEmitter`: it is served as `text/event-stream`, uncached and unbuffered, and a watching client holds no thread.
`ServerSentEvents.watching` covers what most streams do: it reads a value once in the call (so an unknown id answers
404 as usual), then every `every`, and sends it whenever it changed, until `until` holds. A silence of 15 seconds gets
a comment that keeps proxies open, and a stream ends after 30 minutes, when the browser's `EventSource` reconnects.
Each read runs on the server's thread pool, in a transaction of its own.

```python
@route.get("/games/{game_id}/events")
def watch_game(self, game_id: str) -> ServerSentEvents:
    return ServerSentEvents.watching(
        lambda: self._get_game.execute(GetGameRequestDTO(game_id=game_id)),
        every=timedelta(milliseconds=500),
        until=lambda game: game.status in FINAL_STATUSES,
        as_event=lambda game: ServerSentEvent(game, event="game", id=str(game.version)),  # data as JSON
    )
```

**Authentication.** An adapter that extends `BearerAuthentication` is a component of the container, like a
`SecurityFilterChain` bean: its constructor receives sections and ports by type. With one in the component scan, every
endpoint needs `Authorization: Bearer <token>`, the OpenAPI document says so, and a parameter of type `Principal`
receives whom the token belongs to, like `@AuthenticationPrincipal`. `/health` stays open; an endpoint opts out with
`public=True`. A refused token answers 401 `{"detail": "Unauthorized"}`. `authenticate` returns the caller's id, or a
`Principal` with the roles the token grants; `@roles_allowed` on an endpoint or a whole controller lets in only a caller
with one of its roles, like `@RolesAllowed`, and answers anybody else 403 `{"detail": "Forbidden"}`. While an endpoint
runs, its caller is signed in to the `SecurityContext`, like Spring's `SecurityContextHolder`.

```python
class KeycloakTokens(BearerAuthentication):
    def __init__(self, properties: SecurityProperties) -> None:
        self._properties = properties

    @override
    def authenticate(self, token: str) -> str | None: ...  # the subject of a valid token, or None for 401


# in a controller
@route.post("/{workshop_id}/registrations", status=201)
def register(self, workshop_id: str, participant: Principal) -> RegistrationDTO:
    return self._enrollment.register(workshop_id, participant_id=participant.name)


@route.delete("/{workshop_id}", status=204)
@roles_allowed("organizer")
def cancel(self, workshop_id: str) -> None: ...
```

**Tokens of an authorization server.** For the JWT access tokens of Keycloak or another OAuth2 server, extend
`JwtBearerAuthentication` (extra `snakeboot[oauth2]`) and add the table `[oauth2]` (`issuer_uri`, `jwks_uri`,
`audience`), like Spring Boot's resource server. It fetches the issuer's public keys and caches them, and accepts a
token only when the signature, the issuer, the audience and the expiry are right; its `sub` is the principal, and
its roles are Keycloak's realm roles, its client roles for the audience, and a plain `roles` claim (override
`roles_of` for another authorization server).

**What runs beside the requests.** When `serve` starts the server, and in each of its processes, every `Lifecycle`
component starts, like a `SmartLifecycle` bean, and
`ApplicationReadyEvent` goes to the event listeners. Commands and tests start nothing. `python -m myapp run_lifecycle`
runs the same lifecycle without a web server, until SIGTERM: a process that only listens and schedules, like Spring
Boot without the web starter.

**Commands.** A subclass of `CommandLineRunner` that names its command is a command of the application, like a
`CommandLineRunner` bean: a component whose constructor receives use cases and ports, with arguments declared as with
argparse in a classmethod, because they are parsed before the command is built: `--help` answers at once, even when
the command depends on a server that is down. `python -m myapp self_play --games 20` runs it; `python -m myapp help`
lists the application's commands and snakeboot's own (`serve`, `run_lifecycle`, `migrate`, `make_migration`). A
`CommandLineError` stops the command with its message and exit status 1; two commands of one name stop the start.

```python
class SelfPlayCommand(CommandLineRunner, command="self_play"):
    """Lets the AI levels play each other and prints how strong each one is."""

    def __init__(self, self_play: SelfPlayUseCase) -> None:
        self._self_play = self_play

    @classmethod
    @override
    def add_arguments(cls, parser: ArgumentParser) -> None:
        parser.add_argument("--games", type=int, default=20, help="Games per pairing.")

    @override
    def run(self, arguments: Namespace) -> None:
        print(self._self_play.execute(SelfPlayRequestDTO(games=arguments.games)))
```

**Scheduled methods.** `@scheduled` on a method of a component runs it periodically, like `@Scheduled`: with a fixed
rate or a fixed delay, on one thread. A method that raises is logged and runs again at its next turn.
`[scheduling] auto_startup = false` keeps a process from running them. Every replica runs its own scheduler;
`@scheduler_lock`, like ShedLock's `@SchedulerLock`, lets the replica that takes the lock run a turn and the others
skip it. The lock is a row of `snakeboot_scheduler_lock` in the database, held for at most `at_most_for` (the lock of
a process that died frees itself) and at least `at_least_for`.

```python
@scheduled(fixed_rate=timedelta(hours=1))
@scheduler_lock("hourly-report", at_most_for=timedelta(minutes=50), at_least_for=timedelta(minutes=5))
def send_hourly_report(self) -> None: ...
```

**RabbitMQ.** With the table `[rabbitmq]` (extra `snakeboot[rabbitmq]`, through pika), `@rabbit_listener` makes a
method of a component consume a queue, like `@RabbitListener` with `@QueueBinding`: the durable topic exchange, the
queue and the binding are declared at start-up, the JSON body becomes the pydantic model, `dict` or `bytes` the method
takes, and each listener has a thread and a connection of its own. Returning acknowledges the message;
`RejectAndDontRequeueError` or an unreadable body refuses it for good; another failure is tried three times, then
refused. The `RabbitTemplate` sends persistent JSON, confirmed by the broker. `[rabbitmq.listener] auto_startup =
false` keeps a process from consuming.

```python
@injectable
class GameStartedListener:
    @rabbit_listener(queue="tictactoe.game-started", exchange="games", routing_key="game.tictactoe.started")
    def on_game_started(self, message: GameStartedMessage) -> None: ...  # a pydantic model
```

**Health and metrics.** Like Spring Boot's actuator, the server answers beside the API, without a token:
`/health/liveness` is UP while the process answers (Kubernetes's livenessProbe); `/health` and `/health/readiness`
check every `HealthIndicator` and answer 503 when one part is DOWN (the readinessProbe). The bindings bring the checks
of the database, Redis and RabbitMQ; an adapter that extends `HealthIndicator` adds its own. `/metrics` answers
Prometheus with every meter of the `MeterRegistry`, which times every call as `http_server_requests_seconds` by
method, route and status; an adapter injects it for counters, timers and gauges of its own. The metrics are those of
one process: scale with replicas of one worker.

```python
class PaymentGatewayHealthIndicator(HealthIndicator):
    @override
    def check(self) -> None:
        self._gateway.ping()  # raises when the gateway is down


self._meters.counter("games_started", "Games started", tags={"game": "tictactoe"}).increment()
```

**Traces and logs.** Every call runs in a span of the caller's trace when it sends a W3C `traceparent`, or of a new
trace; so does every message a `@rabbit_listener` receives, every scheduled run, and every
`@application_module_listener`. The `RabbitTemplate` sends the `traceparent` along, and every log line carries the trace
id, so one request can be followed through every service. `[logging] format = "ecs"` writes every line as JSON in the
Elastic Common Schema, for Loki or Elasticsearch, like Spring Boot's structured logging.

**CORS.** With `[cors]`, the pages of the origins it names may call the API from a browser, like a `CorsRegistry`;
without it, none of another origin may. `*` with `allow_credentials = true` stops the start, as in Spring.

```toml
[cors]
allowed_origins = ["https://games.example.com"]
allowed_methods = ["GET", "POST", "PUT", "PATCH", "DELETE"]
allowed_headers = ["Authorization", "Content-Type"]
allow_credentials = false
```

**A cache.** An adapter asks for `Cache` by type: values JSON can hold, kept by key for a while. With `[cache]
redis_url = "redis://redis:6379/1"` (extra `snakeboot[cache]`) it is Redis; a test gives an `InMemoryCache`.

```python
self._cache.put(question, {"text": answer, "sources": sources}, time_to_live=timedelta(hours=1))
```

**Tests.** `TestApplication` starts the application as it runs, from its `application.toml`, with three differences,
like `@SpringBootTest` with `@AutoConfigureTestDatabase`: `overrides` replace components with doubles, the database is a
fresh SQLite in memory whose tables come from the entities, and the `@application_module_listener` methods run on the
caller's thread, so what they did is there when the call returns. `client()` calls the REST API in the same process, like
`TestRestTemplate`; used as a context manager, the lifecycle runs around it.

```python
def test_a_started_game_can_be_read() -> None:
    with TestApplication.start(TictactoeApplication, overrides={GamePlatformPort: FakePlatform()}) as app:
        client = app.client()
        created = client.post("/api/tictactoe/games", json={"players": ["ann", "bob"]})

        assert client.get(f"/api/tictactoe/games/{created.json()['game_id']}").status_code == 200
        assert app.get(GameRecords).count() == 1
```

`RecordingTransactionManager` runs `@transactional` use cases without a database, and `declared_classes` lets an
architecture test compare what the source declares with what the component scan found.

## Design rules

* Imitate the basics, not all of Spring: no AOP, no cron, no message broker other than RabbitMQ.
* Fail at start-up, not at the first request: a broken controller, repository, command, listener, root or
  configuration stops the application.
* An application imports snakeboot, never the framework underneath: only `snakeboot.fastapi_web`,
  `snakeboot.sqlalchemy_data`, `snakeboot.redis_cache` and `snakeboot.boot` know FastAPI, SQLAlchemy, Alembic or Redis,
  so another framework means another binding, not other applications.
* Each package knows as little as possible; `uv run lint-imports` enforces it.

## Develop

```bash
uv sync
uv run pre-commit install
uv run pytest            # tests, including the import contracts
uv run ruff check        # Clean Code rules
uv run mypy              # strict
```

The PostgreSQL tests (migrations, JSONB, pgvector, `SKIP LOCKED`, the scheduler locks) run when `SNAKEBOOT_TEST_POSTGRESQL_URL` names a database they may
fill and empty:

```bash
docker run -d --rm -p 55432:5432 -e POSTGRES_PASSWORD=snakeboot pgvector/pgvector:pg17
SNAKEBOOT_TEST_POSTGRESQL_URL=postgresql+psycopg://postgres:snakeboot@localhost:55432/postgres uv run pytest
```
