healthkit

README

HealthKit Module

Liveness and readiness reporting for Fx applications. Designed for use with orchestrators and load balancers (e.g. Kubernetes).

Modes

1. Dedicated server (ServerModule) Starts its own HTTP server on a configurable port. Recommended for isolation from application traffic.

2. Mux attachment (MuxModule) Registers /health on an existing *http.ServeMux. Useful if the app already exposes HTTP.

Config

    health:
      port: ":8081"          # only used with ServerModule()
      startup_delay: 200ms   # wait before marking ready

Responses

• 200 OK when live and ready.
• 503 Service Unavailable with {"status":"initializing"} until ready.
• 503 Service Unavailable with {"status":"unhealthy"} after stop.

Usage

Dedicated server:

    app := fx.New(
      healthkit.ServerModule(),
    )

Mux attachment:

    app := fx.New(
      httpkit.Module(),
      healthkit.MuxModule(),
    )

Documentation

Overview

Package healthkit provides liveness and readiness reporting for uber/fx applications. It is designed for use with container orchestrators and load balancers like Kubernetes.

Two integration modes are supported:

1. Dedicated server (Module): starts its own HTTP server on a configurable port. This is the recommended approach as it isolates health checks from application traffic.
2. Mux attachment (MuxModule): attaches a /health handler to an existing *http.ServeMux provided by the application. Useful if you already run an HTTP server and want to avoid a second port.

Index

• func MuxModule() fx.Option
• func RegisterMux(mux *http.ServeMux, h *Health)
• func RegisterServer(lc fx.Lifecycle, h *Health)
• func ServerModule() fx.Option
• type Config
• type Health
  • func New(p Params) *Health
• type Params

Functions

func MuxModule

func MuxModule() fx.Option

MuxModule provides health reporting attached to an existing *http.ServeMux. It includes the core Health service and invokes a handler registration.

func RegisterMux

func RegisterMux(mux *http.ServeMux, h *Health)

RegisterMux attaches the health handler to a Mux provided in the Fx container. This is used by MuxModule().

func RegisterServer

func RegisterServer(lc fx.Lifecycle, h *Health)

RegisterServer creates a dedicated HTTP server and registers it with the application lifecycle. This is used by ServerModule().

func ServerModule

func ServerModule() fx.Option

ServerModule provides a self-contained health server on a dedicated port. It includes the core Health service and invokes a dedicated HTTP server.

Types

type Config

type Config struct {
	// Port is the network address for the dedicated health server.
	// Defaults to ":8081" if not set.
	// Only used by ServerModule(), ignored by MuxModule().
	Port string `yaml:"port"`

	// StartupDelay is the duration to wait after the application has started
	// before reporting readiness. Defaults to 200ms if not set.
	StartupDelay time.Duration `yaml:"startup_delay"`
}

Config defines configuration for the Health service.

type Health

type Health struct {
	// contains filtered or unexported fields
}

Health tracks and reports liveness and readiness state.

func New

func New(p Params) *Health

New constructs a new Health service and attaches hooks to manage its state according to the application's lifecycle.

type Params

type Params struct {
	fx.In

	LC     fx.Lifecycle
	Logger *zap.Logger
	// The Config is now marked as optional, as it may not be present in the YAML.
	Config *Config `optional:"true"`
}

Params defines the dependencies required to construct the Health service.