Metadata-Version: 2.4
Name: sonnet-server
Version: 0.8.1
Summary: Domain-service foundation for Petrarca Labs backend services
Author-email: Wolfgang Miller <wolfgang.miller@petrarca-labs.com>
License-Expression: Apache-2.0
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <4.0,>=3.14
Description-Content-Type: text/markdown
Requires-Dist: sonnet-core>=0.5.0
Requires-Dist: fastapi>=0.135.1
Requires-Dist: starlette>=1.3
Requires-Dist: uvicorn>=0.41.0
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: loguru>=0.7.3
Requires-Dist: jinja2>=3.1.6
Requires-Dist: sqlmodel>=0.0.37
Requires-Dist: sqlalchemy>=2.0.48
Requires-Dist: alembic>=1.18.4
Requires-Dist: tenacity>=9.1.4
Requires-Dist: pydantic-settings>=2.13.1
Requires-Dist: arrow>=1.4.0
Requires-Dist: jsonschema>=4.23.0
Requires-Dist: cachetools>=7.0.5
Requires-Dist: opentelemetry-api>=1.44.0
Provides-Extra: filtering
Requires-Dist: lark>=1.3.1; extra == "filtering"
Provides-Extra: graphql
Requires-Dist: strawberry-graphql[fastapi]>=0.312.3; extra == "graphql"
Provides-Extra: postgres
Requires-Dist: psycopg>=3.3.3; extra == "postgres"
Requires-Dist: psycopg-binary>=3.3.3; extra == "postgres"
Provides-Extra: nats
Requires-Dist: nats-py>=2.15.0; extra == "nats"
Provides-Extra: rabbitmq
Requires-Dist: aio-pika>=9.5.0; extra == "rabbitmq"
Provides-Extra: redis
Requires-Dist: redis[hiredis]>=7.0; extra == "redis"
Provides-Extra: telemetry
Requires-Dist: sonnet-core[telemetry]; extra == "telemetry"
Requires-Dist: opentelemetry-instrumentation-asgi>=0.65b0; extra == "telemetry"
Provides-Extra: all
Requires-Dist: sonnet-server[filtering,graphql,nats,postgres,rabbitmq,redis,telemetry]; extra == "all"
Provides-Extra: dev
Requires-Dist: sonnet-server[all]; extra == "dev"
Requires-Dist: ruff>=0.3.0; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pre-commit>=4.3.0; extra == "dev"
Requires-Dist: fakeredis>=2.0; extra == "dev"
Requires-Dist: testcontainers[nats,postgres,redis]>=4.0; extra == "dev"
Requires-Dist: watchfiles>=0.19.0; extra == "dev"

# sonnet-server

The web layer for Petrarca Labs backend services. A FastAPI application
factory, an extension mechanism for composing subsystems, and the
infrastructure that sits behind a request: database wiring, messaging, caching,
guards and readiness.

Version 0.6.0. It is a library, not a running service -- the consuming
application owns its entry point and its factory call
([ADR-0001](../../docs/adr/0001-sonnet-server-is-a-library.md)).

## What it provides

- **Application factory** -- `create_app` wires logging, DI, profiles,
  extension lifecycle, exception handlers, CORS and the system endpoints
  (`/ping`, `/version`, `/health-check`), and returns the app plus a startup
  check coroutine.
- **Extensions** -- opt-in subsystem lifecycle with routers, middleware and
  checks contributed per capability. Extensions may live in other packages.
- **Routing and guards** -- router factories that apply preconditions
  (authenticated caller, tenant context, per-request session) before a handler
  runs, with the implementations filled by protocol slots.
- **List endpoints** -- one pagination envelope with sorting, search and
  declared client filters.
- **Messaging** -- a content-based router over in-process, PostgreSQL
  LISTEN/NOTIFY, NATS and RabbitMQ channels, with a CloudEvents envelope and
  request/reply.
- **Caching** -- a managed cache with local, distributed and near-cache modes
  and cross-process invalidation.
- **Readiness stages** -- concrete database, messaging and cache checks on the
  `sonnet-core` engine.
- **Settings and profiles** -- a `Settings` base you subclass with your own env
  prefix, and per-deployment subsystem toggles.

Command-line building blocks are **not** here. They live in
[`sonnet-cli`](../sonnet-cli/README.md); this package depends on neither typer
nor rich. The data layer -- repositories, sessions, filtering, the readiness
engine -- lives in [`sonnet-core`](../sonnet-core/README.md), which comes with
this package.

## Install

```bash
uv add "sonnet-server[postgres]"
```

| Extra | Adds | Use when |
|---|---|---|
| `postgres` | `psycopg` | Always, in practice -- PostgreSQL is the target database. |
| `filtering` | `lark` | Accepting client filter expressions. |
| `graphql` | `strawberry-graphql` | Serving GraphQL. |
| `nats` | `nats-py` | Using NATS as the message broker. |
| `rabbitmq` | `aio-pika` | Using RabbitMQ as the message broker. |
| `redis` | `redis` | Using a distributed or near cache. |
| `all` | all of the above | Development, or a service that uses most of it. |

For a project file, pin the current floor:

```toml
[project]
dependencies = ["sonnet-server[all]>=0.6.0"]
```

## Usage

Register the extensions the service needs and hand them to the factory. The
factory drives them in registration order and does not know what any of them
are.

```python
from sonnet_server.app import create_app
from sonnet_server.database.extension import DatabaseExtension
from sonnet_server.extensions import create_extension_registry

_registry = create_extension_registry(
    DatabaseExtension(),
    RestExtension(),
)

app, perform_startup_checks = create_app(
    extension_registry=_registry,
    register_services=register_all_services,
    title="My Server",
    server_name="my_server",
)
```

Infrastructure extensions go first. See the usage guides for settings,
routing, list endpoints, messaging, caching and GraphQL.

## Documentation

- **Usage** -- [`docs/usage/index.md`](docs/usage/index.md)
- **Design** -- [`docs/design/index.md`](docs/design/index.md)
- **Workspace** -- [`../../docs/README.md`](../../docs/README.md)

## License

Apache 2.0 -- see [LICENSE.md](../../LICENSE.md).
