Exaop

A minimal elixir library for aspect-oriented programming.

Installation

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

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

Usage

Unlike common AOP patterns, Exaop does not introduce any additional behavior to existing functions, as it may bring complexity and make the control flow obscured. Elixir developers prefer explicit over implicit, thus invoking the cross-cutting behavior by simply calling the plain old function generated by pointcut definitions is better than using some magic like module attributes and macros to decorate and weave a function.

Hello World

Use Exaop in a module, then define some pointcuts to separate the cross-cutting logic:

defmodule Foo do
  use Exaop

  check :validity
  set :compute
end

When you compile the file, the following warnings would occur:

warning: function check_validity/3 required by behaviour Foo.ExaopBehaviour is not implemented (in module Foo)
  foo.exs:1: Foo (module)

warning: function set_compute/3 required by behaviour Foo.ExaopBehaviour is not implemented (in module Foo)
  foo.exs:1: Foo (module)

It reminds you to implement the corresponding callbacks required by your pointcut definitions:

defmodule Foo do
  use Exaop

  check :validity
  set :compute

  @impl true
  def check_validity(%{b: b} = _params, _args, _acc) do
    if b == 0 do
      {:error, :divide_by_zero}
    else
      :ok
    end
  end

  @impl true
  def set_compute(%{a: a, b: b} = _params, _args, acc) do
    Map.put(acc, :result, a / b)
  end
end

A function __inject__/2 is generated in the above module Foo. When it is called, the callbacks are triggered in the order defined by your pointcut definitions.

Throughout the execution of the pointcut callbacks, an accumulator is passed and updated after running each callback. The execution process may be halted by a return value of a callback.

If the execution is not halted by any callback, the final accumulator value is returned by the __inject__/2 function. Otherwise, the return value of the callback that terminates the entire execution process is returned.

In the above example, the value of the accumulator is returned if the check_validity is passed:

iex> params = %{a: 1, b: 2}
iex> initial_acc = %{}
iex> Foo.__inject__(params, initial_acc)
%{result: 0.5}

The halted error is returned if the execution is aborted:

iex> params = %{a: 1, b: 0}
iex> initial_acc = %{}
iex> Foo.__inject__(params, initial_acc)
{:error, :divide_by_zero}

Pointcut definitions

check :validity
set :compute

We've already seen the pointcut definitions in the example before. check_validity/3 and set_compute/3 are the pointcut callback functions required by these definitions.

Additional arguments can be set:

check :validity, some_option: true
set :compute, {:a, :b}

Pointcut callbacks

Naming and arguments

All types of pointcut callbacks have the same function signature. Each callback function following the naming convention in the example, using an underscore to connect the pointcut type and the following atom as the callback function name.

Each callback has three arguments and each argument can be of any Elixir term.

The first argument of the callback function is passed from the first argument of the caller __inject__/2. The argument remains unchanged in each callback during the execution process.

The second argument of the callback function is passed from its pointcut definition, for example, set :compute, :my_arg passes :my_arg as the second argument of its callback function set_compute/3.

The third argument is the accumulator. It is initialized as the second argument of the caller __inject__/2. The value of accumulator is updated or remains the same after each callback execution, depending on the types and the return values of the callback functions.

Types and behaviours

Each kind of pointcut has different impacts on the execution process and the accumulator.

check
- does not change the value of the accumulator.
- the execution of the generated function is halted if its callback return value matches the pattern {:error, _}.
- the execution continues if its callback returns :ok.
set
- does not halt the execution process.
- sets the accumulator to its callback return value.
preprocess
- allows to change the value of the accumulator or halt the execution process.
- the execution of the generated function is halted if its callback return value matches the pattern {:error, _}.
- the accumulator is updated to the wrapped acc if its callback return value matches the pattern {:ok, acc}.

View documentation of these macros for details.

A more in-depth example

