Metadata-Version: 2.4
Name: dephealth
Version: 0.8.1
Summary: SDK for monitoring microservice dependencies via Prometheus metrics
Project-URL: Homepage, https://github.com/BigKAA/topologymetrics
Project-URL: Repository, https://github.com/BigKAA/topologymetrics
Project-URL: Documentation, https://github.com/BigKAA/topologymetrics/tree/master/docs
Project-URL: Bug Tracker, https://github.com/BigKAA/topologymetrics/issues
Project-URL: Changelog, https://github.com/BigKAA/topologymetrics/blob/master/CHANGELOG.md
Author-email: Artur Kryukov <artur@kryukov.biz>
License-Expression: Apache-2.0
Keywords: dependency,health-check,microservices,monitoring,prometheus
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.9
Requires-Dist: prometheus-client>=0.20
Provides-Extra: all
Requires-Dist: aio-pika>=9.4; extra == 'all'
Requires-Dist: aiokafka>=0.10; extra == 'all'
Requires-Dist: aiomysql>=0.2; extra == 'all'
Requires-Dist: asyncpg>=0.29; extra == 'all'
Requires-Dist: fastapi>=0.110; extra == 'all'
Requires-Dist: grpcio-health-checking>=1.60; extra == 'all'
Requires-Dist: grpcio>=1.60; extra == 'all'
Requires-Dist: ldap3>=2.9; extra == 'all'
Requires-Dist: redis[hiredis]>=5.0; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.29; extra == 'all'
Provides-Extra: amqp
Requires-Dist: aio-pika>=9.4; extra == 'amqp'
Provides-Extra: dev
Requires-Dist: aio-pika>=9.4; extra == 'dev'
Requires-Dist: aiokafka>=0.10; extra == 'dev'
Requires-Dist: aiomysql>=0.2; extra == 'dev'
Requires-Dist: asyncpg>=0.29; extra == 'dev'
Requires-Dist: fastapi>=0.110; extra == 'dev'
Requires-Dist: grpcio-health-checking>=1.60; extra == 'dev'
Requires-Dist: grpcio>=1.60; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: ldap3>=2.9; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pdoc>=14.0; extra == 'dev'
Requires-Dist: pip-audit>=2.7; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: redis[hiredis]>=5.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: uvicorn[standard]>=0.29; extra == 'dev'
Requires-Dist: vulture>=2.11; extra == 'dev'
Provides-Extra: docs
Requires-Dist: pdoc>=14.0; extra == 'docs'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.110; extra == 'fastapi'
Requires-Dist: uvicorn[standard]>=0.29; extra == 'fastapi'
Provides-Extra: grpc
Requires-Dist: grpcio-health-checking>=1.60; extra == 'grpc'
Requires-Dist: grpcio>=1.60; extra == 'grpc'
Provides-Extra: kafka
Requires-Dist: aiokafka>=0.10; extra == 'kafka'
Provides-Extra: ldap
Requires-Dist: ldap3>=2.9; extra == 'ldap'
Provides-Extra: mysql
Requires-Dist: aiomysql>=0.2; extra == 'mysql'
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.29; extra == 'postgres'
Provides-Extra: redis
Requires-Dist: redis[hiredis]>=5.0; extra == 'redis'
Description-Content-Type: text/markdown

*[Русская версия](README.ru.md)*

# dephealth

SDK for monitoring microservice dependencies via Prometheus metrics.

## Features

- Automatic health checking for dependencies (PostgreSQL, MySQL, Redis, RabbitMQ, Kafka, HTTP, gRPC, TCP, LDAP)
- Prometheus metrics export: `app_dependency_health` (Gauge 0/1), `app_dependency_latency_seconds` (Histogram), `app_dependency_status` (enum), `app_dependency_status_detail` (info)
- Async architecture built on `asyncio`
- FastAPI integration (middleware, lifespan, endpoints)
- Connection pool support (preferred) and standalone checks

## Installation

```bash
# Basic installation
pip install dephealth

# With specific checkers
pip install dephealth[postgres,redis]

# All checkers + FastAPI
pip install dephealth[all]
```

## Quick Start

### Standalone

