health-check

Kind	kit
Categories	cloud monitoring
Keywords	health healthcheck monitoring cloud readiness liveness

Health check types, runner, and JSON output for Kit cloud deployments

Files

File	Description
`.editorconfig`	Editor formatting configuration
`.gitignore`	Git ignore rules for build artifacts and dependencies
`.tool-versions`	asdf tool versions (Zig, Kit)
`examples/basic-health.kit`	Basic usage example
`kit.toml`	Package manifest with metadata and dependencies
`LICENSE`	MIT license file
`README.md`	This file
`src/main.kit`	kit-health-check: Health Check Types and Runner
`src/runner.kit`	Health check runner, JSON output, and HTTP status codes
`src/types.kit`	Core types: HealthStatus, CheckResult, HealthReport, Probe
`tests/runner.test.kit`	Tests for runner, JSON output, status helpers

Dependencies

No Kit package dependencies.

Installation

kit add gitlab.com/kit-lang/packages/kit-health-check.git

Usage

import Kit.HealthCheck

main = fn(-env) =>
  # Define health check probes
  db-probe = HealthCheck.Probe {
    label: "database",
    checker: fn(-n) => HealthCheck.Healthy
  }

  cache-probe = HealthCheck.Probe {
    label: "cache",
    checker: fn(-n) => HealthCheck.Degraded "high latency"
  }

  worker-probe = HealthCheck.Probe {
    label: "worker",
    checker: fn(-n) => HealthCheck.Healthy
  }

  # Run all probes and get aggregate report
  report = HealthCheck.check [db-probe, cache-probe, worker-probe]

  # Output results
  println "Status:      ${HealthCheck.status-to-string report.status}"
  println "HTTP code:   ${to-string (HealthCheck.status-code report)}"
  println "Check count: ${to-string (List.length report.checks)}"
  println (HealthCheck.to-json report)

main

Types

Type	Description
`HealthStatus`	`Healthy`, `Degraded String`, or `Unhealthy String`
`CheckResult`	`CheckResult {label: String, status: HealthStatus}`
`HealthReport`	`HealthReport {status: HealthStatus, checks: [CheckResult]}`
`Probe`	`Probe {label: String, checker: Int -> HealthStatus}`

Functions

Function	Signature	Description
`check`	`[Probe] -> HealthReport`	Run probes and aggregate into a report (worst-of status)
`to-json`	`HealthReport -> String`	Convert report to JSON string
`status-code`	`HealthReport -> Int`	Map report to HTTP status (200 or 503)
`status-to-string`	`HealthStatus -> String`	Convert status to `"healthy"`, `"degraded"`, or `"unhealthy"`
`is-healthy?`	`HealthStatus -> Bool`	Check if status is Healthy
`is-degraded?`	`HealthStatus -> Bool`	Check if status is Degraded
`is-unhealthy?`	`HealthStatus -> Bool`	Check if status is Unhealthy

JSON Output

to-json produces output in the following format:

{"status":"degraded","checks":[{"name":"database","status":"healthy"},{"name":"cache","status":"degraded","reason":"high latency"}]}

A "reason" field is included for Degraded and Unhealthy checks.

Status Code Mapping

Status	HTTP Code
Healthy	200
Degraded	200
Unhealthy	503

Development

Running Examples

Run examples with the interpreter:

kit run examples/basic-health.kit

Compile examples to a native binary:

kit build examples/basic-health.kit && ./basic-health

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running kit dev

Run the standard development workflow (format, check, test):

kit dev

This will:

Format and check source files in src/
Run tests in tests/ with coverage

Generating Documentation

Generate API documentation from doc comments:

kit doc

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/health-check/, making it available for import as Kit.HealthCheck in other projects.

License

This package is released under the MIT License - see LICENSE for details.

Exported Functions & Types

`check`

Run all probes and produce an aggregate HealthReport.

[Probe] -> HealthReport

`to-json`

Convert a HealthReport to a JSON string.

HealthReport -> String

`status-code`

Map a HealthReport to an HTTP status code.

HealthReport -> Int

`HealthStatus`

The health status of a component or service.

- Healthy: Component is operating normally - Degraded: Component is functional but impaired (with reason) - Unhealthy: Component is not functional (with reason)

Variants

Healthy

Degraded {String}

Unhealthy {String}

`CheckResult`

The result of a single health check.

Contains the label of the check and its status.

Variants

CheckResult {label, status}

`HealthReport`

An aggregate health report containing overall status and individual checks.

The overall status is the worst-of all check statuses: any Unhealthy -> Unhealthy, any Degraded -> Degraded, else Healthy.

Variants

HealthReport {status, checks}

`Probe`

A named health check probe.

The checker function takes a dummy Int argument (pass 0) and returns a HealthStatus.

Variants

Probe {label, checker}

`status-to-string`

Convert a HealthStatus to its string label.

HealthStatus -> String

`is-healthy?`

Check if a HealthStatus is Healthy.

HealthStatus -> Bool

`is-degraded?`

Check if a HealthStatus is Degraded.

HealthStatus -> Bool

`is-unhealthy?`

Check if a HealthStatus is Unhealthy.

HealthStatus -> Bool

`check`

Run all probes and produce an aggregate HealthReport.

Each probe's checker is called with 0 as the dummy argument. The aggregate status is the worst-of all individual statuses: any Unhealthy -> Unhealthy, any Degraded -> Degraded, else Healthy.

[Probe] -> HealthReport

`to-json`

Convert a HealthReport to a JSON string.

Format: {"status":"healthy","checks":[{"name":"db","status":"healthy"},...]} Includes "reason" field for Degraded and Unhealthy checks.

HealthReport -> String

`status-code`

Map a HealthReport to an HTTP status code.

Healthy or Degraded -> 200, Unhealthy -> 503.

HealthReport -> Int