Malla.Plugins.Httpd.Lifecycle behaviour (malla v0.1.0)

Copy Markdown View Source

Plugin that extends Malla.Plugins.Httpd with Kubernetes-style lifecycle endpoints.

Provides the following HTTP endpoints:

  • GET /node — replies 200 with the current node name (as returned by Kernel.node/0, converted with Atom.to_string/1).
  • GET /is_live — invokes Malla.Service.is_live?/1 on every locally started service. Replies 200 when all services report live, or 500 (with the offending service id in the body) otherwise. Typically used as a Kubernetes liveness probe so the pod is restarted if it stops being live for long enough.
  • GET /is_ready — invokes Malla.Service.is_ready?/1 on every locally started service. Replies 200 when all services report ready, or 500 (with the offending service id in the body) otherwise. Typically used as a Kubernetes readiness probe so the pod is added to the service network only once it is ready.
  • GET /stop — first invokes httpd_lifecycle_drain_start/0, then drains every locally started service via Malla.Service.drain_all_local/0 (in each service's :priority order, lowest first), and once all are drained invokes the httpd_lifecycle_drain/0 callback to let services run any additional shutdown work. Replies 200 on success or 500 after ten failed retries (one second apart). Typically wired to the Kubernetes pre-stop hook so in-flight work can finish cleanly before the pod is killed.

Requests that do not match any of the paths above fall through (:cont), letting other plugins handle them.

To use, add the plugin to your service after Malla.Plugins.Httpd:

defmodule MyApp.Service do
  use Malla.Service,
    plugins: [Malla.Plugins.Httpd, Malla.Plugins.Httpd.Lifecycle],
    malla_httpd: [port: 3100]
end

Malla.Plugins.Httpd.Lifecycle declares Malla.Plugins.Httpd as a plugin dependency, so listing only the former is enough.

Summary

Callbacks

Invoked by the GET /stop endpoint once every local service has been drained via Malla.Service.drain/1, allowing each service to run any additional shutdown work (flushing buffers, closing external connections, waiting for in-flight jobs, etc.).

Invoked once by the GET /stop endpoint before any service is drained, so the node can announce it is going away: report not ready, stop consumers, close listeners that should not take new work. Its return value is ignored.

Callbacks

httpd_lifecycle_drain()

@callback httpd_lifecycle_drain() :: boolean()

Invoked by the GET /stop endpoint once every local service has been drained via Malla.Service.drain/1, allowing each service to run any additional shutdown work (flushing buffers, closing external connections, waiting for in-flight jobs, etc.).

Return value

  • true — the custom drain is complete. /stop replies 200.
  • false — the custom drain is still in progress. The plugin sleeps for one second and calls the callback again.

The /stop handler retries the drain/callback cycle up to ten times; if true is never returned within that budget, /stop replies 500.

The default implementation returns true immediately, which is the right choice when no extra shutdown work is needed.

httpd_lifecycle_drain_start()

@callback httpd_lifecycle_drain_start() :: any()

Invoked once by the GET /stop endpoint before any service is drained, so the node can announce it is going away: report not ready, stop consumers, close listeners that should not take new work. Its return value is ignored.

The default implementation does nothing.