MishkaCmsCore.Runtime.Plugs.HealthPlug (Mishka CMS Core v0.0.5-alpha.13)

Copy Markdown View Source

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"}.

Summary

Functions

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.

Functions

check()

@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.