Health Check¶

Verify backend connectivity and credentials before your application starts processing requests.

Quick start¶

from remote_store import Store
from remote_store.backends import LocalBackend

store = Store(LocalBackend(root="/data/inbox"))
store.ping()  # raises on failure, silent on success

Use cases¶

Startup gates — fail fast before accepting traffic if the backend is unreachable or credentials are invalid.
Liveness probes — Kubernetes livenessProbe or similar health endpoints.
Connection validation — verify config after loading from TOML/YAML.

Error handling¶

ping() raises the same exceptions as other Store operations:

Exception	Meaning
`PermissionDenied`	Invalid credentials or insufficient permissions
`NotFound`	Bucket, container, or root directory does not exist
`BackendUnavailable`	Network error, DNS failure, or timeout

from remote_store import BackendUnavailable, NotFound, PermissionDenied

try:
    store.ping()
except PermissionDenied:
    log.error("Bad credentials for %s", store)
except NotFound:
    log.error("Missing bucket/container for %s", store)
except BackendUnavailable:
    log.error("Backend unreachable for %s", store)

Per-backend strategies¶

Each backend uses the cheapest possible read-only operation:

Backend	Operation	What it validates
Local	`root.exists()` + `os.access(R_OK)`	Directory exists and is readable
S3	`head_bucket`	Bucket exists, credentials valid
S3-PyArrow	`get_file_info(bucket)`	Bucket accessible via PyArrow
SFTP	`stat(base_path)`	SSH connection, path exists
Azure	`get_container_properties()`	Container exists, credentials valid
Memory	No-op	Always healthy
HTTP	`HEAD` to `base_url` (falls back to `GET`)	Server reachable
SQLBlob	`SELECT 1`	Database connection valid
SQLQuery	`SELECT 1`	Database connection valid

Observability¶

ping() integrates with ext.observe:

from remote_store.ext.observe import observe

def on_ping(event):
    print(f"Ping took {event.duration_ms:.1f}ms")

observed = observe(store, on_ping=on_ping)
observed.ping()

Design notes¶

No return value — success is silent (None), failure raises. This matches the Go convention of Ping() error and keeps the API minimal.
No caching — every call performs a real connectivity check.
No timeout parameter — use backend-level timeouts (e.g. RetryPolicy).
Not capability-gated — all backends support health checks.