Malla

Malla is a framework for developing distributed services in Elixir. It simplifies distributed service development through a plugin-based architecture with compile-time callback chaining, automatic service discovery across nodes, and minimal "magic" to keep systems understandable.

Why Malla?

Developing distributed services can be challenging. Malla simplifies the process by handling much of the boilerplate while giving you the flexibility to implement custom behaviors and use any libraries without enforced constraints.

Malla is built on years of production experience running critical systems. This real-world battle testing has shaped its design to prioritize what matters most: simplicity, safe evolution, and practical flexibility.

Not Just for Distributed Systems

While Malla excels at distributed computing, you don't need a cluster to benefit from it. On a single node, Malla gives you a plugin-based service architecture with compile-time callback chaining, runtime plugin management (add, remove, or reconfigure plugins without restarting), service lifecycle control, and built-in observability. If you need structured, evolvable services with runtime flexibility — even on a single BEAM instance — Malla has you covered. Distribution is there when you need it, but the service-management and runtime capabilities stand on their own.

Key Principles

• Simplicity and Readability First: Production experience has taught us that keeping code simple and easy to understand is critical for long-term maintainability. Malla prioritizes straightforward, readable code over clever abstractions. The plugin architecture promotes focused code where each plugin handles a single concern. Compile-time callback chains mean no runtime complexity.
• Safe Evolution Through Plugins: Add new functionality or modify behavior without touching existing code. Plugins compose transparently, following the Open/Closed Principle. This reduces risk in production deployments—deactivate problematic plugins on the fly without requiring a full system restart.
• No Technology Lock-In: Malla has little friction with other libraries and integrates with your existing codebase incrementally. All built-in and future released plugins are optional. Use Malla for only part of your system—start with a single distributed service and expand gradually.

Core Features

• Plugin-Based Architecture: Compose behavior through plugins with compile-time callback chaining (zero runtime overhead). Plugins can be added and removed at runtime, which is a game-changer for production operations.
• Automatic Service Discovery: Services automatically discover each other across the cluster.
• Distributed RPC: Call service functions on remote nodes transparently.
• Service Lifecycle Management: Control service state with admin statuses (:active, :pause, :inactive) and monitor their running status.
• Dynamic Runtime Control: Modify service behavior and plugin configurations in real-time. Deactivate problematic plugins on the fly without requiring a full system restart.
• Extensive Documentation and Test Coverage: Every major feature is documented and included in a test.

Optional Included Utilities

• Status and Error Management: Built-in status tracking and error handling.
• Process Registry: Service-level process registration.
• Tracing and Logging: An instrumentation interface for observability.
• Configuration Management: Multi-layer configuration with deep merging.
• Storage: ETS-based storage per service.

Installation

Prerequisites

• Elixir 1.17 or later
• Erlang/OTP 26 or later

Adding Malla to Your Project

Add malla to your list of dependencies in mix.exs:

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

Then run mix deps.get to install the dependency.

Quick Start

1. Define a service with use Malla.Service, global: true to make it discoverable across the cluster.

   defmodule MyService do
     use Malla.Service, 
       global: true
       
     # A callback that can be called remotely
     defcb fun1(a) do
       {:ok, %{you_said: a}}
     end
   end

2. Start the service on one node.

   iex --sname node1 --cookie my_secret -S mix

   iex(node1@hostname)> MyService.start_link()

3. Connect from another node and call the service. Malla handles the remote call transparently.

   iex --sname node2 --cookie my_secret -S mix

   iex(node2@hostname)> Node.connect(:"node1@hostname")
   true
   iex(node2@hostname)> MyService.fun1("hello from node2")
   {:ok, %{you_said: "hello from node2"}}

Interactive Tutorials

The best way to learn Malla is through our interactive LiveBook tutorials:

• Getting Started Tutorial - Learn the fundamentals through building a calculator service:

  • Create services and publish APIs
  • Extract functionality into reusable plugins
  • Compose plugins to modify behavior
  • Reconfigure services at runtime

• Distributed Services Tutorial - Master distributed computing with Malla:

  • Set up a cluster with multiple LiveBook sessions
  • Create services that communicate across nodes
  • Experience automatic service discovery
  • Implement bidirectional service communication

Open these tutorials in LiveBook for an interactive, hands-on learning experience.

Architecture Overview

Plugin System

Malla's architecture centers on a sophisticated plugin system where behavior is composed through callback chains resolved at compile time:

Your Service Module (Top of chain - highest priority)
    ↓ Custom business logic
    ↓ Can override any plugin behavior
    ↓
Your Plugins (Middleware layer)
    ↓ Authentication, logging, caching
    ↓ Can modify, observe, or block calls
    ↓
Malla.Plugins.Base (Bottom of chain - default behavior)
    • Always present
    • Provides fallback implementations

Key characteristics:

• Service modules (using Malla.Service) are themselves plugins.
• Dependencies form a hierarchy: Malla.Plugins.Base (bottom) → plugins → your service module (top).
• Each callback invocation walks the chain from top to bottom until a plugin returns something different than :cont.
• This process has zero runtime overhead, as all chains are resolved at compile time.

Distributed Services

Services marked as global: true automatically:

• Join the cluster-wide process group.
• Announce themselves to other nodes.
• Support automatic RPC routing with failover.
• Well-documented helper macros to make remote calls.

Use Cases

Malla is ideal for:

• Microservices Architecture: Build distributed microservices that discover and communicate with each other.
• Real-Time Systems: Create services that require low-latency communication across nodes.
• Scalable Applications: Horizontally scale services with automatic load balancing.
• Production Systems: Deploy on Kubernetes and other modern platforms with runtime plugin management.

Documentation

For a complete understanding of Malla's features, please see the full documentation in the guides directory.

The guides provide a comprehensive overview of:

• Introduction - Why Malla and core concepts
• Services - Service fundamentals and lifecycle
• Plugins - Understanding the plugin system
• Lifecycle Management - Service state and transitions
• Configuration - Multi-layer configuration system
• Distribution - Cluster setup and service discovery
• Observability - Tracing and monitoring
• Plugin Development - Creating custom plugins
• And more...

AI-Assisted Development

Malla ships with instruction files that help AI coding assistants (Claude Code, OpenAI Codex, Cursor, GitHub Copilot, etc.) generate correct Malla services and plugins.

If you use Malla as a dependency, add this line to your project's AI instruction file to teach your assistant about Malla patterns:

If you contribute to Malla itself, the AGENTS.md and CLAUDE.md files at the project root are automatically picked up by most AI coding tools.

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 more details.