Ferricstore.Health (ferricstore v0.3.1)

Tracks node readiness for Kubernetes health probes (spec 2C.1 Phase 3).

The readiness flag starts as false during application startup and is set to true by Ferricstore.Application after the full supervision tree has started successfully. This prevents Kubernetes from routing traffic to a node that hasn't finished initializing its shards.

Uses :persistent_term for zero-cost reads from any process. The write happens exactly once during normal operation (startup), so the global GC cost of :persistent_term.put/2 is negligible.

Public API

ready?/0 - returns true when the node is ready to serve traffic
set_ready/1 - sets the readiness flag (called by Application on startup)
check/0 - returns a detailed health map with shard status

Usage by Kubernetes

Configure a readiness probe pointing at the HTTP endpoint served by Ferricstore.Health.Endpoint:

readinessProbe:
  httpGet:
    path: /health/ready
    port: 9090
  initialDelaySeconds: 2
  periodSeconds: 5

Summary

Types

health_result()

Full health check result.

shard_info()

Shard health info.

Functions

check()

Returns a detailed health check map including per-shard status.

ready?()

Returns true when the node has completed startup and is ready to serve traffic. Returns false during startup or if the readiness flag has not been set.

set_ready(value)

Sets the node readiness flag.

Types

health_result()

@type health_result() :: %{
  status: :ok | :starting,
  shard_count: non_neg_integer(),
  shards: [shard_info()],
  uptime_seconds: non_neg_integer()
}

Full health check result.

shard_info()

@type shard_info() :: %{
  index: non_neg_integer(),
  status: String.t(),
  keys: non_neg_integer()
}

Shard health info.

Functions

check()

@spec check() :: health_result()

Returns a detailed health check map including per-shard status.

The returned map contains:

:status - :ok when ready, :starting otherwise
:shard_count - configured number of shards
:shards - list of per-shard info maps with :index, :status,
```
                and `:keys`
```
:uptime_seconds - seconds since server start

Examples

iex> Ferricstore.Health.check()
%{
  status: :ok,
  shard_count: 4,
  shards: [
    %{index: 0, status: "ok", keys: 42},
    ...
  ],
  uptime_seconds: 120
}

ready?()

@spec ready?() :: boolean()

Returns true when the node has completed startup and is ready to serve traffic. Returns false during startup or if the readiness flag has not been set.

This is a zero-cost read from :persistent_term.

Examples

iex> Ferricstore.Health.ready?()
true

set_ready(value)

@spec set_ready(boolean()) :: :ok

Sets the node readiness flag.

Called by Ferricstore.Application.start/2 after the supervision tree has started successfully. Can also be used in tests to simulate startup/shutdown transitions.

Parameters

value - true to mark the node as ready, false to mark it as starting

Examples

iex> Ferricstore.Health.set_ready(true)
:ok