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:
- the boot is done (
MishkaCmsCore.Runtime.Handlers.BootHandler.get_status/0is:ready): every site is loaded and every precompiled page, layout, component and error page is built; - every active site in
MishkaCmsCore.Runtime.States.SiteStatehas its CSS and its JS bundle inMishkaCmsCore.Runtime.States.AssetsState, the bundles the boot queued; - every plugin on the
runtime:health:readyevent answers:ok; - 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
endPhoenix 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}
endA plugin that raises answers {:error, "extension check failed"}.
Summary
Functions
@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.