Boundary is a library which helps managing and restraining cross-module dependencies in Elixir projects.
Highly experimental, untested, and unstable.
For a detailed reference see moduledoc here and here.
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.
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, 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 theMySystem
boundary. - Modules residing in the
MySystem.Application
namespace are allowed to invoke functions from modules exported byMySystem
andMySystemWeb
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: [:phoenix, :gettext] ++ Mix.compilers() ++ [:boundary],
# ...
]
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)
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:
- support nested boundaries (defining internal boundaries within a boundary)
- validate calls to external deps (e.g. preventing
Ecto
usage fromMySystemWeb
, orPlug
usage fromMySystem
) - support Erlang modules