```python
from dephealth import DepHealth

dh = DepHealth()
dh.add("postgres", url="postgresql://user:pass@localhost:5432/mydb")
dh.add("redis", url="redis://localhost:6379")

await dh.start()
# Metrics are available via prometheus_client
await dh.stop()
```

### FastAPI

```python
from fastapi import FastAPI
from dephealth_fastapi import DepHealthFastAPI

app = FastAPI()
dh = DepHealthFastAPI(app)
dh.add("postgres", url="postgresql://user:pass@localhost:5432/mydb")
```

## Dynamic Endpoints

Add, remove, or replace monitored endpoints at runtime on a running instance
(v0.6.0+):

```python
from dephealth import DependencyType, Endpoint
from dephealth.checks.http import HTTPChecker

# After dh.start()...

# Add a new endpoint
await dh.add_endpoint(
    "api-backend",
    DependencyType.HTTP,
    True,
    Endpoint(host="backend-2.svc", port="8080"),
    HTTPChecker(),
)

# Remove an endpoint (cancels check task, deletes metrics)
await dh.remove_endpoint("api-backend", "backend-2.svc", "8080")

# Replace an endpoint atomically
await dh.update_endpoint(
    "api-backend",
    "backend-1.svc", "8080",
    Endpoint(host="backend-3.svc", port="8080"),
    HTTPChecker(),
)
```

Synchronous variants are available: `add_endpoint_sync()`,
`remove_endpoint_sync()`, `update_endpoint_sync()`.

See [migration guide](docs/migration.md#v050-to-v060) for details.

## Health Details

```python
details = dh.health_details()
for key, ep in details.items():
    print(f"{key}: healthy={ep.healthy} status={ep.status} "
          f"latency={ep.latency_millis():.1f}ms")
```

## Configuration

| Parameter | Default | Description |
| --- | --- | --- |
| `interval` | `15` | Check interval (seconds) |
| `timeout` | `5` | Check timeout (seconds) |

## Supported Dependencies

| Type | Extra | URL Format |
| --- | --- | --- |
| PostgreSQL | `postgres` | `postgresql://user:pass@host:5432/db` |
| MySQL | `mysql` | `mysql://user:pass@host:3306/db` |
| Redis | `redis` | `redis://host:6379` |
| RabbitMQ | `amqp` | `amqp://user:pass@host:5672/vhost` |
| Kafka | `kafka` | `kafka://host1:9092,host2:9092` |
| HTTP | — | `http://host:8080/health` |
| gRPC | `grpc` | `host:50051` (via `FromParams`) |
| TCP | — | `tcp://host:port` |
| LDAP | `ldap` | `ldap://host:389` or `ldaps://host:636` |

## LDAP Checker

LDAP health checker supports four check methods and multiple TLS modes:

```python
from dephealth.checks.ldap import LdapChecker, LdapCheckMethod, LdapSearchScope

# RootDSE check (default)
ldap_checker = LdapChecker(check_method=LdapCheckMethod.ROOT_DSE)

# Simple bind with credentials
ldap_checker = LdapChecker(
    check_method=LdapCheckMethod.SIMPLE_BIND,
    bind_dn="cn=monitor,dc=corp,dc=com",
    bind_password="secret",
    use_tls=True,
)

# Search with StartTLS
ldap_checker = LdapChecker(
    check_method=LdapCheckMethod.SEARCH,
    base_dn="dc=example,dc=com",
    search_filter="(objectClass=organizationalUnit)",
    search_scope=LdapSearchScope.ONE,
    start_tls=True,
)
```

Check methods: `ANONYMOUS_BIND`, `SIMPLE_BIND`, `ROOT_DSE` (default), `SEARCH`.

## Authentication

HTTP and gRPC checkers support Bearer token, Basic Auth, and custom headers/metadata:

```python
http_check("secure-api",
    url="http://api.svc:8080",
    critical=True,
    bearer_token="eyJhbG...",
)

grpc_check("grpc-backend",
    host="backend.svc",
    port=9090,
    critical=True,
    bearer_token="eyJhbG...",
)
```

See [authentication guide](docs/authentication.md) for all options.

## Documentation

Full documentation is available in the [docs/](docs/README.md) directory.

## License

Apache License 2.0 — see [LICENSE](https://github.com/BigKAA/topologymetrics/blob/master/LICENSE).
