Malla

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?

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

At a Glance

See the Livebook Getting Started Tutorial and Distributed Tutorial.

Documentation

Full documentation is available on HexDocs.

Getting Started

Guide Description
Introduction What Malla is, core concepts and how the pieces fit
Quick Start Create your first service, then call it from a second node
Glossary Terms used across the documentation
Getting started tutorial Interactive Livebook tutorial
Distributed Tutorial Multi-node Livebook tutorial

Core Concepts

Guide Description
Services Service fundamentals and the defcb macro
Plugins The plugin system, dependencies and ordering
Callbacks How callback chains work
Lifecycle Service statuses and transitions
Configuration Configuration layers and every config :malla key
Reconfiguration Changing configuration and plugins at runtime
Storage and State Per-service ETS table, process registry, node-wide store

Distribution

Guide Description
Cluster Setup Connecting nodes, manually or through DNS
Service Discovery How nodes find the services of other nodes
Remote Calls Malla.remote/4, the call macro and virtual modules

Optional Plugins

Guide Description
Request Handling Request protocol with trace propagation, status normalization and interception
Status Handling Malla.Status and Malla.Plugins.Status
Tracing The instrumentation API and how to plug in a tracer
HTTP Admin Server Probes, drain endpoint and your own admin routes

Development and Operations

Guide Description
Plugin Development A complete worked plugin
Testing Testing services, plugins and multi-node scenarios
Troubleshooting Symptoms, causes and how to inspect a service
Deployment Releases, 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:

Tool File Add this line
Claude Code CLAUDE.md @deps/malla/priv/ai/AGENTS.md
OpenAI Codex AGENTS.md @deps/malla/priv/ai/AGENTS.md
Cursor .cursor/rules/malla.md Copy 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.