# `Malla.Plugins.Httpd.Lifecycle`
[🔗](https://github.com/netkubes/malla/blob/v0.1.0/lib/malla/plugins/httpd/lifecycle.ex#L21)

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 `c: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
  `c: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.

# `httpd_lifecycle_drain`

```elixir
@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`

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

---

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