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

  This module implements a `Malla.Plugin` to include in your `Malla.Service`,
  providing a super simple, dependency-free http server, useful to
  provide adminstrative information like Prometheus requests, Kubernetes Lifecycle,
  etc.

  It is built on Erlang's `:inets` `httpd` (already part of OTP), so it pulls
  in no extra web stack. It is intended for administrative surfaces —
  Prometheus scraping, Kubernetes health probes, internal introspection —
  where a full web framework would be overkill.

  It offers a single callback, `c:httpd_request/4` that will be called on
  each incoming request.

  To use it, include it in your service, for example

  ```
  defmodule MyService do
    use Malla.Service,
      plugins: [Malla.Plugins.Httpd],
      malla_httpd: [port: 3100]

    defcb httpd_request(name, method, path, data) do
      body =
        inspect(%{
          name: name,
          method: method,
          path: path,
          headers: Malla.Plugins.Httpd.get_headers(data),
          body: Malla.Plugins.Httpd.get_body(data)
        })

      {:reply, [code: 200, body: body, server: "MyTest"]}
    end
  end
  ```
  Configuration must be placed under `:malla_httpd` key.

  Currently, only recognized options are:
  - port (default will be 3500)
  - name (mandatory if you use several 'malla_httpd' entries, default will be "default")

  This plugin accepts multiple 'malla_httpd' entries, starting multiple servers.
  Use `Malla.Service.reconfigure/2` to replace the full `:malla_httpd` configuration at runtime;
  if the value changes, the plugin will restart its supervised children.

  For Kubernetes-style lifecycle endpoints (`/is_live`, `/is_ready`, `/stop`,
  `/node`) wired to Malla's readiness and drain callbacks, see
  `Malla.Plugins.Httpd.Lifecycle`.

# `method`

```elixir
@type method() :: :get | :post | :put | :head | :delete
```

# `request_data`

```elixir
@type request_data() ::
  {:mod_cb, init_data :: term(), data :: term(), socket_type :: term(),
   socket :: term(), config_db :: term(), method :: term(),
   absolute_uri :: term(), request_uri :: term(), http_version :: term(),
   request_line :: term(), parsed_header :: term(), entity_body :: term(),
   connection :: term()}
```

Opaque request data handed to `c:httpd_request/4`; use `get_headers/1` and `get_body/1` to inspect it.

# `response`

```elixir
@type response() ::
  {:code, pos_integer()}
  | {:server, binary()}
  | {:accept_ranges, binary()}
  | {:allow, binary()}
  | {:cache_control, binary()}
  | {:content_MD5, binary()}
  | {:content_encoding, binary()}
  | {:content_language, binary()}
  | {:content_length, binary()}
  | {:content_location, binary()}
  | {:content_range, binary()}
  | {:content_type, binary()}
  | {:date, binary()}
  | {:etag, binary()}
  | {:expires, binary()}
  | {:last_modified, binary()}
  | {:location, binary()}
  | {:pragma, binary()}
  | {:retry_after, binary()}
  | {:body, binary()}
```

# `httpd_request`

```elixir
@callback httpd_request(String.t(), method(), String.t(), request_data()) ::
  {:reply, [response()]}
```

Callback invoked for every incoming request.

## Arguments

- `name` — the `:name` of the `:malla_httpd` entry that received the request
  (as a `String.t()`, e.g. `"default"`, `"metrics"`, `"probes"`). Useful to
  dispatch differently when a service exposes several listeners.
- `method` — HTTP method, one of `:get`, `:post`, `:put`, `:head`, `:delete`.
- `path` — request path as a `String.t()` (e.g. `"/metrics"`), including any
  query string.
- `data` — opaque `request_data` record; use `get_headers/1` to obtain a list
  of `{name, value}` string pairs and `get_body/1` to obtain the raw request
  body as a `String.t()`.

## Return value

Must return `{:reply, response}` where `response` is a keyword list built
from the entries below. Every value is a `binary` except `:code`, which is
a `pos_integer`. All entries are optional; unspecified entries default to
the server's usual behaviour (e.g. `:code` defaults to `200` when a `:body`
is present).

Status and body:
- `:code` — HTTP status code, e.g. `200`, `404`, `500`.
- `:body` — response body bytes, e.g. `"hello"` or an encoded payload.

Response headers (values are the raw header string):
- `:server` — `Server` header, e.g. `"MyApp/1.0"`.
- `:accept_ranges` — `Accept-Ranges`, e.g. `"bytes"` or `"none"`.
- `:allow` — `Allow`, e.g. `"GET, HEAD, OPTIONS"`.
- `:cache_control` — `Cache-Control`, e.g. `"no-cache"` or `"max-age=3600"`.
- `:content_MD5` — `Content-MD5`, base64-encoded digest, e.g. `"Q2hlY2s="`.
- `:content_encoding` — `Content-Encoding`, e.g. `"gzip"`.
- `:content_language` — `Content-Language`, e.g. `"en"`.
- `:content_length` — `Content-Length` in bytes as a string, e.g. `"1024"`.
- `:content_location` — `Content-Location`, e.g. `"/index.en.html"`.
- `:content_range` — `Content-Range`, e.g. `"bytes 0-499/1234"`.
- `:content_type` — `Content-Type`, e.g. `"application/json"` or
  `"text/plain; charset=utf-8"`.
- `:date` — `Date` in RFC 7231 format, e.g. `"Tue, 15 Nov 2024 08:12:31 GMT"`.
- `:etag` — `ETag`, e.g. `~s("abc123")`.
- `:expires` — `Expires` in RFC 7231 format,
  e.g. `"Thu, 01 Dec 2024 16:00:00 GMT"`.
- `:last_modified` — `Last-Modified` in RFC 7231 format,
  e.g. `"Wed, 21 Oct 2024 07:28:00 GMT"`.
- `:location` — `Location`, e.g. `"/login"` or `"https://example.com/"`.
- `:pragma` — `Pragma`, e.g. `"no-cache"`.
- `:retry_after` — `Retry-After` as seconds or HTTP-date, e.g. `"120"`.

# `get_body`

```elixir
@spec get_body(
  {:mod_cb, init_data :: term(), data :: term(), socket_type :: term(),
   socket :: term(), config_db :: term(), method :: term(),
   absolute_uri :: term(), request_uri :: term(), http_version :: term(),
   request_line :: term(), parsed_header :: term(), entity_body :: charlist(),
   connection :: term()}
) :: String.t()
```

Utility to call from `c:httpd_request/4` to get the body body

# `get_headers`

```elixir
@spec get_headers(request_data()) :: [{String.t(), String.t()}]
```

Utility to call from `c:httpd_request/4` callback to get headers

---

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