Repository navigation
Malla is a framework for distributed services in Elixir. A service is a module built from plugins whose callbacks are chained when the code is compiled, so a call costs a few function calls with no runtime lookup. Services on different Erlang nodes find each other and call each other, with failover when a node does not run the service. It is just as useful on a single node, where it gives you plugin-based services, a managed lifecycle, and plugins that can be added, removed or reconfigured while the service runs.
0.1.0 is the first stable release.
def deps do
[{:malla, "~> 0.1"}]
endDocs: https://hexdocs.pm/malla. Start with the Quick Start or the Getting Started Livebook.
Highlights
- Plugins and callback chains. Behaviour is composed with
defcbcallbacks that run from the service down through its plugins until one of them answers. Chains are resolved at compile time. - Deterministic plugin order. Plugins that do not depend on each other run in the order of
plugins:. Before, that order could change between Elixir/OTP versions. - Runtime plugin changes.
add_plugin/3,del_plugin/2andreconfigure/2rebuild the chain of a running service without restarting it. A change that fails is rolled back. - Service lifecycle. A service has an admin status (
:active,:pause,:inactive) and a running status. A failed service keeps retrying its plugins. Readiness and drain are callbacks, anddrain_all_local/0drains the services of a node in:priorityorder. - Distribution. Services with
global: trueare discovered across the cluster.Malla.remote/4and thecallmacro route a call to a node that runs the service. Its default timeout is set withconfig :malla, :remote_timeout. - Optional plugins. Malla includes plugins for request handling (
Malla.Request), status normalization (Malla.Status), tracing (Malla.Tracer) and an HTTP admin server (Malla.Plugins.Httpd). WithMalla.Plugins.Httpd.Lifecyclethat server answers Kubernetes-style/is_live,/is_readyand/stop(drain). - Documentation. 21 guides, from concepts to testing, plugin development, troubleshooting and deployment. There are also runnable Livebook tutorials for one and two nodes.
Upgrading from 0.0.1-rc.2
The last version on Hex was 0.0.1-rc.2. These changes may need code changes:
- Plugin groups run in the documented order. For
plugins: [A, B, C]in onegroup:, plugins startA → B → Cand callbacks runC → B → A. It was the reverse: if you relied on it, reverse your list. - Prefixed error atom.
Malla.NodeandMalla.remote/4answer{:error, :malla_service_not_available}. Code matching:service_not_availableon their result must use the new atom. The public status string is still"service_not_available". - No mixed clusters with rc.2. Nodes on 0.0.1-rc.2 or earlier still answer the unprefixed atom, and newer nodes do not fail over when they get it. Upgrade every node of the cluster together.
priv/ai/MIGRATION.mdin the package is a step-by-step guide for older code, meant for AI coding assistants. Use it if you are coming from a version before the Hex releases.
Also new since rc.2:
:priorityoption ofuse Malla.Service.Malla.Service.get_all_local/0.- Redaction of secrets in request logs (
Malla.Util.redact/1). Malla.Util.validate_app!/2, withnimble_optionsas an optional dependency.- Remote exceptions are no longer exposed in public statuses.
- Several lifecycle fixes when a plugin fails to start or a reconfiguration is refused.
See the CHANGELOG for the full list.
Requirements
Elixir 1.17 or later. CI runs on Elixir 1.17 to 1.20 with OTP 27 to 29.