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, 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.
Summary
Types
Opaque request data handed to httpd_request/4; use get_headers/1 and get_body/1 to inspect it.
Callbacks
Callback invoked for every incoming request.
Functions
Utility to call from httpd_request/4 to get the body body
Utility to call from httpd_request/4 callback to get headers
Types
@type method() :: :get | :post | :put | :head | :delete
@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 httpd_request/4; use get_headers/1 and get_body/1 to inspect it.
@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()}
Callbacks
@callback httpd_request(String.t(), method(), String.t(), request_data()) :: {:reply, [response()]}
Callback invoked for every incoming request.
Arguments
name— the:nameof the:malla_httpdentry that received the request (as aString.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 aString.t()(e.g."/metrics"), including any query string.data— opaquerequest_datarecord; useget_headers/1to obtain a list of{name, value}string pairs andget_body/1to obtain the raw request body as aString.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—Serverheader, 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-Lengthin 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—Datein RFC 7231 format, e.g."Tue, 15 Nov 2024 08:12:31 GMT".:etag—ETag, e.g.~s("abc123").:expires—Expiresin RFC 7231 format, e.g."Thu, 01 Dec 2024 16:00:00 GMT".:last_modified—Last-Modifiedin 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-Afteras seconds or HTTP-date, e.g."120".
Functions
@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 httpd_request/4 to get the body body
@spec get_headers(request_data()) :: [{String.t(), String.t()}]
Utility to call from httpd_request/4 callback to get headers