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

Copy Markdown View Source

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

method()

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

request_data()

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

response()

@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

httpd_request(t, method, t, request_data)

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

Functions

get_body(arg)

@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

get_headers(arg)

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

Utility to call from httpd_request/4 callback to get headers