# Service Health Checker

`service-health-checker` is a Python library that validates the health of critical service dependencies and reports whether your system is safe to run.

It is designed for:

- production readiness checks
- container health checks
- Kubernetes readiness probes
- CI/CD deployment checks

## Features

- Health checks for dependencies such as:
  - databases
  - cache systems
  - message queues
  - external APIs
  - storage services
- Simple status model: `OK` or `FAILED`
- Aggregated report with optional fail-fast exit code for automation
- Lightweight, no third-party dependencies

## Installation

```bash
pip install service-health-checker
```

## Quick Start (Library)

```python
from service_health_checker import (
    ServiceMonitor,
    tcp_check,
    http_check,
    disk_space_check,
)

monitor = ServiceMonitor(timeout=3.0)

monitor.add_check("Database", tcp_check(host="127.0.0.1", port=5432))
monitor.add_check("Redis", tcp_check(host="127.0.0.1", port=6379))
monitor.add_check("Kafka", tcp_check(host="127.0.0.1", port=9092))
monitor.add_check("External API", http_check(url="https://api.example.com/health"))
monitor.add_check("Disk Space", disk_space_check(path="/", min_free_percent=10.0))

report = monitor.run()
print(report.to_table())

if not report.is_healthy:
    raise SystemExit("System is not safe to run")
```

### Example Output

```text
Service Health Report

Database        OK
Redis           OK
Kafka           OK
External API    FAILED
Disk Space      OK
```

## CLI Usage

The package provides a CLI command:

```bash
service-health-check --http "External API=https://api.example.com/health" --disk "Disk Space=/,10"
```

Additional examples:

```bash
service-health-check \
  --tcp "Database=127.0.0.1:5432" \
  --tcp "Redis=127.0.0.1:6379" \
  --tcp "Kafka=127.0.0.1:9092" \
  --http "External API=https://api.example.com/health" \
  --disk "Disk Space=/,10" \
  --json
```

Exit codes:

- `0` when all checks are healthy
- `1` when one or more checks fail

## Built-in Checks

- `tcp_check(host, port)`
- `http_check(url, method="GET")`
- `disk_space_check(path="/", min_free_percent=10.0)`

## API Overview

- `ServiceMonitor(timeout=3.0)`
- `add_check(name, check_fn)`
- `run() -> HealthReport`

`HealthReport` provides:

- `results`: list of individual service results
- `is_healthy`: boolean overall status
- `to_table()`: human-readable report
- `to_dict()`: structured output
