Hex.pm Hex Docs License

Malla is a framework for developing distributed services in Elixir. A service is a module whose behavior is composed from plugins through callback chains that are resolved when the code is compiled. Services running on different Erlang nodes find each other and can call each other. The framework keeps the moving parts few and visible.

Malla is also useful on a single node: it gives you plugin-based services, a lifecycle with admin and running statuses, and plugins that can be added, removed or reconfigured while the service runs. Distribution is there when you need it.

Installation

Add malla to the dependencies in mix.exs. Check hex.pm/packages/malla for the latest version:

def deps do
  [
    {:malla, "~> 0.1"}
  ]
end

Then run mix deps.get. Malla requires Elixir 1.17 or later.

A first service, started and called from iex -S mix:

defmodule MyService do
  use Malla.Service

  defcb greet(name), do: {:ok, "Hello, #{name}"}
end

iex> MyService.start_link()
iex> MyService.greet("world")
{:ok, "Hello, world"}

The Quick Start continues from here, including a second node.

Why Malla?

  • Plain code. Plugins are modules with ordinary functions. Which implementation of a callback runs is decided at compile time and can be inspected with MyService.service().plugin_chain.
  • Change behavior by composition. A plugin adds or modifies behavior without touching existing code. Plugins can be added to, or removed from, a running service.
  • Incremental adoption. All plugins are optional. You can use Malla for one service and leave the rest of your application as it is.

Malla is built on production experience running distributed systems in Elixir.

At a Glance

  • Plugin-based services. Callbacks (defcb) are chained across the service and its plugins. The chain is resolved at compile time into direct function calls: low overhead, and no runtime lookup of who implements a callback. The chain is rebuilt when plugins are added or removed at runtime.
  • Runtime plugin management. Add, remove and reconfigure plugins in a running service.
  • Service discovery. Services declared with global: true are announced to the cluster through :pg. Calls reach a node running the service; if a node answers that the service is not available, the next node is tried.
  • Service lifecycle. Admin status (:active, :pause, :inactive), running status, readiness and drain callbacks.
  • Optional building blocks. Status and error normalization, a request protocol with trace propagation, an instrumentation API (spans, logs, metrics; the default implementation logs through Logger and emits :telemetry events), a small HTTP admin server with Kubernetes probes, per-service ETS storage and a process registry.

See the Livebook Getting Started Tutorial and Distributed Tutorial.

Documentation

Full documentation is available on HexDocs.

Getting Started

GuideDescription
IntroductionWhat Malla is, core concepts and how the pieces fit
Quick StartCreate your first service, then call it from a second node
GlossaryTerms used across the documentation
Getting started tutorialInteractive Livebook tutorial
Distributed TutorialMulti-node Livebook tutorial

Core Concepts

GuideDescription
ServicesService fundamentals and the defcb macro
PluginsThe plugin system, dependencies and ordering
CallbacksHow callback chains work
LifecycleService statuses and transitions
ConfigurationConfiguration layers and every config :malla key
ReconfigurationChanging configuration and plugins at runtime
Storage and StatePer-service ETS table, process registry, node-wide store

Distribution

GuideDescription
Cluster SetupConnecting nodes, manually or through DNS
Service DiscoveryHow nodes find the services of other nodes
Remote CallsMalla.remote/4, the call macro and virtual modules

Optional Plugins

GuideDescription
Request HandlingRequest protocol with trace propagation, status normalization and interception
Status HandlingMalla.Status and Malla.Plugins.Status
TracingThe instrumentation API and how to plug in a tracer
HTTP Admin ServerProbes, drain endpoint and your own admin routes

Development and Operations

GuideDescription
Plugin DevelopmentA complete worked plugin
TestingTesting services, plugins and multi-node scenarios
TroubleshootingSymptoms, causes and how to inspect a service
DeploymentReleases, clustering and Kubernetes

Part of the NetKubes Platform

Malla is the foundation of NetKubes, a platform for building distributed Elixir applications. Malla works as a standalone framework.

AI-Assisted Development

Malla ships with instruction files for AI coding assistants. If you use Malla as a dependency, add this to your project's AI instruction file:

ToolFileAdd this line
Claude CodeCLAUDE.md@deps/malla/priv/ai/AGENTS.md
OpenAI CodexAGENTS.md@deps/malla/priv/ai/AGENTS.md
Cursor.cursor/rules/malla.mdCopy contents of deps/malla/priv/ai/AGENTS.md

Contributing

Contributions are welcome! Please feel free to open an issue or submit a pull request.

License

Malla is released under the Apache 2.0 License. See the LICENSE file for details.