Skip to content

RunnerHealth

Checks whether cluster runners should be treated as alive.

RunnerHealth is used by sharding when deciding whether assigned shards can stay on a runner or need to move elsewhere. This module includes the health-check service, a no-op layer that always reports runners as alive, a ping-based checker, and a Kubernetes-based checker that looks at pod readiness for the runner host.

6 exports Added in v4.0.0 Source

Constructors

makeK8s

Added in v4.0.0 Source

Creates a RunnerHealth service that checks Kubernetes pod readiness for a runner host, optionally scoped by namespace and label selector.

Gotchas

If the Kubernetes API check fails, the runner is treated as healthy.

Signature

declare const makeK8s: (
  ...args: [
    options?: {
      readonly labelSelector?: string;
      readonly namespace?: string;
    },
  ]
) => Effect<
  {
    readonly isAlive: (address: RunnerAddress) => Effect<boolean>;
  },
  never,
  K8sHttpClient
>;

makePing

Added in v4.0.0 Source

Creates a RunnerHealth service that pings runners through Runners, retrying failed pings on a short schedule and treating a successful ping within the timeout as healthy.

Signature

declare const makePing: Effect.Effect<
  RunnerHealth["Service"],
  never,
  Runners.Runners | Scope.Scope
>;

Layers

layerK8s

Added in v4.0.0 Source

Layer that checks Kubernetes pod readiness to determine whether a runner is healthy.

Details

The provided HttpClient must trust the pod CA certificate and the pod service account must be allowed to list pods.

Gotchas

If the Kubernetes API check fails, the runner is treated as healthy.

Signature

declare function layerK8s(options?: {
  readonly labelSelector?: string;
  readonly namespace?: string;
}): Layer<RunnerHealth, never, K8sHttpClient>;

layerNoop

Added in v4.0.0 Source

Layer that always considers a runner healthy.

When to use

Use when you need a runner-health layer for tests or local development where active health checks are unnecessary.

Signature

declare const layerNoop: Layer<RunnerHealth, never, never>;

layerPing

Added in v4.0.0 Source

Layer that pings runners directly to check whether they are healthy.

Signature

declare const layerPing: Layer.Layer<RunnerHealth, never, Runners.Runners>;

Services

RunnerHealth

Added in v4.0.0 Source

Represents the service used to check if a Runner is healthy.

Details

If a Runner is responsive, shards will not be re-assigned because the Runner may still be processing messages. If a Runner is not responsive, then its associated shards can and will be re-assigned to a different Runner.

Signature

declare class RunnerHealth extends Shape<
  "effect/cluster/RunnerHealth",
  {
    readonly isAlive: (address: RunnerAddress) => Effect<boolean>;
  },
  this
> {
  constructor(_: never);
}