Exaop is ready for production and makes complex application workflows simple and self-documenting. In practice, we combine it with some custom simple macros as a method to separate cross-cutting concerns and decouple business logic. Note that we do not recommend overusing it, it is only needed when the workflow gets complicated, and the pointcuts should be strictly restricted to the domain of cross-cutting logic, not the business logic body itself.

Here's a more complex example, a wallet balance transfer. The configuration loading, context setting and transfer validations are separated, but the main transfer logic remains untouched. The example also introduces an external callback, which is defined in a module other than its pointcut definition.

defmodule Wallet do
  @moduledoc false

  use Exaop
  alias Wallet.AML
  require Logger

  ## Definitions for cross-cutting concerns

  set :config, [:max_allowed_amount, :fee_rate]
  set :accounts

  check :amount, guard: :positive
  check :amount, guard: {:lt_or_eq, :max_allowed_amount}
  check :recipient, :not_equal_to_sender
  check AML

  set :fee
  check :balance

  @doc """
  A function injected by explicitly calling __inject__/2 generated by Exaop.
  """
  def transfer(%{from: _, to: _, amount: _} = info) do
    info
    |> __inject__(%{})
    |> handle_inject(info)
  end

  defp handle_inject({:error, _} = error, info) do
    Logger.error("transfer failed", error: error, info: info)
  end

  defp handle_inject(_acc, info) do
    # Put the actual transfer logic here:
    # Wallet.transfer!(acc, info)
    Logger.info("transfer validated and completed", info: info)
  end

  ## Setters required by the above concern definitions.

  @impl true
  def set_accounts(%{from: from, to: to}, _args, acc) do
    balances = %{"Alice" => 100, "Bob" => 30}

    acc
    |> Map.put(:sender_balance, balances[from])
    |> Map.put(:recipient_balance, balances[to])
  end

  @impl true
  def set_config(_params, keys, acc) do
    keys
    |> Enum.map(&{&1, Application.get_env(:my_app, &1, default_config(&1))})
    |> Enum.into(acc)
  end

  defp default_config(key) do
    Map.get(%{fee_rate: 0.01, max_allowed_amount: 1_000}, key)
  end

  @impl true
  def set_fee(%{amount: amount}, _args, %{fee_rate: fee_rate} = acc) do
    Map.put(acc, :fee, amount * fee_rate)
  end

  ## Checkers required by the above concern definitions.

  @impl true
  def check_amount(%{amount: amount}, args, acc) do
    args
    |> Keyword.fetch!(:guard)
    |> do_check_amount(amount, acc)
  end

  defp do_check_amount(:positive, amount, _acc) do
    if amount > 0 do
      :ok
    else
      {:error, :amount_not_positive}
    end
  end

  defp do_check_amount({:lt_or_eq, key}, amount, acc)
       when is_atom(key) do
    max = Map.fetch!(acc, key)

    if max && amount <= max do
      :ok
    else
      {:error, :amount_exceeded}
    end
  end

  @impl true
  def check_recipient(%{from: from, to: to}, :not_equal_to_sender, _acc) do
    if from == to do
      {:error, :invalid_recipient}
    else
      :ok
    end
  end

  @impl true
  def check_balance(%{amount: amount}, _args, %{fee: fee, sender_balance: balance}) do
    if balance >= amount + fee do
      :ok
    else
      {:error, :insufficient_balance}
    end
  end
end

defmodule Wallet.AML do
  @moduledoc """
  A module defining external Exaop callbacks.
  """

  @behaviour Exaop.Checker

  @aml_blacklist ~w(Trump)

  @impl true
  def check(%{from: from, to: to}, _args, _acc) do
    cond do
      from in @aml_blacklist ->
        {:error, {:aml_check_failed, from}}

      to in @aml_blacklist ->
        {:error, {:aml_check_failed, to}}

      true ->
        :ok
    end
  end
end

License

The MIT License

nobrick/exaop