Spakky Actuator

Spakky Framework를 위한 transport 중립 actuator 계약입니다. Health, readiness, liveness, info 상태를 HTTP나 CLI adapter와 분리된 모델로 집계합니다.

설치

pip install spakky-actuator

주요 기능

• Health/readiness/liveness 결과: HTTP, CLI 등 adapter가 공유하는 result 계약
• Probe 확장 지점: Spakky DI로 등록되는 동기/비동기 health probe
• Info contributor: 동기/비동기 info contributor의 결정적 병합
• Startup diagnostics contributor: SpakkyApplication startup report를 actuator info로 노출
• 예외 처리: Probe 예외를 구조화된 에러 상세가 포함된 비정상 component result로 변환
• Transport 중립 core: FastAPI, Typer, plugin adapter 의존성 없음

Endpoint Semantics

기본적으로 health probe는 liveness가 아니라 health와 readiness에 참여합니다. 외부 의존성을 사용할 수 없다는 이유로 실패하면 안 되는 프로세스 내부 check에만 ActuatorEndpoint.LIVENESS를 사용하세요.

빠른 시작

from spakky.actuator import (
    AbstractHealthProbe,
    ActuatorAggregationService,
    ComponentHealthResult,
)
from spakky.core.application.application import SpakkyApplication
from spakky.core.application.application_context import ApplicationContext
from spakky.core.application.plugin import Plugin
from spakky.core.pod.annotations.pod import Pod


@Pod()
class DatabaseProbe(AbstractHealthProbe):
    @property
    def name(self) -> str:
        return "database"

    def check(self) -> ComponentHealthResult:
        return ComponentHealthResult.healthy(self.name)


app = (
    SpakkyApplication(ApplicationContext())
    .load_plugins(include={Plugin(name="spakky-actuator")})
    .add(DatabaseProbe)
    .start()
)
service = app.container.get(type_=ActuatorAggregationService)
health = service.evaluate_health()
readiness = service.evaluate_readiness()

Extension Points

Component health를 제공하려면 AbstractHealthProbe 또는 AbstractAsyncHealthProbe Pod를 등록하세요. info에 metadata를 제공하려면 IInfoContributor 또는 IAsyncInfoContributor Pod를 등록하세요. Actuator 플러그인은 ActuatorExtensionPostProcessor를 추가하여 DI가 관리하는 extension Pod를 발견하고 ActuatorExtensionRegistry에 저장합니다.

from spakky.actuator import (
    AbstractHealthProbe,
    IInfoContributor,
    ActuatorEndpoint,
    ComponentHealthResult,
)
from spakky.core.pod.annotations.pod import Pod


@Pod()
class ProcessProbe(AbstractHealthProbe):
    @property
    def name(self) -> str:
        return "process"

    @property
    def endpoints(self) -> tuple[ActuatorEndpoint, ...]:
        return (ActuatorEndpoint.LIVENESS,)

    def check(self) -> ComponentHealthResult:
        return ComponentHealthResult.healthy(self.name)


@Pod()
class BuildInfo(IInfoContributor):
    @property
    def name(self) -> str:
        return "build"

    def contribute_info(self) -> dict[str, object]:
        return {"version": "1.0.0"}

Backend plugin은 자신이 소유한 외부 의존 상태를 first-party probe/contributor로 등록합니다. 예를 들어 spakky-redis는 Redis 연결 상태와 cache metrics를 actuator health/info에 연결합니다. 애플리케이션은 transport adapter를 바꾸지 않고 같은 계약으로 자체 check를 추가할 수 있습니다.

개발 검증

패키지 단위 검증은 해당 패키지 디렉토리에서 실행합니다.

uv run ruff format .
uv run ruff check .
uv run pyrefly check
uv run pytest

pytest는 각 패키지 pyproject.toml의 coverage 설정을 사용합니다.

라이선스

MIT License