# `MishkaCmsCore.Runtime.Plugs.HealthPlug`
[🔗](https://github.com/mishka-group/mishka_cms_core/blob/v0.0.5-alpha.13/lib/mishka_cms_core/runtime/plugs/health_plug.ex#L5)

Answers `GET /_health` (and `HEAD`) with whether this node is ready to serve its sites, for a
deploy's health check: a proxy that sends visitors to a new container only once it answers 200
keeps them on the old one while the new one is still warming up.

It is ready when, in this order:

  1. the boot is done (`MishkaCmsCore.Runtime.Handlers.BootHandler.get_status/0` is `:ready`):
     every site is loaded and every precompiled page, layout, component and error page is built;
  2. every active site in `MishkaCmsCore.Runtime.States.SiteState` has its CSS and its JS bundle in
     `MishkaCmsCore.Runtime.States.AssetsState`, the bundles the boot queued;
  3. every plugin on the `runtime:health:ready` event answers `:ok`;
  4. the repo answers `SELECT 1`.

Ready is `200` with `ok`; anything else is `503` with a short reason, such as `booting`,
`boot failed`, `building assets: blog css` or `database unavailable`. Both are plain text with
`cache-control: no-store`. The checks read the caches the boot fills, so a probe costs ETS reads
and one `SELECT 1`. A bundle whose build failed keeps the node at 503 and names the failure, so a
release that cannot build a site's CSS never takes its traffic.

The answer does not depend on the `Host` header, the scheme or a site, so mount it in the endpoint
before anything that does, such as the site lookup and the session:

    defmodule MyAppWeb.Endpoint do
      use Phoenix.Endpoint, otp_app: :my_app

      plug MishkaCmsCore.Runtime.Plugs.HealthPlug
      # ... sockets, static files, parsers, session, router
    end

Phoenix runs `force_ssl` before the endpoint's first plug, and it leaves `localhost` and
`127.0.0.1` alone, so a probe inside the container (`curl http://localhost:4000/_health`) reaches
it as it is. To answer plain http on any host too, exclude the path:

    config :my_app, MyAppWeb.Endpoint,
      force_ssl: [
        rewrite_on: [:x_forwarded_proto],
        host: nil,
        exclude: [hosts: ["localhost", "127.0.0.1"], paths: ["/_health"]]
      ]

`_health` is one of `MishkaCmsCore.ExtensionRouter.host_prefixes/0`, so no extension route takes
it.

## Holding readiness from an extension

An extension that warms something of its own at boot holds the node at 503 with a plugin on
`runtime:health:ready`. It is handed `:ok`, and answers `:ok` when ready, or `{:error, reason}`,
where `reason` is the short text the probe shows; a plugin handed an `{:error, _}` passes it on.
The check runs on every probe, so it reads state and does no work:

    defmodule MyExtension.Plugins.SearchIndexReady do
      use MishkaInstaller.Event.Hook, event: "runtime:health:ready"

      def call(:ok) do
        if MyExtension.SearchIndex.loaded?(),
          do: {:reply, :ok},
          else: {:reply, :halt, {:error, "search index loading"}}
      end

      def call(error), do: {:reply, error}
    end

A plugin that raises answers `{:error, "extension check failed"}`.

# `check`

```elixir
@spec check() :: :ok | {:error, String.t()}
```

Whether this node is ready to serve its sites: `:ok`, or `{:error, reason}` with the first check
that is not, in the order the moduledoc lists them.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
