Boundary

Boundary is a library which helps managing and restraining cross-module dependencies in Elixir projects. A few examples of the things you can do with boundary include:

Prevent invocations from the context layer to the web layer
Prevent invocations from the web layer to internal context modules
Prevent usage of Phoenix and Plug in the context layer
Limit usage of Ecto in the web layer to only Ecto.Changeset
Allow :mix modules to be used only at compile time

Warning

This library is experimental, untested, and unstable. Interface might change significantly in the future versions. The code is not well tested or optimized, so you might experience crashes, or significant slowdowns during compilation, especially in larger projects. In addition, be aware that Boundary loads the application and all of its dependencies (recursively) during compilation.

Documentation

For a detailed reference see docs for Boundary module and mix compiler.

Basic usage

To use this library, you first need to define the boundaries of your project. A boundary is a named group of one or more modules. Each boundary exports some (but not all!) of its modules, and can depend on other boundaries. During compilation, the boundary compiler will find and report all cross-module function calls which are not permitted according to the boundary configuration.

Example

Add boundary as a dependency in mix.exs:

defmodule MySystem.MixProject do
  use Mix.Project

  # ...

  defp deps do
    [
      {:boundary, "~> 0.5.0", runtime: false},
      # ...
    ]
  end

  # ...
end

The following code defines boundaries for a typical Phoenix based project generated with mix phx.new.

defmodule MySystem do
  use Boundary, deps: [], exports: []
  # ...
end

defmodule MySystemWeb do
  use Boundary, deps: [MySystem], exports: [Endpoint]
  # ...
end

defmodule MySystem.Application do
  use Boundary, top_level?: true, deps: [MySystem, MySystemWeb]
  # ...
end

The configuration above defines three boundaries: MySystem, MySystemWeb, and MySystem.Application.

Boundary modules are determined automatically from the boundary name. For example, the MySystem boundary contains the MySystem module, as well as any module whose name starts with MySystem. (e.g. MySystem.User, MySystem.User.Schema, ...).

The configuration specifies the following rules:

Modules residing in the MySystemWeb boundary are allowed to invoke functions from modules exported by the MySystem boundary.
Modules residing in the MySystem.Application namespace are allowed to invoke functions from modules exported by MySystem and MySystemWeb boundaries.

All other cross-boundary calls are not permitted.

Next, you need to add the mix compiler:

defmodule MySystem.MixProject do
  use Mix.Project

  def project do
    [
      compilers: [:boundary, :phoenix, :gettext] ++ Mix.compilers(),
      # ...
    ]
  end

  # ...
end

Boundary rules are validated during compilation. For example, if we have the following code:

defmodule MySystem.User do
  def auth do
    MySystemWeb.Endpoint.url()
  end
end

The compiler will emit a warning:

$ mix compile

warning: forbidden call to MySystemWeb.Endpoint.url/0
  (calls from MySystem to MySystemWeb are not allowed)
  (call originated from MySystem.User)
  lib/my_system/user.ex:3

The complete working example is available here.

Because boundary is implemented as a mix compiler, it integrates seamlessly with editors which can work with mix compiler. For example, in VS Code with Elixir LS:

Roadmap

validate calls to external deps (e.g. preventing Ecto usage from MySystemWeb, or Plug usage from MySystem)
support compile time vs runtime deps
support nested boundaries (defining internal boundaries within a boundary)
support Erlang modules

License

MIT

gshaw / boundary